docs: correct the sizing-aware lists and the han-reporting install claims - #211
Merged
Conversation
An outside reader reported that Han's docs contradict each other and the skill definitions (#200). This plans the fix and records the evidence. Verification widened the first of the three reported items. The quickstart is missing four size-accepting skills, not the one reported: it lists 9, the concepts page 12, and the skill frontmatter declares 14, of which 13 classify their own work. The cause is CONTRIBUTING.md step 6, which names the sizing and concepts catalogs and not the quickstart, so four skill additions between 2026-08-10 and 2026-09-09 updated the named pages and left the quickstart behind. The plan carries six delta entries in three units, each pinning the exact replacement text: the two list syncs plus the checklist step, the two han-reporting corrections, and the banner alt attribute. One entry is behavior-changing, and the operator approved widening scope to cover it. An automated catalog check is deferred under YAGNI with its reopening trigger named. Nothing was cut for scope.
…aims Closes #200. The quickstart listed 9 sizing-aware skills and the concepts page 12, where 13 skills classify their own work. Both now match docs/sizing.md, which was already correct. CONTRIBUTING.md step 6 now names the quickstart alongside the sizing and concepts catalogs, which is the reason it fell four months behind: four skill additions since 2026-05-29 updated the two pages the checklist named and left the third untouched. Two pages stated the han-reporting dependency exception correctly and then contradicted it a few lines later. On docs/choosing-a-han-plugin.md the correct half sat in a trailing parenthetical while the bold sentence under "The one thing that surprises people" erased it, so the exception now sits in the bold sentence a skimming reader stops on. docs/concepts.md listed reporting-only among installs that do not exist; it is the one layer plugin you can install without han-core, so the page now says what it gives you. The README banner gains alt text. It is the only image embed in the repo's prose, and it carries the project name and tagline that a screen-reader user previously got nothing of. Plan, decisions, and evidence in docs/plans/gh-200-docs-consistency/.
Branch-scoped documentation audit over the 14 skills and 22 agents this branch touched. - research: add Write and Edit to allowed-tools. Step 8 writes the report and applies the editor's rewrite, but neither tool was declared. - docs/readability.md: add /design-an-api, /plan-a-change, and /ddd-analysis to the per-skill table. All three dispatch readability-editor, and the table declares itself authoritative. - plan-a-change: document the Step 9.5 readability rewrite in Cost and latency and in Related documentation. - ddd-analysis: add the readability-editor bullet to Related documentation, matching the Step 10 dispatch its Cost section already described. - readability-editor: add /ddd-analysis to the dispatcher list. - risk-analyst: add /plan-a-change to the TL;DR dispatcher list and the Dispatch-when section; it was named in Related documentation only.
mxriverlynn
marked this pull request as ready for review
September 11, 2026 14:52
This was referenced Sep 11, 2026
Draft
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #200.
An outside reader worked through the docs end to end and found pages that disagree with each other and with the skill definitions. All three of their findings were verified against the skill frontmatter and the plugin manifests before anything was changed, and the first one turned out larger than reported.
The sizing-aware lists were three different lengths
docs/quickstart.mdlisted 9 skills anddocs/concepts.mdlisted 12. Thirteen skills classify their own work, which is whatdocs/sizing.mdalready said. Both pages now match it.The reporter found one missing skill. Four were missing, and the cause is one line:
CONTRIBUTING.mdstep 6 told contributors to update the sizing and concepts catalogs and never mentioned the quickstart. Four skill additions between 2026-08-10 and 2026-09-09 updated the two named pages and left the third behind, so the quickstart's list had been stale since 2026-05-29. Step 6 now names all three.plan-a-feature-to-confluencedeclaresarguments: sizeand stays out of all three catalogs on purpose. It forwards the argument toplan-a-featurerather than classifying anything, which step 6's own opening condition already excludes.Two pages denied the
han-reportingexception they documenthan-reportingis the only layer plugin that does not declarehan-core, and both pages said so correctly before contradicting themselves.On
docs/choosing-a-han-plugin.mdthe correct half sat in a trailing parenthetical while the bold sentence two lines below it, under the heading "The one thing that surprises people", generalized over it. A skimming reader stops on the bold sentence, so the exception now lives there.docs/concepts.mdlisted reporting-only among installs that do not exist. It is exactly the install that does exist, so the page now says what it gives you:/stakeholder-summaryand/html-summaryplushan-communication, without thehan-coreagent roster.The banner has alt text
README.mdcarries the only image embed in the repo's prose and had noaltattribute, so the project name and tagline reached a screen-reader user as the filename or as nothing.What is in this PR
Two commits. The first adds the change plan, the decisions behind it, and the evidence, under
docs/plans/gh-200-docs-consistency/. The second applies the six edits.Each edit was pinned to exact replacement text before being made, and each of the plan's three verification checks passes: all three pages now carry the same 13 names as
docs/sizing.md, no page outsidedocs/plans/claims that every layer install brings the shared agents, and the banner announces the project rather than its filename.npm run lintandnpm testpass.Deliberately not in this PR
An automated check that a skill declaring
arguments: sizereaches every catalog. It would have caught this drift on the day it started, where the checklist edit only reminds a person. It is deferred with a reopening trigger recorded in the plan: a second drift incident, or a fourth page carrying the list.Two things the review surfaced and this PR leaves alone, both noted in the plan's Open Items. The plugin dependency graph is hand-copied across four files with nothing enforcing agreement, which is the same failure mode on a different fact. And
han-reporting/README.mdstates no dependencies at all.