Skip to content
sdlc

T-AV6J-add-update-skill-doc-skill

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

Goal

Section titled “Goal”

The warning hook shipped by T-H9Q4-document-every-skill-with-mermaid-flowchart catches drift when a plugin/skills/<slug>/SKILL.md is edited without touching its companion docs/skills/<slug>.md, but it offers no recovery action — the author still has to hand-edit the doc and re-author the Mermaid flowchart. A stand-alone /update-skill-doc skill closes that loop: invoked with a skill slug, it regenerates the per-skill doc to match the current SKILL.md, so refreshing docs becomes a one-command action and the hook can point to it directly.

Today

Section titled “Today”

There is no plugin/skills/update-skill-doc/ directory today. The existing skills (14 of them under plugin/skills/) all share a common shape — a SKILL.md with numbered steps, references to other plugin docs under /Users/sksizer2/.claude/plugins/sdlc/, and a notes section — but no skill currently authors or rewrites markdown under docs/skills/. The parent task T-H9Q4-document-every-skill-with-mermaid-flowchart introduces docs/skills/<slug>.md per skill, a house-style README at plugin/skills/README.md, and a warning hook in .claude/settings.json, but the hook can only flag drift — it cannot fix it.

Proposed

Section titled “Proposed”

A stand-alone skill exists at plugin/skills/update-skill-doc/SKILL.md, invoked as /update-skill-doc <skill-slug>. Given a slug for any skill present under plugin/skills/, it reads that skill’s SKILL.md and the house-style at plugin/skills/README.md, then rewrites docs/skills/<slug>.md so the doc faithfully reflects the current SKILL.md — including a fresh Mermaid flowchart of the skill’s steps and major branching/looping logic. Running the skill against an unchanged SKILL.md produces no diff (idempotent). The warning hook from the parent task is updated to mention /update-skill-doc <slug> as the recovery action so authors have a clear next step when drift is flagged.

Approach

Section titled “Approach”
  1. Confirm T-H9Q4-document-every-skill-with-mermaid-flowchart has merged so docs/skills/, plugin/skills/README.md, and the warning hook in .claude/settings.json are available as the integration surface.
  2. Create plugin/skills/update-skill-doc/SKILL.md following the structural conventions used by the existing skills under plugin/skills/ (numbered steps, plugin-doc references, notes section). The body should specify:
    • Argument resolution: <skill-slug> matched against plugin/skills/; bail with a clear error if no match.
    • Read plugin/skills/<slug>/SKILL.md and plugin/skills/README.md.
    • Author / rewrite docs/skills/<slug>.md in the house-style, regenerating the Mermaid flowchart from the SKILL.md steps and major branching/looping logic.
    • Stage and commit the result on the current branch with a conventional message (docs(skills): refresh <slug>).
  3. Update the warning-hook command in .claude/settings.json so its output names /update-skill-doc <slug> as the recovery action.
  4. Update plugin/skills/README.md to note that /update-skill-doc is the canonical way to refresh a per-skill doc.
  5. Smoke-test by running /update-skill-doc <some-existing-skill> against one of the docs hand-authored by the parent task; confirm the regenerated doc matches the house-style and that a second invocation produces no diff (idempotency check).

Files to touch

Section titled “Files to touch”
  • plugin/skills/update-skill-doc/SKILL.md (new) — the new skill body.
  • .claude/settings.json — update the warning-hook message from the parent task to suggest running /update-skill-doc <slug>.
  • plugin/skills/README.md — add a one-liner noting /update-skill-doc is the canonical way to refresh a per-skill doc.

Acceptance criteria

Section titled “Acceptance criteria”
  • AC-1: plugin/skills/update-skill-doc/SKILL.md exists and follows the structural shape of the other skills in plugin/skills/.
  • AC-2: /update-skill-doc <slug> (for any skill present in plugin/skills/) writes a docs/skills/<slug>.md that conforms to the house-style defined in plugin/skills/README.md (title, one-line summary, trigger, Mermaid flowchart, notes).
  • AC-3: Running /update-skill-doc <slug> twice in a row produces no diff on the second run (idempotent).
  • AC-4: Invoking with an unknown slug exits with a clear error and does not write docs/skills/<slug>.md.
  • AC-5: The warning hook from T-H9Q4-document-every-skill-with-mermaid-flowchart mentions /update-skill-doc <slug> as the recovery action.

Out of scope

Section titled “Out of scope”
  • Authoring docs from scratch for skills that don’t yet have one — that’s the parent task’s job.
  • Running the skill in batch over every skill (single-slug invocation only; multi-skill mode can be a follow-up).
  • Auto-invoking the skill from the warning hook; the hook stays advisory and points the author at the command.
  • Pulling the flowchart from anything other than the SKILL.md step structure (e.g. no AST-style parsing of plugin scripts).

Dependencies

Section titled “Dependencies”

Discovery context

Section titled “Discovery context”

Split off from the design conversation around T-H9Q4-document-every-skill-with-mermaid-flowchart on 2026-05-19. The parent task introduces a warning hook for skill→doc drift; this task is the model-driven recovery skill the hook will point at, kept separate to avoid bloating the parent task’s scope.

Post-mortem

Section titled “Post-mortem”

Captured by /sdlc:task-work on 2026-05-19. PR: pending.

Acceptance criteria coverage

Section titled “Acceptance criteria coverage”
  • AC-1: agent-manual — plugin/skills/update-skill-doc/SKILL.md exists with the expected structural shape (frontmatter with description: and allowed-tools:, numbered ## N. ... steps, ## Notes section, references to canonical conventions). Cross-checked against plugin/skills/task-ensure-ready/SKILL.md and plugin/skills/setup/SKILL.md as structural exemplars.
  • AC-2: agent-manual — the SKILL.md’s Step 3 enumerates the required outputs (title, one-line summary, trigger, Mermaid flowchart, notes) verbatim from plugin/skills/README.md and instructs the agent to follow the README’s Flowchart conventions section literally. Compliance of an actual generated doc is not verifiable without running the skill live — see “Friction” below.
  • AC-3: agent-manual — Step 4 of the SKILL.md instructs the implementer to compare the written file against the pre-edit state via git diff and skip commit/report “no changes” when the diff is empty. Idempotency was not exercised end-to-end (would require running the skill live in this same session); flagging this as agent-manual rather than auto. See follow-up below.
  • AC-4: agent-manual — Step 1 explicitly bails (with usage message + list of present plugin/skills/ directories) when the slug doesn’t resolve, and the prose forbids writing docs/skills/<slug>.md in that branch. Behavior was specified, not executed.
  • AC-5: auto — .claude/hooks/warn-skill-doc-drift.py was updated in both branches (missing-doc and stale-doc), naming /update-skill-doc {slug} as the recovery action. Verified by reading the diff back; the slug interpolation uses the already-extracted regex group, so the message always includes a runnable command.

What worked

Section titled “What worked”
  • Reading plugin/skills/README.md, the parent task’s post-mortem, and two structural exemplars (task-ensure-ready, setup) before writing — that established the house-style without any reverse-engineering.
  • The dogfooded doc (docs/skills/update-skill-doc.md) was authored by hand following the same house-style the skill itself enforces, which doubled as a structural validation of the spec.
  • The quality-check suite passed cleanly first try across check_entities.py, entities-migrate/tests/run_evals.py, import-planning/tests/run_evals.py, and check_skill_prose.py — no fixture surprises from the new skill directory.

Friction and automation gaps

Section titled “Friction and automation gaps”
  • Idempotency is asserted but not executed. AC-3 is agent-manual because verifying “second run produces no diff” requires running the skill live, which is itself the artifact being added. The pattern of “skills that author other docs” needs a sub-skill or harness eval that drives a real invocation under deterministic conditions, so idempotency claims for skills like /update-skill-doc can be auto rather than agent-manual. → T-RXKE-eval-harness-for-doc-authoring-skills
  • The drift hook’s warning text is duplicated between two branches. The “missing doc” and “stale doc” stderr writes in warn-skill-doc-drift.py each carry their own copy of the recovery-action line. If the recovery command ever changes (plugin namespacing, slug rename), both branches must be edited in lockstep. A small refactor to a shared format string would prevent that drift — but the hook is short enough that it’s a minor concern, not blocking. (Skipping as too speculative.)
  • No discoverable contract test for “every skill has a doc that matches its SKILL.md.” The warning hook is per-edit-event; project-check has check_skill_prose.py which validates invariants per skill, but nothing currently asserts that docs/skills/<slug>.md exists for every skill OR that its flowchart references every numbered step in the SKILL.md. A check_skill_docs.py under .claude/skills/project-check/ would close the loop — turning the soft hook into a hard gate at project-check time. → T-5CVT-project-check-asserts-skill-docs-match-skill-md

Spawned follow-up tasks

Section titled “Spawned follow-up tasks”

← Back to Tasks