docs(verify-readme): align the prose with the ai-facing style #40
Loading…
Reference in a new issue
No description provided.
Delete branch "align/verify-readme"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Style-only pass: the README contract itself (section order, parity rule, Agent Rule template) is unchanged; the cuts are restatements the ai-facing guide forbids.
Approach review: The approach is sound. This is a single-file style pass on
skills/verify-readme/SKILL.mdthat applies the repository's ownai-facing-writing-stylerules to a skill document, which is the right way to do it: the contract (section order, parity rule, Agent Rule template, failure-mode list, output modes) is byte-for-byte unchanged, and every cut is a restatement that guide explicitly targets.The individual moves line up with named rules rather than being ad-hoc trimming: dropping the
# Goalheading whose body duplicated the frontmatter description follows "Structure and Formatting" (a section included for form's sake) and matches the majority convention here — only 3 of 25 skills carry a# Goalheading; collapsing the fournpx -y <tool> --helpbullets into one sentence and replacing the restated parity instruction in Task step 5 with a pointer to thepackage.json#descriptionparity section follows "collapse the restatements into the anchor"; removing "and, if present" from thepackage.jsonread follows "cut self-evident escape hatches" (a missing file announces itself).I checked the removals for information loss and found none that matters. The
(default: README.md)parenthetical cut from Task step 1 is still stated in Inputs ("If no path is given, operate onREADME.mdin the current working directory"), so the behavior stays pinned in exactly one place. The shortened frontmatter description keeps every trigger phrase, which is what governs skill selection, and the human-facing-prose delegation dropped from it survives in the body line that tells the agent to invokehuman-facing-writing-style.No materially better approach — the alternatives (leaving the prose as-is, or extracting shared boilerplate across skills) would either skip the alignment or over-engineer a one-file cleanup.
Approach review by Claude Code Opus (opus)
Summary: No actionable issues found.
Style-only pass over
skills/verify-readme/SKILL.md. I verified the claims in the PR body and checked for the failure modes a prose-deletion pass usually introduces:package.json#descriptionparity rule, and the Agent Rule template are byte-identical; only surrounding prose changed.package.json#descriptionparity" rule matches the heading exactly. Task step 6's failure modes ("without answering obvious follow-up questions or linking to deeper material") are still backed by the surviving "How it works" bullets. No file in the repo references the removed# Goalheading.(default: README.md)is safe because the Inputs section still states the default, and droppingif presentforpackage.jsonmatches the ai-facing guide's "cut self-evident escape hatches" rule (a missing file fails loudly, and the config/dotfiles case is already named in Inputs).:sequence, no leading indicator char) at 411 chars, well under the routing-description limit, and it retains the literal trigger phrases the router matches on.# Inputsmatches 22 of 25 skills here, includingai-facing-writing-styleitself.Code review by Claude Code Opus (opus)
Approach review: The approach looks good. This is a deletion-first style pass on a single
SKILL.md, which is exactly the shapeai-facing-writing-styleprescribes for aligning existing content: cut restatements whole, leave the contract untouched. The README contract (section order, parity rule, Agent Rule template, failure-mode list) is unchanged, so the skill's behaviour is preserved.The cuts land where the style guide points. Dropping the
# Goalheading and its paragraph removes a near-verbatim restatement of the frontmatter description and matches the several skills here that already open with a bare lead paragraph (ai-facing-writing-style,human-facing-writing-style,handoff,node,grill-with-docs). Task step 1 losing(default: README.md)andif presentcosts nothing — the default is already pinned in Inputs, and a missingpackage.jsonfails loudly, the self-evident escape hatch the guide says to cut. Task step 5 now defers to thepackage.json#descriptionparity section instead of paraphrasing it, which is the right direction: one home per instruction. Collapsing the four-bulletnpx -y <tool> --helprationale into one sentence keeps the causal content while shedding the bullet scaffolding.One thing worth a deliberate call rather than a change: the description also lost
and applies human-facing prose rules throughout. The description is the routing surface, and the body still makes invokinghuman-facing-writing-stylea required step, so a request phrased as README prose or wording quality has slightly less to match on. The literal trigger phrases still cover the common asks, so this is a judgement call about routing reach, not a defect.No materially better approach to suggest.
Approach review by Claude Code Opus (opus)
Review feedback disposition (head
7d113e7):approach-smart-1andcode-smart-1(run 17389): no actionable findings — nothing to change.approach-smart-1(dispatch retry, run 17431) flagged one deliberate-call item: the frontmatter description no longer says "and applies human-facing prose rules throughout". Ruling: the cut stands. The body still requires invokinghuman-facing-writing-stylebefore editing, so the phrase restated a surviving instruction, and this style-only pass deliberately reintroduces no derivable sentence. The description keeps every literal trigger phrase the router matches on; if routing reach proves too narrow in practice, widening the routing surface is a separate deliberate change, not part of this pass.Review-cycle status:
approach-smart-2,approach-3, andcode-smart-2failed their Axrecipe capability exchange (HTTP 400 "Validation failed") in both run 17389 and the maintainer-dispatch retry (run 17431, wherecode-smart-1also hit a transient upstream 529). The same three slots fail identically on PRs #41 and #42, so this is service-side, not PR-specific.