{"slug":"han-update-documentation","title":"han-update-documentation","summary":"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 p","platform":"Claude","tags":[],"authorName":"LLM Mart","authorSlug":"llm-mart","score":0,"source":"github","price":null,"verified":false,"createdAt":"2026-10-15T13:12:03.428761Z","repo":{"url":"https://github.com/testdouble/han","stars":303,"forks":24,"license":"MIT","updatedAt":"2026-10-14T20:22:28Z"},"bodyHtml":"<hr>\n<h2>name: han-update-documentation\ndescription: &gt;\nUpdate Han plugin documentation so every skill, agent, guidance doc, index, and cross-reference is current and\naccurate. On a non-default branch, scopes the pass to entities the branch actually touched. On the default branch,\nperforms a full documentation sweep across the whole plugin. Use when updating, refreshing, syncing, auditing, or\nverifying Han's docs after changing skills, agents, references, or top-level guidance — including \"update the docs\",\n\"doc sweep\", \"refresh documentation\", \"audit the docs\", \"make sure the docs are current\". This is a\nrepository-maintenance skill for the Han repo itself, not a general documentation skill — use /project-documentation\nto document features in arbitrary projects, /han-release to cut a release (and update CHANGELOG), and\n/update-pr-description for PR bodies.\nargument-hint: \"[optional context about what changed]\"\nallowed-tools: Read, Write, Edit, Glob, Grep, Agent, Bash(git *), Bash(find *)</h2>\n<h2>Pre-requisites</h2>\n<ul>\n<li>git: !<code>which git 2&gt;/dev/null || echo \"not installed\"</code></li>\n<li>repo root marker: !<code>find . -maxdepth 3 -name \"plugin.json\" -path \"*/.claude-plugin/*\" -type f</code></li>\n<li>skill roots:\n!<code>find . -maxdepth 2 -type d -name skills -path './han-*/skills' ! -path './han-plugin-builder/skills' 2&gt;/dev/null | sed 's|^\\./||' | sort</code></li>\n<li>agents directory:\n!<code>find . -maxdepth 2 -type d -name agents -path './han-*/agents' 2&gt;/dev/null | sed 's|^\\./||' | sort</code></li>\n</ul>\n<p><strong>If any of the above are empty or read <code>not installed</code>:</strong> this skill is intended to run inside the Han plugin\nrepository. Tell the operator which marker is missing and stop. Do not attempt to operate on a different repo.</p>\n<h2>Project Context</h2>\n<ul>\n<li>current branch: !<code>git branch --show-current 2&gt;/dev/null || echo unknown</code></li>\n<li>default branch: !<code>git symbolic-ref --short refs/remotes/origin/HEAD 2&gt;/dev/null || echo unknown</code></li>\n</ul>\n<h2>Step 1: Detect mode and scope</h2>\n<p>Run <code>${CLAUDE_SKILL_DIR}/scripts/detect-doc-update-context.sh</code> and read its output. Branch on the <code>mode:</code> line.</p>\n<p>The script also emits the <strong>skill roots</strong> (between <code>skill-roots-start</code> and <code>skill-roots-end</code>) and the <strong>agent root</strong>\n(the <code>agent-root:</code> line), both discovered dynamically from disk. These are the authoritative roots for the rest of this\nskill — use them wherever the steps below say \"the skill roots\" or \"the agent root,\" rather than any hardcoded plugin\nlist. A skill root is every <code>han-*/skills</code> directory except <code>han-plugin-builder/skills</code>, whose <code>guidance</code> skill is\nauthoring guidance audited under guidance docs (Step 2, sweep), not a documented product skill. Adding a new product\nplugin needs no edit to this skill; it shows up in the discovered roots automatically.</p>\n<p><strong><code>mode: error</code></strong> — stop. Surface the <code>reason:</code> line to the operator. Do not proceed.</p>\n<p><strong><code>mode: branch</code></strong> — branch scope. Set <code>MODE = branch</code>. Read the file list between <code>changed-files-start</code> and\n<code>changed-files-end</code> (or note that the file list is empty if <code>changed-files: none</code> appears instead). If the file list is\nempty, inform the operator that the branch has no changes against the default branch and stop.</p>\n<p><strong><code>mode: sweep</code></strong> — full sweep. Set <code>MODE = sweep</code>. The skill audits every documentation entity across the plugin suite\n(every skill root the detect script reported, plus the agent root).</p>\n<p>Echo back the mode and the count of in-scope files (branch mode) or \"full plugin sweep\" (sweep mode) so the operator\nknows what is about to happen.</p>\n<h2>Step 2: Build the entity inventory</h2>\n<p>The mode determines <em>which</em> entities to audit. Always build a deduplicated list of entities before reading anything\nelse, so Step 3 has a fixed plan.</p>\n<h3>When <code>MODE = branch</code></h3>\n<p>Map each changed file to its entities using <a href=\"./references/scope-mapping.md\">references/scope-mapping.md</a>. A single file\ncan pull multiple entities into scope (a changed skill SKILL.md pulls the skill plus, if the description changed, the\nindex and CLAUDE.md catalog). Then apply the <strong>implicit dependencies</strong> section of the mapping reference: skill or agent\nadditions and removals pull the indexes, CLAUDE.md, README, and <code>docs/concepts.md</code> into scope; sibling-boundary changes\npull the named sibling into scope.</p>\n<p>Deduplicate. Produce a single ordered inventory <code>INV</code>:</p>\n<ol>\n<li>Skills, alphabetical.</li>\n<li>Agents, alphabetical.</li>\n<li>Indexes (<code>docs/skills/README.md</code>, <code>docs/agents/README.md</code>).</li>\n<li>Top-level concept docs (<code>docs/concepts.md</code>, <code>docs/quickstart.md</code>, <code>docs/sizing.md</code>, <code>docs/yagni.md</code>).</li>\n<li>Guidance docs (specific files only).</li>\n<li>Templates (specific files only).</li>\n<li>Root files (<code>README.md</code>, <code>CONTRIBUTING.md</code>, <code>CLAUDE.md</code>).</li>\n</ol>\n<h3>Plugin roots</h3>\n<p>Han ships as several plugins. Skills are spread across several of them; agents live in <code>han-core</code> and, for the\nreadability-editor, <code>han-communication</code>. Long-form docs now live inside the plugin they describe, at\n<code>{plugin}/docs/skills/{name}.md</code> and <code>{plugin}/docs/agents/{name}.md</code>, beside that plugin's <code>README.md</code>.</p>\n<ul>\n<li><strong>Skill roots:</strong> the list the detect script reported between <code>skill-roots-start</code> and <code>skill-roots-end</code>. Every\n<code>han-*/skills</code> directory except <code>han-plugin-builder/skills</code> (its <code>guidance</code> skill is authoring guidance, audited under\nguidance docs below). Do not hardcode the plugins here; read them from the script so a newly added plugin is covered\nautomatically.</li>\n<li><strong>Agent root:</strong> the script's <code>agent-root:</code> line (<code>han-core/agents</code>). The readability-editor agent also lives in\n<code>han-communication/agents</code>; include it when auditing agents.</li>\n<li><strong>Plugin manifests:</strong> <code>{plugin}/.claude-plugin/plugin.json</code> for every plugin. Owned by <code>/han-release</code>; out of scope\nhere.</li>\n</ul>\n<p>Throughout this skill, <code>{plugin}</code> means whichever discovered skill root a given skill came from.</p>\n<h3>When <code>MODE = sweep</code></h3>\n<p>Enumerate the full set:</p>\n<ol>\n<li><strong>Every skill.</strong> Run <code>find &lt;skill roots&gt; -mindepth 1 -maxdepth 1 -type d</code>, passing the skill roots the detect script\nreported, for the inventory; each entry pulls in <code>{plugin}/skills/{name}/SKILL.md</code> (the root the directory came from)\nand <code>{plugin}/docs/skills/{name}.md</code>.</li>\n<li><strong>Every agent.</strong> Run <code>find &lt;agent root&gt; -mindepth 1 -maxdepth 1 -name \"*.md\" -type f</code>, passing the script's\n<code>agent-root</code> (plus <code>han-communication/agents</code> for the readability-editor), for the inventory; each entry pulls in\n<code>{agent-root}/{name}.md</code> and <code>{plugin}/docs/agents/{name}.md</code>.</li>\n<li><strong>Both indexes</strong> (<code>docs/skills/README.md</code>, <code>docs/agents/README.md</code>).</li>\n<li><strong>All top-level concept docs</strong> in <code>docs/</code>.</li>\n<li><strong>All guidance docs</strong> under <code>han-plugin-builder/skills/guidance/references/</code>.</li>\n<li><strong>All templates</strong> under <code>docs/templates/</code>.</li>\n<li><strong>Root files</strong> (<code>README.md</code>, <code>CONTRIBUTING.md</code>, <code>CLAUDE.md</code>).</li>\n</ol>\n<p>Sweep mode always audits that <code>README.md</code>, <code>CLAUDE.md</code>, and <code>docs/concepts.md</code> reference the skills and agents without a\nhardcoded count, and that every entity found in this step appears in the indexes and the CLAUDE.md catalog.</p>\n<h3>Out-of-scope files (both modes)</h3>\n<p>Treat as ignored: <code>CHANGELOG.md</code>, plugin and marketplace <code>version</code> fields, <code>.claude/**</code>, <code>LICENSE</code>, <code>images/**</code>. These\nbelong to other skills or are not user-facing documentation.</p>\n<h2>Step 3: Per-entity audit</h2>\n<p>Walk <code>INV</code> in order. For each entity, apply every rule in\n<a href=\"./references/audit-checklist.md\">references/audit-checklist.md</a> that fits the entity's type. Record findings as you go\nin a working list with this shape:</p>\n<pre><code>- {entity-name} ({path})\n  - Finding: {one-sentence description}\n  - Fix: {concrete edit}\n</code></pre>\n<p><strong>Read the source of truth before checking the doc.</strong> For a skill, read <code>{plugin}/skills/{name}/SKILL.md</code> first (the\nplugin root the skill came from), then read <code>{plugin}/docs/skills/{name}.md</code> and check it against the source. For an\nagent, read <code>{plugin}/agents/{name}.md</code> first, then <code>{plugin}/docs/agents/{name}.md</code>. Doc-vs-source contradictions are\nfunctional bugs —\ntreat them with the same severity as broken scripts (see\n<code>han-plugin-builder/skills/guidance/references/skill-building-guidance/documentation-maintenance.md</code>).</p>\n<p><strong>Batch agent audits when the inventory is large.</strong> When <code>INV</code> has more than ten skills or ten agents to audit, dispatch\na <code>content-auditor</code> agent per batch of five entities with the entity name, the source-of-truth file, and the long-form\ndoc. Hand each agent the relevant section of <a href=\"./references/audit-checklist.md\">references/audit-checklist.md</a> inline (do\nnot tell it to read the file). The agent returns findings; merge them into the working list. Do not run more than four\nsuch agents in parallel.</p>\n<p><strong>Stop on first hard finding only for missing files.</strong> Missing long-form doc, missing index entry, or missing CLAUDE.md\ncatalog entry blocks the rest of that entity's checks until created. Other findings accumulate; do not bail.</p>\n<h2>Step 4: Cross-reference and bidirectional-link audit</h2>\n<p>After Step 3, look across entities, not just within them.</p>\n<ol>\n<li><strong>Bidirectional skill boundaries.</strong> For every skill in <code>INV</code> whose frontmatter or long-form \"Do not invoke for\"\nsection names a sibling, verify the sibling names this skill in the reverse direction. Asymmetric boundaries are\nfindings.</li>\n<li><strong>Bidirectional pairings.</strong> For every skill or agent in <code>INV</code> whose long-form Related documentation names another,\nverify the other side links back where the link adds value. One-direction pairings without a reason are findings.</li>\n<li><strong>Indexes are consistent with reality.</strong> Use Grep to confirm every skill across the discovered skill roots appears in\n<code>docs/skills/README.md</code> exactly once, and every agent in the agent root appears in <code>docs/agents/README.md</code> exactly\nonce. Stray entries pointing at non-existent files are findings.</li>\n<li><strong>CLAUDE.md catalog completeness.</strong> Every entity in <code>INV</code> (skills and agents) has a one-line entry in the CLAUDE.md\ndoc map. Missing entries are findings.</li>\n<li><strong>Count-free references.</strong> Confirm <code>README.md</code>, <code>CLAUDE.md</code> (the \"Indexes stay complete, not counted\" line), and\n<code>docs/concepts.md</code> describe the skills and agents without a hardcoded total. A reintroduced count (for example \"21\nskills\" or \"23 agents\") is a finding. Sweep mode always runs this check; branch mode runs it only if the branch added\nor removed skills or agents.</li>\n<li><strong>The composition chains in <code>docs/workflows.md</code></strong> reference current skill names only, and the mermaid diagrams stay\nconsistent with the prose. References to renamed or removed skills are findings.</li>\n</ol>\n<p>Add each finding to the working list with the same shape as Step 3.</p>\n<h2>Step 5: Apply updates</h2>\n<p>Apply every finding from Steps 3 and 4 in place.</p>\n<p><strong>Use Edit, not Write,</strong> for changes that touch part of an existing file. Use Write only when creating a missing\nlong-form doc from a template.</p>\n<p><strong>Creating a missing long-form doc.</strong> Copy <code>docs/templates/skill-long-form-template.md</code> (for a skill) or\n<code>docs/templates/agent-long-form-template.md</code> (for an agent) into the target path. Fill in the orientation frame, TL;DR,\nand Key concepts from the entity's frontmatter description and step body. Leave a <code>&lt;!-- TODO: human review --&gt;</code> marker\nonly at sections that require operator judgment (Sources, In more detail, examples). Surface those markers in Step 6's\nreport so the operator can finish them.</p>\n<p><strong>Apply the writing voice.</strong> Every edit follows <code>han-communication/references/writing-voice.md</code>: em-dashes only as a\nlabel-gloss or appositive separator, direct\nsecond person, no flattery or hype words, no <code>actually</code>, <code>just</code>, <code>leverage</code>, <code>utilize</code>, <code>showcase</code>, <code>robust</code> (as a vague\npositive), <code>It's worth noting</code>, or <code>Importantly</code>. When fixing a doc, do not introduce voice violations even if the\nsurrounding doc has them.</p>\n<p><strong>Apply YAGNI to documentation edits.</strong> Do not add speculative sections, <em>for-future-flexibility</em> warnings, or examples\nfor behavior the skill does not have. The YAGNI rule that gates plan steps also gates docs (see <code>docs/yagni.md</code>).</p>\n<p><strong>Bidirectional fixes go on both sides</strong> in the same pass. If the fix is to add <code>/foo</code> to <code>/bar</code>'s <code>Do not invoke for</code>\nlist, also add <code>/bar</code> to <code>/foo</code>'s reverse pointer in the same step.</p>\n<p><strong>Findings that need operator judgment</strong> stay unresolved. Surface them in Step 6. Examples: the user-facing category a\nnew skill belongs in, the agent a removed skill's documentation should now point at, the wording for a Source citation\nthat does not yet exist.</p>\n<h2>Step 6: Verify and report</h2>\n<p>Re-read every file that was edited or created. Confirm:</p>\n<ol>\n<li><strong>Every finding from Steps 3 and 4 was either applied or surfaced as needing operator judgment.</strong></li>\n<li><strong>No new internal links are broken.</strong> Run a Grep across the edited files for <code>](../</code> and <code>](./</code> and spot-check a few\nresolved paths.</li>\n<li><strong><code>README.md</code>, <code>CLAUDE.md</code>, and <code>docs/concepts.md</code> stay count-free</strong> — no hardcoded entity total was introduced\nduring the pass.</li>\n<li><strong>Any em-dash introduced sits in a legal position</strong> (label-gloss separator or appositive aside), never standing in for\na sentence break.</li>\n<li><strong>No <code>{placeholder}</code> braces from templates remain</strong> in any newly-created long-form doc.</li>\n</ol>\n<p>Then report to the operator:</p>\n<ul>\n<li><strong>Mode</strong> (branch or sweep) and the inventory size.</li>\n<li><strong>Entities audited</strong>, grouped by type (skills audited, agents audited, etc.).</li>\n<li><strong>Findings applied</strong>, one bullet per fix, with the file path.</li>\n<li><strong>Findings surfaced for operator judgment</strong>, with the recommended resolution.</li>\n<li><strong>Files changed</strong>, as a list of paths the operator can pass to <code>git diff</code> for review.</li>\n</ul>\n<p>Do not commit, push, or open a PR — those decisions are the operator's. The skill stops at this report.</p>\n","files":[{"path":"references/audit-checklist.md","sizeBytes":11330,"isText":true},{"path":"references/scope-mapping.md","sizeBytes":6428,"isText":true},{"path":"scripts/detect-doc-update-context.sh","sizeBytes":3153,"isText":true},{"path":"SKILL.md","sizeBytes":13481,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"clean","suspicious":0,"notes":0,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-10-15T13:13:06.258117Z","sha256":"D8D7B3FCEBF97591AA2FD97E511C1819D522B2AE79FAD6E9DA16B0441754F61C","sizeBytes":12652},"review":null,"source":{"repositoryUrl":"https://github.com/testdouble/han","path":".claude/skills/han-update-documentation","license":"MIT","commit":"abba73a773528905a8f3d15956029394746e5c7f","subtreeSha":"1480AD19885FFBBFE2DBBC3E6A432193E83E953E6CBB70974F8280ACC7C79156","lastSyncedAt":"2026-10-15T13:11:53.672149Z"},"reviewedAt":"2026-10-15T13:15:21.125858Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/testdouble/han/tree/main/.claude/skills/han-update-documentation"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install testdouble-han@llmmart"},{"target":"git","command":"git clone https://github.com/testdouble/han.git"}]}