Merge pull request #498 from IgniteUI/radomirchev/skills-structure-aeo-geo-seo-rules

update(*): skills-structure-content

Author: IMinchev64

.ai/skills/CHANGELOG.md

@@ -0,0 +1,100 @@
+# igniteui doc-skill set · changelog
+
+## v3 · 2026-08-14
+
+Restructures both skills to the routing-hub + references architecture used by the
+`IgniteUI/igniteui-angular` repo skills (SKILL.md = router with a Task → Reference table; all
+evolving rules live in `references/`). **No rule content changed** — v2's rules were moved, not
+edited; two stale cross-pointers were fixed in the move. Completes D2-03 stage 2 (physical
+deduplication) and adds the set-level README. Whole set bumped to v3 (uniform version line,
+including content-unchanged files, per the blog-creator convention).
+
+### Changed
+
+| Change | File(s) |
+|---|---|
+| igniteui-topic-frontmatter split: SKILL.md becomes a router (scope, audit-first mode, task table, hard boundaries); the field checks + severity ladder move to `references/audit-rules.md`; report shape + apply procedure move to `references/report-format.md`. `description` unchanged (adapter byte-match preserved). | igniteui-topic-frontmatter/* |
+| igniteui-doc-topics slimmed: SKILL.md keeps identity, two modes, compass, composite principle, task table, grounding boundaries. Create steps 1–7 (6a–6e) + the category/index structure move to `references/create-workflow.md`; the 5 audit-workflow steps move into `audit-rubric.md`. `description` unchanged. | igniteui-doc-topics/SKILL.md, references/create-workflow.md, references/audit-rubric.md |
+| Dedup (D2-03 stage 2): the section→mode map is no longer restated in SKILL.md — it is the "Diátaxis mode" column of house-style's canonical section table; SKILL.md keeps only the one-section-one-mode rule and the concrete mode-bleed examples. The category blueprint now lives in house-style + create-workflow only. Stale pointers fixed (house-style intro pointed at a SKILL.md map that moved; body-support bullet pointed at "Create workflow step 4" which now lives in create-workflow.md). | igniteui-doc-topics/SKILL.md, references/house-style.md |
+| Set-level README.md added: human-readable intent, file map, authority chain, and the five-step update procedure (edit references not routers; uniform version bump; adapter byte-match; changelog entry; resolve ‹VERIFY› by pre-committed outcome). | README.md |
+| Set-wide version line: every file now carries `Version: v3 · 2026-08-14 · igniteui doc-skill set`, including content-unchanged house-style and diataxis-cheatsheet (the cheatsheet gains its first version line). | all files |
+
+### Unchanged
+
+All v2 rule substance (E1–E9 with D2 amendments, D2-01…11 fixes), all open ‹VERIFY› items and their
+owners (see the v2 entry below), and both skill `description` fields.
+
+---
+
+## v2 · 2026-08-14
+
+Applies the D5 frontmatter patch v1 (E1–E9) as ratified by D2 (D2 review v1.1, 2026-08-14, transfer
+matrix v1 Option A) with D2's amendments, plus the D2 "do now" wave. Three wait-line items were
+pulled forward (D2-08, D2-09, D2-11) because the marginal cost inside a full edit pass was zero,
+the same precedent as blog-creator v3. Finding IDs reference the D5 review (D5-22…31, patch edits
+E1–E9) and the D2 review v1.1 (D2-01…12).
+
+Files changed: `igniteui-topic-frontmatter/SKILL.md`, `igniteui-doc-topics/SKILL.md`,
+`igniteui-doc-topics/references/house-style.md`, `igniteui-doc-topics/references/audit-rubric.md`,
+both `.claude/skills/*/SKILL.md` adapters. `diataxis-cheatsheet.md` is unchanged (no findings).
+
+### Applied
+
+| Finding | Change | File(s) |
+|---|---|---|
+| E1 / D5-24 + D2 amendment | Title rule split per doc set: xplat keeps `{ComponentTitle}`; Angular target `"Angular <Component> Component"` within ~60 query-relevant chars, no hand-coded suffixes pending `‹VERIFY: Angular layout title suffix behavior›`, with pre-committed outcomes for both branches (`\| Ignite UI` standardized if the layout appends nothing). Blog banned-phrase set merged in. | frontmatter SKILL.md |
+| E2 / D5-26 | Description bar raised: definition-first ("X is a … that …"), not imperative CTA; complete sentences; no ellipsis truncation. | frontmatter SKILL.md, house-style |
+| E3 / D5-23 + D2 amendment | `llms.description` defines the component, not the page: subject noun names product + component, no pronouns, no list-dumps, no page-referential phrasing; quotability test at accept time. One-definition rule added: llms.description ≈ H1 lead ≈ llms-manifest entry (`‹VERIFY: manifest source field›`). | frontmatter SKILL.md, house-style |
+| E4 / D5-22 | New required check: cross-field consistency (title / description / llms.description / keywords / H1 / lead sentence tell one story, same entities, same capability list). | frontmatter SKILL.md, house-style |
+| E5 / D5-25 | New required check: entity terminology in metadata, bound to the shared terminology table. | frontmatter SKILL.md |
+| E6 / D5-27 | New required check: body support for every metadata claim; frontmatter generated from the finished body. | frontmatter SKILL.md, house-style |
+| E7 / D5-28 | `keywords` coherence made testable: every keyword (or token-resolved form) appears in the body. | frontmatter SKILL.md |
+| E8 / D5-30 | `mentionedTypes` scoped: Angular occurrences tolerated, not required, pending `‹VERIFY: does the Angular pipeline consume mentionedTypes?›`. | frontmatter SKILL.md |
+| E9 / D5-31 | Schema linkage named in Scope: frontmatter bars are schema bars; FAQPage (if emitted) sources visible FAQ content verbatim (`‹VERIFY: schema pipeline nodes/fields›`). | frontmatter SKILL.md |
+| E-10 (D2 §2) | Title character budget in Severity: non-query terms pushing query terms past ~60-char truncation = Error; query-relevant portion >~60 = Warning. | frontmatter SKILL.md |
+| D2-01 | Contradiction fixed: reconciliation table no longer maps "Known Limitations" to Troubleshooting; drifted variants map to the required **Known Limitations** section, with the conditional Troubleshooting placement noted. | house-style |
+| D2-02 | Create step 4 rewritten "Write frontmatter first" → "Scaffold frontmatter": convention-fixed fields before the body; description / llms.description / keywords / mentionedTypes / relatedComponents generated from the finished body, then the frontmatter skill's cross-field and body-support checks run. Resolves the companion-skill contradiction with E6 / matrix row 11. | doc-topics SKILL.md |
+| D2-03 stage 1 | Single-sourcing declared: house-style "File format & frontmatter" is the normative field contract; both SKILL.mds reference it. Version lines added to all changed files; adapter `description` byte-match rule stated in both adapters and both canonicals. Shared field bars synced so no copy contradicts another. | all changed files |
+| D2-04 / matrix row 5 | FAQ answer shape bound: 2–4 self-contained sentences quotable without the question; fan-out question patterns (licensing, version support, migration, accessibility, "is X right for") added as authoring guidance. Rubric A11 extended. | house-style, audit-rubric |
+| D2-05 / matrix row 1 | Section leads name the component (and platform token): write-for-both rule 2 and rubric D3 extended. | house-style, audit-rubric |
+| D2-06 / matrix row 10 | Quotability test given a check ID: new D13 (H1 lead, section leads, FAQ answers, llms.description). | audit-rubric |
+| D2-07 / matrix row 8 | New E7: descriptive, entity-bearing anchor text on prose links; "click here"/bare URLs flagged. | audit-rubric |
+| D2-08 / matrix row 7 (pulled forward) | New house-style section "Entity terminology (canonical names)", a governed copy of the blog terminology table with provenance line "source: blog-creator product-context v4 · 2026-08-14". New rubric B6 for body-side entity drift. | house-style, audit-rubric |
+| D2-09 (pulled forward) | Table of contents added to house-style (>300-line reference, loaded on every create/audit). | house-style |
+| D2-10 | Routing boundary sentences added to both skill descriptions (frontmatter-only work → frontmatter skill; body/structure work → doc-topics skill). Adapters updated to byte-match. | both SKILL.mds, both adapters |
+| D2-11 (pulled forward) | Create step 6 split into passes 6a–6e; no rule content changed. | doc-topics SKILL.md |
+| Matrix row 4 (pre-commitment) | Rubric B4 carries the pending `‹VERIFY: layout H1/framework adjacency›` with both pre-committed outcomes, so the answer resolves the rule mechanically. | audit-rubric |
+
+### Deliberately not applied
+
+- **D2-03 stage 2** (physical deduplication of the field contract out of the frontmatter skill's
+  audit rules): batched with the next structural SKILL.md edit; stage 1's authority declaration and
+  synced wording carry the interim.
+- **D2-12** (verification-URL single-sourcing against RESOURCE-LIST): requires the RESOURCE-LIST
+  canonical-variant decision, which has no owner yet.
+- **Canonical-link policy enforcement** (D5-29): the skill still refuses to invent canonicals; the
+  enforcement text lands only after the policy's two `‹VERIFY›` items are answered (D2 review §5).
+- **Em-dash advisory** (matrix row 18): docs team's call; existing file style kept.
+- **Matrix rows 4 / E1 branch resolution**: `‹VERIFY›` placeholders ship in the files, as the
+  convention intends; the pre-committed outcomes are written next to them.
+
+### Open verification items (owners)
+
+1. `‹VERIFY: Angular layout title suffix behavior›` — docs team. Resolves E1's branch and the
+   Severity rule's application to Angular titles.
+2. `‹VERIFY: layout H1/framework adjacency, both doc sets›` — docs team. Resolves B4's direction.
+3. `‹VERIFY: schema pipeline — node types, source fields, FAQPage presence›` — docs team.
+4. `‹VERIFY: does the Angular pipeline consume mentionedTypes?›` — docs team.
+5. `‹VERIFY: llms-manifest source field›` — docs team. Resolves the one-definition rule's third leg.
+6. `‹VERIFY: what the layout emits when _canonicalLink is absent›` — docs team; if the answer is
+   "nothing", it preempts every queue (D2 review §5.1).
+7. Canonical-link policy pattern — D2 (draft exists in D2 review §5), docs team implements.
+
+### Deploy
+
+1. Replace the four `.ai` files and two `.claude` adapters in one commit; `git diff` is the review
+   surface.
+2. The adapter `description` fields must remain byte-identical to their canonicals — check on every
+   future edit (version lines are the interim control until a CI check exists).
+3. Next steps per the D2 cut line: D5 step 2 diffs are superseded by this apply; skill-creator eval
+   loop (pre-patch snapshots exist in git history) after this wave merges.

.ai/skills/README.md

@@ -0,0 +1,91 @@
+# Ignite UI doc-skill set — architecture and maintenance guide
+
+Version: v3 · 2026-08-14 · igniteui doc-skill set. This file is for humans; agents load the
+SKILL.md files. Change history: `CHANGELOG.md`.
+
+## What this is
+
+Two agent skills that keep Ignite UI documentation topics uniform, verified, and quotable by AI
+assistants:
+
+- **`igniteui-doc-topics`** — author or audit whole topics (component pages, concept overviews,
+  category indexes) against the Diátaxis-based house templates.
+- **`igniteui-topic-frontmatter`** — audit and normalize YAML frontmatter only (SEO titles, meta
+  descriptions, `llms.description`, keywords, canonical links), audit-first, never touching the body.
+
+The `.claude/skills/` copies are **thin adapters** for Claude: they carry the same `name` and
+`description` (the triggering surface) and redirect to the canonical `.ai/skills/` files. Other
+agents can consume the `.ai` skills directly.
+
+## Design intent (why it is structured this way)
+
+**SKILL.md is a routing hub; references carry the substance.** This follows the same pattern as the
+`IgniteUI/igniteui-angular` repo skills (e.g. `skills/igniteui-angular-components`): the SKILL.md
+holds only identity, scope, hard boundaries, and a Task → Reference table; every rule that can
+change over time lives in `references/`. Three reasons:
+
+1. **Progressive disclosure.** Agents always see the name + description; they load the SKILL.md
+   body when the skill triggers, and read only the reference files the task needs. Small router =
+   cheap trigger, precise loading.
+2. **Future-proofing.** Rules evolve (new checks, answered ‹VERIFY› items, template revisions);
+   the router does not. Day-to-day maintenance touches only `references/*.md`, so SKILL.md diffs are
+   rare and reviewable, and the adapters in `.claude/` almost never need to change.
+3. **Anti-drift.** Rules stated once, in one file, referenced everywhere else. The set learned this
+   the hard way (see CHANGELOG v2): the same contract stated in three places will disagree within a
+   week.
+
+## File map
+
+```
+.ai/skills/
+├── README.md            ← this file (humans)
+├── CHANGELOG.md         ← every change, mapped to review finding IDs
+├── igniteui-doc-topics/
+│   ├── SKILL.md                       ← router: modes, compass, composite principle, task table
+│   └── references/
+│       ├── house-style.md             ← THE normative source: blueprints, frontmatter contract,
+│       │                                 naming, entity terminology, verification workflow, voice
+│       ├── create-workflow.md         ← authoring steps 1–7 + category/index structure
+│       ├── audit-rubric.md            ← audit workflow + checks A–F + report format
+│       └── diataxis-cheatsheet.md     ← the four modes + the compass (reasoning layer)
+└── igniteui-topic-frontmatter/
+    ├── SKILL.md                       ← router: scope, audit-first mode, task table, boundaries
+    └── references/
+        ├── audit-rules.md             ← field-by-field quality checks + severity ladder
+        └── report-format.md           ← report shape + apply procedure
+
+.claude/skills/
+├── igniteui-doc-topics/SKILL.md          ← adapter (description byte-matches canonical)
+└── igniteui-topic-frontmatter/SKILL.md   ← adapter (description byte-matches canonical)
+```
+
+**Authority chain:** where any two files differ, `house-style.md` wins on content rules (it is the
+single normative field contract and template source); each skill's own references win on its
+operational procedure (severities, report shapes, workflow order). The frontmatter skill reads
+across into `igniteui-doc-topics/references/house-style.md` deliberately — one contract, two
+consumers.
+
+## How to update the set
+
+1. **Edit the reference file**, not the router. New check → `audit-rules.md` or `audit-rubric.md`;
+   template change → `house-style.md`; workflow change → `create-workflow.md`. Touch a SKILL.md only
+   when scope, boundaries, or routing genuinely change.
+2. **Bump the set version line in every file** (`Version: vN · date · igniteui doc-skill set`) —
+   all files move together, even content-unchanged ones. A mismatched version line is the drift
+   alarm; treat it as a stop sign.
+3. **Keep adapter descriptions byte-identical** to the canonical `description` fields. If you
+   change a description, change it in both places in the same commit.
+4. **Record the change in `CHANGELOG.md`** with what changed, why, and the finding/decision ID it
+   traces to. This set is maintained under review discipline; an untraceable edit is how the last
+   contradiction got in.
+5. **Resolve ‹VERIFY› placeholders by editing, never by deleting.** Each open item is listed in the
+   changelog with an owner. When a verification is answered, apply its pre-committed outcome (they
+   are written next to the placeholders) and remove the placeholder in the same edit.
+
+## Provenance
+
+- The entity-terminology table in `house-style.md` is a governed copy of
+  `blog-creator product-context v4 · 2026-08-14`. When that table changes upstream, update the copy
+  in the same change.
+- The rule substance was ratified through the D5 review (2026-08-14, findings D5-22…31) and the D2
+  review v1.1 (findings D2-01…12, transfer matrix v1). The CHANGELOG maps every edit to those IDs.