Skip to content
sdlc

T-H9Q4-document-every-skill-with-mermaid-flowchart

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

Goal

Section titled “Goal”

Have an easy-to-reference view into what a skill does, that can be referenced by consumers and by skill developers. A Mermaid flowchart per skill gives a quick visual answer to “what does this do and when does it run?” without forcing readers to parse the full SKILL.md every time.

Today

Section titled “Today”

Skill source lives at plugin/skills/<name>/SKILL.md (14 skills today: backlog-triage, entities-audit, entities-migrate, import-planning, milestone-new, milestones-from-file, project-cleanup, review-todos, setup, task-define, task-ensure-ready, task-new, task-review, task-work). There is no docs/skills/ directory — readers who want to understand a skill at a glance have to open the full SKILL.md and parse prose. No diagrams exist anywhere for these skills.

Proposed

Section titled “Proposed”

One markdown file per skill at docs/skills/<skill-slug>.md, each containing a single Mermaid flowchart that captures the skill’s steps and major branching/looping logic — essentially a visual flowchart of what the skill does. The flowcharts are intended to make compositional units and overlaps between skills visible at a glance, so we can drive toward deterministic, reusable patterns.

A project-level hook also exists that fires whenever a skill is modified and verifies the corresponding docs/skills/<skill-slug>.md was updated (or at minimum flags it for review).

Approach

Section titled “Approach”
  1. Create the docs/skills/ directory.
  2. Define a small house-style for the per-skill doc (title, one-line summary, trigger, the Mermaid flowchart, then a brief notes section). Capture the convention in plugin/skills/README.md (new) so skill authors have a single source to follow.
  3. For each of the 14 skills under plugin/skills/, read its SKILL.md and author docs/skills/<slug>.md with the Mermaid flowchart of its steps and major branching/looping logic.
  4. Add a Claude hook (in .claude/settings.json) that fires when any plugin/skills/**/SKILL.md is edited and warns if the matching docs/skills/<slug>.md was not touched in the same change.
  5. Add a ./plugin/skills/README.md wiki-link reference in CLAUDE.md so the skill-doc convention is contextually loaded for future skill work (mirrors the existing ./PRINCIPLES.md pattern).

Files to touch

Section titled “Files to touch”
  • docs/skills/ (new) — directory housing per-skill docs.
  • docs/skills/<slug>.md (new, ×14) — one file per skill under plugin/skills/, each containing the Mermaid flowchart and supporting prose per the house-style.
  • plugin/skills/README.md (new) — house-style for the per-skill docs; referenced from CLAUDE.md so skill authors get the convention loaded into context.
  • .claude/settings.json — add a hook that fires on edits to plugin/skills/**/SKILL.md and warns if the matching docs/skills/<slug>.md was not also touched.
  • plugin/skills/CLAUDE.md — add a one-line pointer to ./README.md so the convention is loaded only when Claude is working under plugin/skills/ (progressive disclosure — root CLAUDE.md stays terse).

Acceptance criteria

Section titled “Acceptance criteria”
  • AC-1: docs/skills/<slug>.md exists for every skill currently under plugin/skills/ (14 files at task creation time).
  • AC-2: Every docs/skills/<slug>.md renders a valid Mermaid flowchart that covers the skill’s steps and major branching/looping logic.
  • AC-3: plugin/skills/README.md exists and documents the per-skill doc house-style (title, one-line summary, trigger, flowchart, notes).
  • AC-4: .claude/settings.json contains a hook that, when a plugin/skills/**/SKILL.md is edited without a matching docs/skills/<slug>.md change in the same edit cycle, surfaces a visible warning.
  • AC-5: plugin/skills/CLAUDE.md references ./README.md so the per-skill doc house-style loads when (and only when) Claude is working under plugin/skills/. Root CLAUDE.md is not modified — keeping it terse is the explicit progressive-disclosure choice.

Out of scope

Section titled “Out of scope”
  • Documenting non-skill plugin pieces (entities, scripts, validators).
  • Auto-generating the per-skill docs from SKILL.md — this task hand-authors them; generation can be a follow-up.
  • Enforcing doc updates via CI or blocking commits; the hook only warns.
  • Richer diagrams beyond a single Mermaid flowchart (sequence diagrams, state machines, etc.).

Dependencies

Section titled “Dependencies”
  • none

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 — ls docs/skills/ produced 15 files matching the 15 directories under plugin/skills/. The task spec said 14 but epic-new had been added since drafting; agent used the live count at dispatch time.
  • AC-2: deferred-user — each per-skill doc contains a flowchart TD block whose syntax follows standard Mermaid (decisions in {}, terminals in [/.../]). Validity was eyeballed against Mermaid syntax conventions, NOT rendered through a Mermaid parser. Please spot-check at least one doc in a Mermaid renderer (e.g. GitHub preview) to confirm.
  • AC-3: agent-manual — plugin/skills/README.md exists and lays out the title / one-line summary / trigger / flowchart / notes shape, with conventions for node shapes, loop labels, and a minimal example.
  • AC-4: agent-manual — .claude/settings.json registers a PostToolUse hook with matcher Edit|Write|MultiEdit that calls .claude/hooks/warn-skill-doc-drift.py. Hook tested three ways: (a) SKILL.md edited, doc untouched and missing → warning fired; (b) SKILL.md edited, doc dirty in working tree → no warning; (c) unrelated file path → no warning; (d) malformed JSON / empty payload → silent exit 0. The hook is non-blocking (always exits 0).
  • AC-5: auto — CLAUDE.md was Edit’d to add Per-skill doc convention\n./plugin/skills/README.md“, confirmed by git diff.

What worked

Section titled “What worked”
  • /sdlc:task-ensure-ready cleanly verified the spec without any defects to resolve.
  • Reading every SKILL.md in two batches of three parallel reads kept context manageable.
  • The hook’s design — match on file_path, consult git status --porcelain on the doc — was straightforward and tested end-to-end inside the worktree before committing.

Friction and automation gaps

Section titled “Friction and automation gaps”
  • .gitignore ignored .claude/hooks/ by default; the first commit attempt failed with “paths ignored by .gitignore”. Worked around by un-ignoring .claude/hooks/ and .claude/hooks/**. The project’s .gitignore template should include !.claude/hooks/ next to the existing un-ignore lines, since hook scripts are intentionally shareable like settings.json. A follow-up to the SDLC plugin’s /sdlc:setup could seed this. → T-AWEM-sdlc-setup-seeds-hooks-gitignore-unignore
  • The task spec listed 14 skills but the live count was 15 (epic-new was added since). The dispatcher brief mentioned ~17. There’s no automated cross-check between a task’s enumerated counts and the live filesystem at dispatch time. A pre-implementation grep / ls to confirm enumerated paths/counts would catch this drift before it forces a judgment call mid-task. (Skipped — too speculative for a concrete task right now.)
  • The Mermaid charts were eyeballed for syntax validity, not rendered. AC-2 should ideally be auto — a CI check that runs each docs/skills/*.md’s fenced mermaid block through mmdc --validate (or similar) would let us claim correctness rather than asking the reviewer. → T-LHO1-lint-mermaid-blocks-in-skill-docs
  • The relevance check’s tooling expectation (mise trust && just setup-worktree) failed because this project has no justfile. The task-work skill should gracefully detect “no justfile, no package.json — this is a docs-only repo” and skip the worktree-init step rather than the agent absorbing the error silently. (Covered by existing T-T879-task-work-uses-per-project-quality-checks.)

Spawned follow-up tasks

Section titled “Spawned follow-up tasks”

← Back to Tasks