Skip to content

docs: correct the sizing-aware lists and the han-reporting install claims - #211

Merged
mxriverlynn merged 3 commits into
v5.5.0-betafrom
gh-200-quick-start-docs
Sep 11, 2026
Merged

docs: correct the sizing-aware lists and the han-reporting install claims#211
mxriverlynn merged 3 commits into
v5.5.0-betafrom
gh-200-quick-start-docs

Conversation

@mxriverlynn

Copy link
Copy Markdown
Collaborator

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.md listed 9 skills and docs/concepts.md listed 12. Thirteen skills classify their own work, which is what docs/sizing.md already said. Both pages now match it.

The reporter found one missing skill. Four were missing, and the cause is one line: CONTRIBUTING.md step 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-confluence declares arguments: size and stays out of all three catalogs on purpose. It forwards the argument to plan-a-feature rather than classifying anything, which step 6's own opening condition already excludes.

Two pages denied the han-reporting exception they document

han-reporting is the only layer plugin that does not declare han-core, and both pages said so correctly before contradicting themselves.

On docs/choosing-a-han-plugin.md the 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.md listed 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-summary and /html-summary plus han-communication, without the han-core agent roster.

The banner has alt text

README.md carries the only image embed in the repo's prose and had no alt attribute, 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 outside docs/plans/ claims that every layer install brings the shared agents, and the banner announces the project rather than its filename. npm run lint and npm test pass.

Deliberately not in this PR

An automated check that a skill declaring arguments: size reaches 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.md states no dependencies at all.

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
mxriverlynn marked this pull request as ready for review September 11, 2026 14:52
@mxriverlynn
mxriverlynn merged commit 83b22c6 into v5.5.0-beta Sep 11, 2026
2 checks passed
@mxriverlynn
mxriverlynn deleted the gh-200-quick-start-docs branch September 11, 2026 14:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant