Skills 2026-09-27 21:08 UTC
ai-readyv1.3.0
Version [v1.3.0] committed by johnpapa. Update Category: Feature Addition & Enhancement. Commit details: Item-by-item review of references/: cut duplicates, narrative asides, and three stale-terminology bugs (#62). This update introduces new capabilities and module extensions.
CommitRaw commit message
Item-by-item review of references/: cut duplicates, narrative asides, and three stale-terminology bugs (#62) * references/agents-md.md: remove a real internal duplicate and three sections SKILL.md already absorbed Same test as the SKILL.md pass: does removing this change what the agent does, and is it stated more completely somewhere else already? The internal duplicate: `## Never merges without a human` was defined twice in this one file. Once inline (with its own "it will be challenged... it is not banned" reasoning) right before the template, and again in a separate `## Defining` section a few dozen lines later, with the exact same blockquote repeated. Merged into one treatment, and folded in the one genuinely new thing the second copy had -- the distinction between `## Done means` (what a change must satisfy to be finished) and this section (what it cannot decide alone) -- as an opening line rather than its own heading and paragraph. Three sections turned out to be near-complete duplicates of what SKILL.md's Step 2 already states, likely left behind when Step 2 was rewritten in an earlier pass and this reference was never re-trimmed to match: - The discoverability-test lead-in (SKILL.md already has the full rule and the exact "surprising... conventional" phrasing). Trimmed to a one-line pointer back to SKILL.md, keeping the verdict table -- genuinely additive worked examples SKILL.md doesn't have. - "Structure and stack sections are the ones to be ruthless about..." -- near-verbatim duplicate of SKILL.md's surprising/conventional language. Cut outright. - The entire `## Length` section -- SKILL.md's Step 2 already states the 20-30 starting point, the 150 ceiling-not-target distinction, and the "gets worse as it gets longer" reasoning, in full. Cut, and fixed the one dangling reference in "Report this honestly" that assumed the cut section's context ("well past the target" -> "well past 150 lines", so the sentence still stands alone). Kept, because they're genuinely not duplicated anywhere: the verdict table, "two rules with no room for judgment" (positive framing, split-by-scope), the placement table with its own reasoning column, the OpenAI-monorepo color, "report this honestly," and the full Done- means / Never-merges-without-a-human generation detail. 136 -> 103 lines (-24%), 1,316 -> 1,048 words. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XE2pKUgGXWbcqbD44mPpSy * references/reviewer-agents.md: cut two duplicates of SKILL.md's Step 4c, one internal "Why three, and when it should not be three" restated SKILL.md's own skip-condition rule almost exactly -- "generate only the ones whose question can come back no here: skip test-integrity in a repo with no tests, skip blast-radius where nothing is hard to undo. Say what you skipped and why" already lives in Step 4c. Trimmed to keep only the genuinely additive framing (why three isn't a fixed principle) and the agent-to-question mapping table, with a pointer back to Step 4c for the skip conditions instead of restating them. Generation rules' "Never overwrite" bullet duplicated Step 4c's own closing line ("if the repo already has agents covering these concerns, leave them and flag drift instead") -- cut. "Keep them narrow" also duplicated itself against this same file's "Writing a fourth one" section, both saying "a repo-specific reviewer is a separate file" a few lines apart. Trimmed to the narrow-remit point only, pointing at Writing a fourth one for the rest instead of repeating it. Left untouched: the opening adversarial-agents distinction (written this session, addresses a real point of confusion), the four mechanics (now the sole copy, since SKILL.md's restatement of these was cut in the same session for the same reason), the three literal agent-body templates (the actual deliverable, not prose to trim), and Writing a fourth one's four-question checklist (operationalizes the mechanics into a pass/fail test, which is a different job than restating them). 158 -> 152 lines, 1,246 -> 1,174 words. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XE2pKUgGXWbcqbD44mPpSy * references/github-discovery.md: fix stale AGENTS.md reference, cut a superlative and a narrative tail - Real bug: the PR-review-comments table row still said conventions belong in "copilot-instructions.md" — stale since PR #37 moved to the single-source-of-truth AGENTS.md architecture. Fixed to `AGENTS.md`. - Cut the "highest-value" superlative and its *Why?* paragraph in 0c, the fifth instance of a pattern already removed 4x during the SKILL.md review. Folded the one non-redundant fact (a maintainer repeating a comment = an undocumented convention) into the lead sentence. - Trimmed a narrative tail off the closing line of 0c ("turning repeated review feedback... into guidance that applies before the next pull request is written instead of after") — restates what the section just explained, changes nothing an agent does. 69 lines / 823 words -> 68 lines / 783 words. * references/detection-tables.md: fix a stale drift-check row, cut four narrative *Why?* asides - Real bug: the drift-detection table asked to check `copilot-instructions.md` for "new conventions from PR reviews" and "maintenance matrix" coverage. Under the single-source-of-truth architecture (PR #37, and SKILL.md Step 2), both of those live in `AGENTS.md` — `copilot-instructions.md` is only a short pointer to it. Moved that check onto the `AGENTS.md` row and replaced the `copilot-instructions.md` row with the check that actually applies: has the pointer drifted into its own copy of the conventions (the Step 1d duplication failure mode)? - Cut the monorepo `*Why?*` under manifest detection — redundant with the fuller, more specific one under "Monorepo area detection" below; added no instruction of its own. - Cut the VS Code extension `*Why?*` — narrative justification for a heuristic already fully stated above (the detection check plus the three flavors). - Trimmed the multi-app-collection and course/tutorial `*Why?*` asides down to their one actionable sentence each ("don't invent workspace tooling where none exists" / what a course repo's product actually is), cutting the restated framing around them. 215 lines / 2,526 words -> 211 lines / 2,465 words. * references/report-template.md: fix a stale section name used 3x, cut two rule duplicates and two *Why?* asides - Real bug: three rules referenced a "What I Did" section and one referenced "What To Do Next" — neither exists in the template, in README.md, or in examples/sample-report-peacock.md. The actual sections are "What I'd Like To Do" and "What's Next?". An agent following these rules literally would look for headings that don't exist. Fixed all four references. - Cut two "Report template rules" bullets (issue/PR attribution, doc-sync-on-change) that restate SKILL.md's General Rules almost verbatim — that file is guaranteed context, this one is conditional, so the fuller statement stays there. Trimmed the matching restatement in the 11b PR-creation flow to just the summary/score instruction; the literal template still shows `Assisted by [ai-ready]` in the actual PR comment (kept — deliverable, not restatement). - Cut the HTML report *Why?* and the closing *Why?* on the single-PR-comment rule — both restate reasoning for an instruction already given in full, directive form just above. 227 lines / 1,736 words -> 221 lines / 1,615 words. * references/agents-md.md: restore the load-bearing guard and the 20–30 line target lost with ## Length Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PuNQuoLvQF4hVY9JUFnJA1 --------- Co-authored-by: Claude <noreply@anthropic.com>