han-update-documentation

# Per-Entity Audit Checklist

## Contents

- Skills (`{plugin}/skills/{name}/SKILL.md` + `{plugin}/docs/skills/{name}.md`)
- Agents (`{plugin}/agents/{name}.md` + `{plugin}/docs/agents/{name}.md`)
- Top-level concept docs (`docs/concepts.md`, `docs/quickstart.md`, `docs/sizing.md`, `docs/yagni.md`)
- Indexes (`docs/skills/README.md`, `docs/agents/README.md`)
- Guidance docs (`han-plugin-builder/skills/guidance/references/**`)
- Templates (`docs/templates/**`)
- Root files (`README.md`, `CONTRIBUTING.md`, `CLAUDE.md`)
- Reporting findings

Verification rules applied to every entity in scope. The skill's mode (branch vs. sweep) determines _which_ entities are
in scope. This checklist determines _what_ is checked for each one. Apply every rule that fits the entity's type. Record
each finding with the file path and a concrete fix; do not paper over discrepancies.

`{plugin}` below means the skill root the skill came from: any discovered `han-*/skills` directory except
`han-plugin-builder/skills` (the detect script reports the current list). Agents live under `han-core/agents` and
`han-communication/agents` (the readability-editor). Long-form docs now live inside the plugin they describe, at
`{plugin}/docs/skills/{name}.md` and `{plugin}/docs/agents/{name}.md`, beside that plugin's `README.md`.

## Skills (`{plugin}/skills/{name}/SKILL.md` + `{plugin}/docs/skills/{name}.md`)

### Skill definition (`{plugin}/skills/{name}/SKILL.md`)

1. **Frontmatter `name` matches directory name.** `name: foo-bar` requires `{plugin}/skills/foo-bar/`.
2. **Frontmatter `description` is current.** Reflects what the steps actually do. If steps changed and the description
   still names a removed step or omits a new one, update the description.
3. **`allowed-tools` matches actual usage.** Every tool the steps call is listed; tools no longer used are removed. Each
   Bash command prefix is a separate `Bash()` entry.
4. **Referenced scripts exist.** Every `${CLAUDE_SKILL_DIR}/scripts/...` path resolves to a real file under the skill's
   `scripts/`.
5. **Referenced files exist.** Every `references/...` or `docs/...` link in the body resolves.
6. **No stale directives.** If the SKILL.md tells the agent to use a renamed flag, a removed script, an abandoned
   convention, or a deleted sibling skill, fix it.

### Long-form doc (`{plugin}/docs/skills/{name}.md`)

1. **Long-form doc exists.** Every skill across the discovered skill roots has a matching long-form doc at
   `{plugin}/docs/skills/{name}.md`. Missing doc is a hard finding — create it from
   `docs/templates/skill-long-form-template.md` rather than leaving the gap.
2. **Orientation frame intact.** First line is `# /{name}`; the second paragraph names the audience and links to
   `{plugin}/skills/{name}/SKILL.md` (from the doc's location, `../../skills/{name}/SKILL.md`). The `> See also:`
   orientation line is present.
3. **TL;DR present.** Three lines: what / when / what-you-get-back. Each one sentence.
4. **Sections follow the template.** Key concepts, When to use it, How to invoke it, What you get back, How to get the
   most out of it, YAGNI (when applicable), Cost and latency, In more detail (optional), Sources, Related documentation.
5. **TL;DR matches the skill's frontmatter description.** A reader who reads the SKILL.md frontmatter and the long-form
   TL;DR must come away with the same understanding. Mismatches are a finding.
6. **"Do not invoke for" pointers resolve.** Every sibling skill named in a boundary statement exists. The other
   direction is bidirectional — see "Cross-references" below.
7. **"How to invoke it" examples reflect actual argument-hint.** If the SKILL.md `argument-hint` changed, examples and
   prose update with it.
8. **"What you get back" matches what the skill produces.** File names, locations, section structures, and ID schemes
   match the steps in SKILL.md.
9. **Sources are still cited correctly.** URLs resolve and named artifacts in the skill trace back to them. Removed
   citations correspond to removed protocols.
10. **Related documentation first bullet links to the plugin README** (`../../README.md`), then the repo root
    (`../../../README.md`), per D14 and the convention in CLAUDE.md.
11. **Agent links resolve.** Every agent link in Related documentation (`../../../han-core/docs/agents/{name}.md`, or
    `../../../han-communication/docs/agents/readability-editor.md`) resolves to a real long-form agent doc.

### Cross-references

1. **`docs/skills/README.md` lists the skill** with a one-sentence scent line under the right group. If the skill's
   purpose changed groups, move it.
2. **`docs/skills/README.md` scent matches current behavior.** A scent line that names a removed agent, a removed
   sub-skill, or an outdated capability is a finding.
3. **CLAUDE.md skill catalog entry is present** and the one-liner matches current behavior.
4. **CLAUDE.md "Indexes stay complete, not counted" convention holds.** The skill has a long-form doc and a skills-index
   entry, and no removed skill is still listed. Verify completeness, not a count.
5. **Bidirectional boundary statements.** If skill A's frontmatter says "use B instead," skill B's frontmatter mentions
   A in the reverse direction. Same for long-form `Do not invoke for` sections.
6. **Bidirectional Related documentation links.** If `/foo` pairs with `/bar`, both long-form docs name the pairing.
7. **README.md skill references stay count-free.** The Skills Index links resolve and the surrounding text names no
   hardcoded skill count.

## Agents (`{plugin}/agents/{name}.md` + `{plugin}/docs/agents/{name}.md`)

### Agent definition (`han-core/agents/{name}.md`)

1. **Frontmatter `name` matches the file's basename.**
2. **Frontmatter `description` is current.** Reflects what the agent does, when to dispatch it, and what it does not do.
   Boundary statements name the right sibling agents.
3. **`tools` matches actual usage.**
4. **`model` matches the model selection guidance** in
   `han-plugin-builder/skills/guidance/references/specialization-and-model-selection.md` for this agent's role.
5. **No stale references.** Sibling agents named in the boundary all exist. Skills named as callers exist.

### Long-form doc (`{plugin}/docs/agents/{name}.md`)

1. **Long-form doc exists** for every agent in `han-core/agents/` and `han-communication/agents/`. Missing doc is a hard
   finding — create it from `docs/templates/agent-long-form-template.md`.
2. **Orientation frame, TL;DR, and template sections present** per `docs/templates/agent-long-form-template.md`.
3. **"Dispatched by" or equivalent section names every skill that uses this agent.** When a skill's dispatch list
   changed, this section updates.
4. **TL;DR matches the agent's frontmatter description.**
5. **Related documentation first bullet links to the plugin README** (`../../README.md`), then the repo root
   (`../../../README.md`), per D14.
6. **Skill links resolve.**

### Cross-references

1. **`docs/agents/README.md` lists the agent** with a one-sentence scent line under the right role group.
2. **Scent line matches current agent behavior.**
3. **CLAUDE.md agent catalog list** (the by-role grouping) includes the agent.
4. **CLAUDE.md "Indexes stay complete, not counted" convention holds.** The agent has a long-form doc and an
   agents-index entry, and no removed agent is still listed. Verify completeness, not a count.
5. **README.md agent references stay count-free.** The Agents Index links resolve and the surrounding text names no
   hardcoded agent count.
6. **Skills that dispatch this agent** name it in their long-form Related documentation section.

## Top-level concept docs (`docs/concepts.md`, `docs/quickstart.md`, `docs/sizing.md`, `docs/yagni.md`)

1. **`docs/concepts.md` stays count-free.** The "What does the plugin include?" bullets reference the skills and agents
   through their index links, not a hardcoded count.
2. **Named skills/agents still exist** under those names. No mention of removed skills, no missing mention of skills
   added to relevant categories.
3. **Cross-references resolve.** Every internal link points at a real file.
4. **No stale protocols.** A claim like "the swarming skills are A, B, C, D, E, F, G" must list the actual seven
   sizing-aware skills.

## Indexes (`docs/skills/README.md`, `docs/agents/README.md`)

1. **Every skill (across the discovered skill roots) and every agent (in the agent root) appears in the index** under
   exactly one group.
2. **No index entry points at a non-existent file.**
3. **Group headings still describe their groups accurately.** When a category was renamed or merged, the heading
   updates.
4. **Each entry's scent line is current.**
5. **Compositions list reflects current pairings.** The composition chains in `docs/workflows.md` list compositions that
   still hold; remove those that no longer do, and keep the mermaid diagrams consistent with the prose.

## Guidance docs (`han-plugin-builder/skills/guidance/references/**`)

1. **References to scripts, file paths, tool flags, and conventions are current.** Doc-code contradictions are
   functional bugs — see `documentation-maintenance.md`.
2. **Cross-references at the bottom resolve.**
3. **Examples cite current skills or agents.** A guidance doc that uses a removed skill as its canonical example must
   update the example.

## Templates (`docs/templates/**`)

1. **Templates reflect the current expected shape of long-form docs.** If most long-form docs added a section the
   template lacks, propose adding it to the template (or treat the new section as drift to remove).
2. **`coverage-rule.md`'s rules are still accurate.** Verify the coverage rule (every skill and agent has a long-form
   doc) holds; do not track a count.

## Root files (`README.md`, `CONTRIBUTING.md`, `CLAUDE.md`)

### README.md

1. **Install/intro paragraphs stay count-free.** The intro references the skills and agents without a hardcoded count,
   and the Skills Index and Agents Index links resolve.
2. **Links to docs resolve.**
3. **Maintainer list, license, and install instructions are still correct.**

### CONTRIBUTING.md

1. **The "Adding a skill" / "Adding an agent" checklists still match the current process.**
2. **Linked guidance files exist.**
3. **The Documentation conventions list still matches what the long-form docs do.**

### CLAUDE.md

1. **Repository layout section reflects the actual on-disk structure.**
2. **Doc map ("When to use which doc") lists every skill and agent long-form doc with a one-line description.**
3. **"Indexes stay complete, not counted" convention line is accurate.** It describes the completeness check (every
   entity has a doc and an index entry), not a running total.
4. **Conventions section matches what the docs actually do.**

## Reporting findings

For each finding, capture:

1. **Location.** Absolute path from repo root.
2. **What is wrong.** One sentence.
3. **The fix.** Concrete edit, not a vague "update this."
4. **Apply the fix in place** before reporting unless the fix requires a judgment only the user can make (a renamed
   agent's intent, a removed skill's replacement, a category boundary the user has not decided yet). In those cases,
   surface the finding to the user with a recommended resolution.

# Scope Mapping: Changed Files to Entities

Maps a changed file path to the documentation entities that must be reviewed for accuracy. Used in **branch mode**,
where the skill audits only the entities the branch touched. In **sweep mode**, the skill enumerates the full inventory
instead.

A single changed file can pull multiple entities into scope. Always add every entity the path touches.

`{plugin}` below means any discovered skill root — every `han-*/skills` directory except `han-plugin-builder/skills`
(its `guidance` skill is authoring guidance, not a documented product skill). The detect script reports the current list
between `skill-roots-start` and `skill-roots-end`; read it from there rather than assuming a fixed set, so a newly added
plugin is covered automatically. Agents live under `han-core/agents` and `han-communication/agents` (the
readability-editor). Long-form docs now live inside the plugin they describe, at `{plugin}/docs/skills/{name}.md` and
`{plugin}/docs/agents/{name}.md`, beside that plugin's `README.md`.

## Mapping table

| Path pattern                                            | Entities pulled into scope                             |
| ------------------------------------------------------- | ------------------------------------------------------ |
| `{plugin}/skills/{name}/SKILL.md`                       | skill `{name}`                                         |
| `{plugin}/skills/{name}/references/**`                  | skill `{name}`                                         |
| `{plugin}/skills/{name}/scripts/**`                     | skill `{name}`                                         |
| `{plugin}/agents/{name}.md`                             | agent `{name}`                                         |
| `{plugin}/docs/skills/{name}.md`                        | skill `{name}`                                         |
| `{plugin}/docs/agents/{name}.md`                        | agent `{name}`                                         |
| `{plugin}/README.md`                                    | plugin `{plugin}` front door                           |
| `docs/skills/README.md`                                 | skills-index                                           |
| `docs/agents/README.md`                                 | agents-index                                           |
| `docs/choosing-a-han-plugin.md`                         | plugin-index                                           |
| `docs/workflows.md`                                     | workflows                                              |
| `docs/concepts.md`                                      | concepts                                               |
| `docs/quickstart.md`                                    | quickstart                                             |
| `docs/sizing.md`                                        | sizing                                                 |
| `docs/yagni.md`                                         | yagni                                                  |
| `han-communication/references/writing-voice.md`         | writing-voice                                          |
| `han-plugin-builder/skills/guidance/references/**/*.md` | the guidance file itself                               |
| `docs/templates/**/*.md`                                | the template file itself                               |
| `README.md`                                             | root-readme                                            |
| `CONTRIBUTING.md`                                       | contributing                                           |
| `CLAUDE.md`                                             | claude-md                                              |
| `CHANGELOG.md`                                          | ignore (out of scope for this skill)                   |
| `{plugin}/.claude-plugin/plugin.json`                   | ignore (versioning belongs to /han-release)            |
| `.claude-plugin/marketplace.json`                       | ignore (versioning belongs to /han-release)            |
| `.claude/skills/**`                                     | ignore (repo-local maintenance skills, no plugin docs) |
| anything else                                           | ignore                                                 |

## Implicit dependencies

Some path changes drag additional entities into scope even when those entities' own files were not edited.

- **A new skill added** under `{plugin}/skills/{name}/`: also audit the plugin's `{plugin}/README.md` (scent line),
  `docs/skills/README.md` (must list it), `CLAUDE.md` (catalog entry), `README.md`, `docs/concepts.md` (all must
  reference it without a hardcoded count).
- **A skill removed or renamed** under `{plugin}/skills/`: same as added, plus every other skill or agent doc whose
  Related Documentation section linked to the old name.
- **A new agent added** under `han-core/agents/` or `han-communication/agents/`: also audit the plugin's
  `{plugin}/README.md` (scent line), `docs/agents/README.md`, `CLAUDE.md` (catalog entry), `README.md` (must reference
  it without a hardcoded count).
- **An agent removed or renamed**: same as added, plus every skill doc that mentions dispatching the agent.
- **A skill description (frontmatter) changed**: also audit the plugin's `{plugin}/README.md` scent line,
  `docs/skills/README.md` scent line, the skill's long-form `{plugin}/docs/skills/{name}.md` TL;DR, and the `CLAUDE.md`
  catalog entry. Sibling skills named in the boundary may need their reverse-boundary statement checked.
- **An agent description (frontmatter) changed**: also audit the plugin's `{plugin}/README.md` scent line,
  `docs/agents/README.md` scent line, the agent's long-form `{plugin}/docs/agents/{name}.md` TL;DR.
- **A guidance doc renamed or moved**: every other doc that linked to the old path is in scope.

## Out of scope for this skill

These changes do not pull anything into the documentation update scope. They have their own owners.

- `CHANGELOG.md` — owned by `/han-release`.
- `{plugin}/.claude-plugin/plugin.json` `version` field (any of the five plugins) — owned by `/han-release`.
- `.claude-plugin/marketplace.json` `version` field — owned by `/han-release`.
- `.claude/**` repo-local config and skills — not part of the plugin's user-facing surface.
- `images/**`, binary assets.
- `LICENSE`.

#!/usr/bin/env bash
# Detect mode and scope for /han-update-documentation.
#
# Emits structured key: value pairs on stdout and always exits 0 so the
# skill can branch on the output without crashing on missing git state.
#
# Output keys:
#   mode             one of: branch | sweep | error
#   reason           (only when mode=error) explanation for the operator
#   branch           current branch name, or "none"
#   default-branch   resolved default branch name (no remote prefix), or "none"
#   skill-roots-start / skill-roots-end
#                    wrap a newline-separated list of discovered skill roots
#                    (every han-*/skills directory except the plugin-builder's,
#                    whose guidance skill is authoring guidance, not a documented
#                    product skill). Discovered dynamically so a newly added
#                    plugin needs no edit to this skill.
#   agent-root       the single directory that holds agents (han-core/agents),
#                    or "none" if not found
#   changed-files-start / changed-files-end
#                    (only when mode=branch and there are changes) wrap a
#                    newline-separated list of files changed against the
#                    default branch
#   changed-files: none
#                    (only when mode=branch and no files changed)

if ! command -v git &>/dev/null; then
  echo "mode: error"
  echo "reason: git is not installed"
  exit 0
fi

if ! git rev-parse --is-inside-work-tree &>/dev/null; then
  echo "mode: error"
  echo "reason: not inside a git work tree"
  exit 0
fi

ROOT=$(git rev-parse --show-toplevel)

BRANCH=$(git branch --show-current)
echo "branch: ${BRANCH:-none}"

if ! git symbolic-ref --short refs/remotes/origin/HEAD &>/dev/null; then
  echo "default-branch: none"
  echo "mode: error"
  echo "reason: origin/HEAD is not configured; cannot determine the default branch"
  exit 0
fi

DEFAULT_FULL=$(git symbolic-ref --short refs/remotes/origin/HEAD)
DEFAULT="${DEFAULT_FULL#origin/}"
echo "default-branch: $DEFAULT"

# Discover the documented skill roots and the agent root dynamically, so adding
# a new product plugin needs no edit here. A skill root is any han-*/skills
# directory; the plugin-builder's guidance skill is authoring guidance audited
# under the guidance-docs branch, not a docs/skills/ product skill, so exclude it.
echo "skill-roots-start"
( cd "$ROOT" && find . -maxdepth 2 -type d -name skills -path './han-*/skills' \
    ! -path './han-plugin-builder/skills' 2>/dev/null | sed 's|^\./||' | sort )
echo "skill-roots-end"

AGENT_ROOT=$( cd "$ROOT" && find . -maxdepth 2 -type d -name agents -path './han-*/agents' \
    2>/dev/null | sed 's|^\./||' | sort | head -1 )
echo "agent-root: ${AGENT_ROOT:-none}"

# Sweep mode when on the default branch (or detached HEAD that resolves to it).
if [ -z "$BRANCH" ] || [ "$BRANCH" = "$DEFAULT" ]; then
  echo "mode: sweep"
  exit 0
fi

echo "mode: branch"
CHANGED=$(git diff --name-only "$DEFAULT_FULL...HEAD")
if [ -n "$CHANGED" ]; then
  echo "changed-files-start"
  echo "$CHANGED"
  echo "changed-files-end"
else
  echo "changed-files: none"
fi