# intent, site-docs-authoring
status: shipped
species: procedural
dials: { disable-model-invocation: false, user-invocable: true }
freedom: medium
type: capability-uplift

Note: this intent record was filled directly from an already-approved
plan (`.claude/plans/enchanted-singing-globe.md`, "Site docs review +
authoring method") and this session's own research (3 parallel Explore
agents surveying `site/pages/`'s structure, a color-contrast root-cause
investigation, and a review of existing tooling) rather than a live
turn-by-turn interview, the operator confirmed the plan, including
"doc + a dedicated skill" as the Phase 4 method depth, before this
skill was forged. Slots below are answered from that record, not
fabricated dialogue.

## trigger
should:
  - "review this site docs page"
  - "add a new pattern page under site/pages/patterns"
  - "why does this callout look like plain text"
  - "author a new page under site/pages/getting-started"
  - "is this site page consistent with our conventions"
should_not:
  - "review this component demo gallery" (packages/web-components/components/*/*.examples.html, primitive-authoring)
  - "fix this gen-ui training exemplar page" (site/pages/examples/**, site/pages/gen-ui/**, composition-and-examples.md's no-style-block rule + a2ui-maintenance)

## delta
Without this skill, Claude (or a human author) reaches for whatever
looks locally plausible on a `site/pages/*.html` page and repeats the
defect classes this session found and fixed: a fabricated `data-*`
attribute standing in for a real primitive (16 of 34 pages had
`data-alert="warning|info"` with ZERO matching CSS anywhere, dead
markup that silently renders as plain paragraphs), a hand-rolled
`<style>` block duplicating an existing shared utility (4 pages
independently reinvented the same "tame this admin-shell demo" CSS),
and a background token picked for its "feels dark and subtle" name
rather than its actual measured contrast (inline `<code>` used
`--a-canvas-well`, hand-measured at ~1.1:1 against
the page background, WCAG 2.2 SC 1.4.11 wants ≥3:1). All three are
now fixed at the shared-CSS/token level (cascades to all 34 pages),
but a NEW page authored without this skill's guidance would
re-introduce the same classes on page 35. Deleted after a month: the
next contributor re-invents a `data-tip`/`data-caution` variant of the
same dead-attribute bug, or a 5th hand-rolled demo-taming `<style>`
block, because nothing routes them to `alert-ui` or `.demo-frame`
before they start typing.

## fences
- NOT for `packages/web-components/components/*/*.examples.html` component demo pages (primitive-authoring)
- NOT for `site/pages/examples/**`, `site/pages/gen-ui/**`, `packages/gen-ui/a2ui/corpus/exemplars/**`, pure primitive-composition training-harvest surfaces with their own no-style-block rule (`composition-and-examples.md`, a2ui-maintenance)
- NOT for the A2UI generation pipeline itself, chunk corpus, or MCP tools (a2ui-maintenance)

## assertions
1. A new callout block the skill produces uses `<alert-ui variant="...">` with a `[slot="content"]` wrapper for rich text, never a bare `data-*` attribute with no matching CSS.
2. A new tamed-demo page the skill produces adds `class="demo-frame"` plus only a page-local `--demo-frame-height` override, it does not restate `position`/`border`/`overflow`/`.demo-body` padding.
3. When asked to review an existing page, the skill's output names the specific rule from `site-pages-authoring.md` a defect violates (not just "this looks off").
4. The skill's own description correctly declines to fire on a component `.examples.html` demo or a `site/pages/examples/**` training page (see `should_not` above) and instead names the owning sibling skill.

## gates
P0 route:      PASS, 2026-07-14, knowledge/procedure needed on demand (author or review a site/pages doc), not mechanically checkable (hook), not always-true-every-turn (entry file), no tool-wall/parallelism need (agent). Skill.
P1 intent:     PASS, 2026-07-14, slots filled from the approved plan + this session's research; operator confirmed the plan's Phase 4 scope (doc + dedicated skill) via AskUserQuestion before forging began.
P2 evals:      PASS, 2026-07-14, see evals/routing-corpus.json (trigger cases, matching this repo's primitive-authoring sibling's own eval-file convention) and assertions above (behavioral). No literal fresh-session baseline captured (this is a same-session, plan-driven forge, not an interactive intent interview), the delta section above records the concrete "without this skill" failure mode from direct evidence (the 3 defect classes this session found and fixed) in place of a baseline transcript.
P3 draft:      PASS, 2026-07-14, SKILL.md + evals/routing-corpus.json exist; both dials explicit; body 61 lines, well under the 500-line budget.
P4 language:   PASS, 2026-07-14, self-audited against the 5 instantiation checks: task-shape rows commit to concrete actions (not descriptions); ~3 hard-gate ceiling held (never restate demo-frame properties, never a bare data-* callout, don't reach for a raw ramp step without color-verify); numeric anchors present (>=3:1, 34-page, 4 rules); contracts (task-shape table) precede the verify-steps tail; the labeled good/bad alert-ui pair lives in the referenced convention doc rather than duplicated here (reference, never restate).
P5 validate:   PASS, 2026-07-14, skill_lint.py clean; skill-auditor FLOOR audit verdict PASS (report at evals/audit-report.md), 3 minor non-blocking findings, all fixed same-change (phantom fence trimmed to reference composition-and-examples.md by name rather than specific paths; 2 negative imperatives demoted to positive form; intent.md's routing-corpus.json citation corrected). No fence-reciprocity step run against primitive-authoring's own evals, primitive-authoring's corpus already covers "primitive authoring" as should_route_to_author:true, which is the correct answer for those phrases; no reciprocal edit needed there.

## rulings
- Accepted with note: no literal fresh-session baseline transcript (P2), this forge ran from an already-approved plan's research rather than a live interview; the delta section's direct evidence substitutes. Not re-litigated.
- Accepted with note: convention doc lives at `.claude/docs/conventions/site-pages-authoring.md`, not inside this skill's own `references/`, deliberate, to avoid a drift pair with the doc that's also linked from `document-routing.md`.
- Post-ship correction (same session, before task close): the skill's own Rule-2 example used `<span slot="content">`, a real bug, not just a style choice. `scripts/build/lib/docs-transpiler.mjs`'s `PROSE_CONTAINERS` only recognizes `p`/`div`/`ul`/`ol`; `<span>` fell to a different decomposition path that silently reordered mixed inline content (a leading `<strong>` rendered AFTER the surrounding text, bold dropped) once the compiled `site-a2ui/pages/*.json` regenerated, invisible to schema validation (`valid:true`) and to a raw-HTML read, only caught by a live-browser check. Fixed in SKILL.md, the convention doc, and all 16 already-migrated `site/pages/*.html` files (`<span>` → `<div>`). Added "visually verify" as a non-optional Verify step for this content shape.