/han-update-documentation

name: han-update-documentation
description: >
  Update Han plugin documentation so every skill, agent, guidance doc, index, and cross-reference is current and
  accurate. On a non-default branch, scopes the pass to entities the branch actually touched. On the default branch,
  performs a full documentation sweep across the whole plugin. Use when updating, refreshing, syncing, auditing, or
  verifying Han's docs after changing skills, agents, references, or top-level guidance — including "update the docs",
  "doc sweep", "refresh documentation", "audit the docs", "make sure the docs are current". This is a
  repository-maintenance skill for the Han repo itself, not a general documentation skill — use /project-documentation
  to document features in arbitrary projects, /han-release to cut a release (and update CHANGELOG), and
  /update-pr-description for PR bodies.
argument-hint: "[optional context about what changed]"
allowed-tools: Read, Write, Edit, Glob, Grep, Agent, Bash(git *), Bash(find *)

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](./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 fro