han-update-documentation

Pre-requisites

• git: !which git
• repo root marker: !find . -maxdepth 2 -name "plugin.json" -path "/.claude-plugin/" -type f
• skills directory: !find . -maxdepth 2 -type d -name "skills" -path "/plugin/"
• agents directory: !find . -maxdepth 2 -type d -name "agents" -path "/plugin/"

If any of the above are empty: this skill is intended to run inside the Han plugin repository. Tell the operator which marker is missing and stop. Do not attempt to operate on a different repo.

Project Context

• current branch: !git branch --show-current
• default branch: !git symbolic-ref --short refs/remotes/origin/HEAD

Step 1: Detect mode and scope

Run ${CLAUDE_SKILL_DIR}/scripts/detect-doc-update-context.sh and read its output. Branch on the mode: line.

mode: error — stop. Surface the reason: line to the operator. Do not proceed.

mode: branch — branch scope. Set MODE = branch. Read the file list between changed-files-start and changed-files-end (or note that the file list is empty if changed-files: none appears instead). If the file list is empty, inform the operator that the branch has no changes against the default branch and stop.

mode: sweep — full sweep. Set MODE = sweep. The skill audits every documentation entity in the plugin.

Echo back the mode and the count of in-scope files (branch mode) or "full plugin sweep" (sweep mode) so the operator knows what is about to happen.

Step 2: Build the entity inventory

The mode determines which entities to audit. Always build a deduplicated list of entities before reading anything else, so Step 3 has a fixed plan.

When MODE = branch

Map each changed file to its entities using [references/scope-mapping.md](references/scope-mapping.md). A single file can pull multiple entities into scope (a changed skill SKILL.md pulls the skill plus, if the description changed, the index and CLAUDE.md catalog). Then apply the implicit dependencies section of the mapping reference: skill or agent additions and removals pull the indexes, CLAUDE.md, README, and docs/concepts.md into scope; sibling-boundary changes pull the named sibling into scope.

Deduplicate. Produce a single ordered inventory INV:

1. Skills, alphabetical.
2. Agents, alphabetical.
3. Indexes (docs/skills/README.md, docs/agents/README.md).
4. Top-level concept docs (docs/concepts.md, docs/quickstart.md, docs/sizing.md, docs/yagni.md, docs/writing-voice.md).
5. Guidance docs (specific files only).
6. Templates (specific files only).
7. Root files (README.md, CONTRIBUTING.md, CLAUDE.md).

When MODE = sweep

Enumerate the full set:

1. Every skill. find plugin/skills -mindepth 1 -maxdepth 1 -type d for the inventory; each entry pulls in plugin/skills/{name}/SKILL.md and docs/skills/{name}.md.
2. Every agent. find plugin/agents -mindepth 1 -maxdepth 1 -name "*.md" -type f for the inventory; each entry pulls in plugin/agents/{name}.md and docs/agents/{name}.md.
3. Both indexes (docs/skills/README.md, docs/agents/README.md).
4. All top-level concept docs in docs/.
5. All guidance docs under docs/guidance/.
6. All templates under docs/templates/.
7. Root files (README.md, CONTRIBUTING.md, CLAUDE.md).

Sweep mode always audits that README.md, CLAUDE.md, and docs/concepts.md reference the skills and agents without a hardcoded count, and that every entity found in this step appears in the indexes and the CLAUDE.md catalog.

Out-of-scope files (both modes)

Treat as ignored: CHANGELOG.md, plugin and marketplace version fields, .claude/, LICENSE, images/. These belong to other skills or are not user-facing documentation.

Step 3: Per-entity audit

Walk INV in order. For each entity, apply every rule in [references/audit-checklist.md](references/audit-checklist.md) that fits the entity's type. Record findings as you go in a working list with this shape:

- {entity-name} ({path})
  - Finding: {one-sentence description}
  - Fix: {concrete edit}

Read the source of truth before checking the doc. For a skill, read plugin/skills/{name}/SKILL.md first, then read docs/skills/{name}.md and check it against the source. For an agent, read plugin/agents/{name}.md first, then docs/agents/{name}.md. Doc-vs-source contradictions are functional bugs — treat them with the same severity as broken scripts (see docs/guidance/skill-building-guidance/documentation-maintenance.md).

Batch agent audits when the inventory is large. When INV has more than ten skills or ten agents to audit, dispatch a content-auditor agent per batch of five entities with the entity name, the source-of-truth file, and the long-form doc. Hand each agent the relevant section of [references/audit-checklist.md](references/audit-checklist.md) inline (do not tell it to read the file). The agent returns findings; merge them into the working list. Do not run more than four such agents in parallel.

Stop on first hard finding only for missing files. Missing long-form doc, missing index entry, or missing CLAUDE.md catalog entry blocks the rest of that entity's checks until created. Other findings accumulate; do not bail.

Step 4: Cross-reference and bidirectional-link audit

After Step 3, look across entities, not just within them.

1. Bidirectional skill boundaries. For every skill in INV whose frontmatter or long-form "Do not invoke for" section names a sibling, verify the sibling names this skill in the reverse direction. Asymmetric boundaries are findings.
2. Bidirectional pairings. For every skill or agent in INV whose long-form Related documentation names another, verify the other side links back where the link adds value. One-direction pairings without a reason are findings.
3. Indexes are consistent with reality. Use Grep to confirm every skill in plugin/skills/ appears in docs/skills/README.md exactly once, and every agent in plugin/agents/ appears in docs/agents/README.md exactly once. Stray entries pointing at non-existent files are findings.
4. CLAUDE.md catalog completeness. Every entity in INV (skills and agents) has a one-line entry in the CLAUDE.md doc map. Missing entries are findings.
5. Count-free references. Confirm README.md, CLAUDE.md (the "Indexes stay complete, not counted" line), and docs/concepts.md describe the skills and agents without a hardcoded total. A reintroduced count (for example "21 skills" or "23 agents") is a finding. Sweep mode always runs this check; branch mode runs it only if the branch added or removed skills or agents.
6. The ## How skills compose block in docs/skills/README.md references current skill names only. References to renamed or removed skills are findings.

Add each finding to the working list with the same shape as Step 3.

Step 5: Apply updates

Apply every finding from Steps 3 and 4 in place.

Use Edit, not Write, for changes that touch part of an existing file. Use Write only when creating a missing long-form doc from a template.

Creating a missing long-form doc. Copy docs/templates/skill-long-form-template.md (for a skill) or docs/templates/agent-long-form-template.md (for an agent) into the target path. Fill in the orientation frame, TL;DR, and Key concepts from the entity's frontmatter description and step body. Leave a <!-- TODO: human review --> marker only at sections that require operator judgment (Sources, In more detail, examples). Surface those markers in Step 6's report so the operator can finish them.

Apply the writing voice. Every edit follows docs/writing-voice.md: no em-dashes, direct second person, no flattery or hype words, no actually, just, leverage, utilize, showcase, robust (as a vague positive), It's worth noting, or Importantly. When fixing a doc, do not introduce voice violations even if the surrounding doc has them.

**Appl