Han Update Documentation

Pre-requisites

• git: !which git 2>/dev/null || echo "not installed"
• repo root marker: !find . -maxdepth 3 -name "plugin.json" -path "*/.claude-plugin/*" -type f
• skill roots: !find . -maxdepth 2 -type d -name skills -path './han-*/skills' ! -path './han-plugin-builder/skills' 2>/dev/null | sed 's|^\./||' | sort
• agents directory: !find . -maxdepth 2 -type d -name agents -path './han-*/agents' 2>/dev/null | sed 's|^\./||' | sort

If any of the above are empty or read not installed: 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 2>/dev/null || echo unknown
• default branch: !git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null || echo unknown

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.

The script also emits the skill roots (between skill-roots-start and skill-roots-end) and the agent root (the agent-root: line), both discovered dynamically from disk. These are the authoritative roots for the rest of this skill — use them wherever the steps below say "the skill roots" or "the agent root," rather than any hardcoded plugin list. A skill root is every han-*/skills directory except han-plugin-builder/skills, whose guidance skill is authoring guidance audited under guidance docs (Step 2, sweep), not a documented product skill. Adding a new product plugin needs no edit to this skill; it shows up in the discovered roots automatically.

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 across the plugin suite (every skill root the detect script reported, plus the agent root).

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. 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).
5. Guidance docs (specific files only).
6. Templates (specific files only).
7. Root files (README.md, CONTRIBUTING.md, CLAUDE.md).

Plugin roots

Han ships as several plugins. Skills are spread across several of them; agents live in han-core and, for the readability-editor, han-communication. 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.

• Skill roots: the list the detect script reported between skill-roots-start and skill-roots-end. Every han-*/skills directory except han-plugin-builder/skills (its guidance skill is authoring guidance, audited under guidance docs below). Do not hardcode the plugins here; read them from the script so a newly added plugin is covered automatically.
• Agent root: the script's agent-root: line (han-core/agents). The readability-editor agent also lives in han-communication/agents; include it when auditing agents.
• Plugin manifests: {plugin}/.claude-plugin/plugin.json for every plugin. Owned by /han-release; out of scope here.

Throughout this skill, {plugin} means whichever discovered skill root a given skill came from.

When MODE = sweep

Enumerate the full set:

1. Every skill. Run find <skill roots> -mindepth 1 -maxdepth 1 -type d, passing the skill roots the detect script reported, for the inventory; each entry pulls in {plugin}/skills/{name}/SKILL.md (the root the directory came from) and {plugin}/docs/skills/{name}.md.
2. Every agent. Run find <agent root> -mindepth 1 -maxdepth 1 -name "*.md" -type f, passing the script's agent-root (plus han-communication/agents for the readability-editor), for the inventory; each entry pulls in {agent-root}/{name}.md and {plugin}/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 han-plugin-builder/skills/guidance/references/.
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 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 (the plugin root the skill came from), then read {plugin}/docs/skills/{name}.md and check it against the source. For an agent, read {plugin}/agents/{name}.md first, then {plugin}/docs/agents/{name}.md. Doc-vs-source contradictions are functional bugs — treat them with the same severity as broken scripts (see han-plugin-builder/skills/guidance/references/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 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.