han-update-documentation

## Pre-requisites

- git: !`which git`
- 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:** 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.

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`, `docs/writing-voice.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 only one. Long-form docs stay flat under `docs/skills/` and `docs/agents/` no matter which plugin owns the entity.

- **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 only plugin with 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 `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`, for the inventory; each entry pulls in `{agent-root}/{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 `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](./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 descript