T-DNGZ-update-skill-prose-standards-and-notes

Status: closed/done · Impact: low · Complexity: small

Goal

Close the loop on the documentation that still describes the retired invariants.yaml mechanism. Rewrite the references in S-0006, rewrite the skills CLAUDE.md “When you change an existing skill’s markers” note, and re-point backlog B-DHKB — which currently assumes invariants.yaml is a keeper — onto the contract mechanism. Then regenerate the standards docs so the generated surface matches.

Today

Location	Role today
`docs/planning/standards/S-0006-skill-md-is-direct-instruction.md`	References the `check_skill_prose` / invariants-based lint mechanism that this milestone replaces
`plugin/skills/CLAUDE.md`	The “When you change an existing skill’s markers” note still tells authors to update `invariants.yaml`
`docs/planning/backlog/B-DHKB-s-0006-cross-cutting-skill-conformance-shared-fix.md`	Assumes `invariants.yaml` is the keeper mechanism for pinned markers

Approach

Repoint the three live docs that still describe invariants.yaml, then regenerate.

S-0006 — the only live reference is the Notes bullet (…:246): “A future check_skill_prose lint could flag some violations mechanically.” Update it to record that sdlc gate skill-prose now runs a markdown-contract contract (the prose-pin mechanism shipped); keep the rule-2 negative-detection caveat as human judgment.
plugin/skills/CLAUDE.md — the “When you change an existing skill’s markers” note (…:78) tells authors to update “the skill’s invariants.yaml (if it pins marker text)”. Repoint to the skill-prose contract.
B-DHKB — item (c) says markers are “pinned in invariants.yaml”; re-point to the contract and note the foreshadowed lint is now realized.
Run sdlc docs generate; stage the regenerated S-0006 site page so project-check-docs-drift passes.

Files to touch

Location	Kind	Change
`docs/planning/standards/S-0006-skill-md-is-direct-instruction.md`	modify	Update the Notes bullet from a “future `check_skill_prose` lint” to the shipped contract-based mechanism
`plugin/skills/CLAUDE.md`	modify	Repoint the “When you change an existing skill’s markers” note from `invariants.yaml` to the skill-prose contract
`docs/planning/backlog/B-DHKB-s-0006-cross-cutting-skill-conformance-shared-fix.md`	modify	Re-point item (c) “pinned in `invariants.yaml`” to the contract; note the lint is realized
`site/src/content/docs/planning/standards/skill-md-is-direct-instruction.md`	modify	Regenerated by `sdlc docs generate` to match the S-0006 edit

Acceptance criteria

AC-1: S-0006 describes the contract-based skill-prose mechanism; no stale invariants.yaml reference remains.
AC-2: The skills CLAUDE.md “When you change an existing skill’s markers” note points authors at the contract, not invariants.yaml.
AC-3: B-DHKB is re-pointed to the contract mechanism (no longer assumes invariants.yaml is a keeper).
AC-4: sdlc docs generate runs clean and the generated standards docs reflect the edits with no drift.

Out of scope

Any code change to the gate op, the contract, or the test surface — done in earlier tasks.
Broader S-0006 rework beyond the skill-prose mechanism reference.

Dependencies

T-UDY1-retire-invariants-yaml-sidecars — the docs describe the end state, so the sidecars must be retired first.

Depends on

T-UDY1-retire-invariants-yaml-sidecars

← Back to Tasks