| name | readme-analyze-existing |
| description | Diagnose an existing README against the source-analysis output and produce a structured action list (CUT/RELOCATE/RESTRUCTURE/REWRITE-HEADING/REORDER/ADD-CALLOUT) consumed by readme-edit. Splits its work into 0(a)(i) source-only draft, 0(a)(ii) anchored diagnosis. |
| argument-hint | <readme-path> <source-analysis-path> |
readme-analyze-existing
Input: an existing README and the structured output of readme-analyze-source (spine candidate, callouts, API inventory).
Output: a structured action list consumed by readme-edit. Every action is one of: [CUT], [RELOCATE], [RESTRUCTURE], [REWRITE-HEADING], [REORDER], [ADD-CALLOUT]. Each entry names the line range it targets, the rationale (one sentence), and the replacement or destination.
This skill does NOT edit the README; it produces the diagnosis. readme-edit applies the actions. Keeping diagnosis and application separate prevents the common failure mode where an agent edits as it diagnoses and produces inconsistent or partial output.
Anchoring-bias mitigation (the 0(a)(i)/0(a)(ii) split)
A naive cleanup agent reads the existing README first, then proposes the spine, then evaluates the existing structure. This anchors the proposed spine on the existing README's wording. The fix: produce the spine BEFORE reading the existing README, then compare.
You must do these steps in this order:
- Step 0(a)(i): source-only spine. Already done by
readme-analyze-source — it produced the spine candidate without ever reading the existing README. Use that spine as the unbiased reference.
- Step 0(a)(ii): comparison. Now read the existing README. Compare its opening to the source-only spine. The spine differential drives the cleanup actions.
If the existing README's spine ALREADY matches the source-only spine, you write FEWER actions. The cleanup target is the deviation from the source-only spine, not a fixed-percentage cut.
Action types and semantics
| Type | When to use | Required fields |
|---|
[CUT] | The lines are noise, banned phrases, em-dashes, audience disclaimers, marketing copy, redundant prose with no curriculum value. | lines: A-B, rationale: <one sentence> |
[RELOCATE] | The lines contain content that belongs elsewhere in the README (buried spine, misplaced callout). | lines: A-B, target: <line N, or 'after heading X'>, rationale: <one sentence> |
[RESTRUCTURE] | The lines need replacement with a description-of-replacement (synthesize a spine from buried fragments; reshape a list into hooks). | lines: A-B, rationale: <one sentence>, replacement_description: <what to synthesize, sourced from where> |
[REWRITE-HEADING] | A heading is generic or misleading and should reflect the section's actual content. | line: N, current: <text>, proposed: <text> |
[REORDER] | A whole ## section is in the wrong curriculum position. | from_line: N, to_line: M (move section starting at N to immediately before section at M), rationale: <one sentence> |
[ADD-CALLOUT] | A surface in the inventory has a callout candidate but no inline qualifier in the README. | at_line: N, source_ref: <file:line>, text: <one or two sentences> |
Do not use any other action types. If a finding does not fit one of the above, it is out of scope for cleanup mode and belongs to a full rewrite via readme-draft.
The diagnosis procedure
Step 1: Map the existing README
Produce a section index for your own use (not part of the output):
- Heading at line N → topic / inventory entry it covers.
- For each section: 1-line summary of its contribution.
This lets you reason about REORDER actions and identify duplicated material.
Step 2: Spine differential
Compare the existing README's opening (typically the first 30-60 lines) to the source-only spine candidate from the analysis output.
Three outcomes:
- Match: existing opening matches the spine candidate's mental model. No spine actions; proceed to other findings.
- Drift: existing opening covers some of the spine but is buried, padded, or misordered. Action:
[RESTRUCTURE] the opening, [RELOCATE] buried material to the front, or both.
- Wrong shape: existing opening is a flat capability list, pure marketing pitch, or premature deep-spine. Action:
[RESTRUCTURE] with replacement_description: "Replace with the source-only spine candidate from analysis output."
When in doubt: the source-only spine wins. Do not preserve the existing opening's framing to "be conservative."
Step 3: Section-by-section action mining
Walk each section. For each, identify findings of these kinds:
- Banned phrases: audience disclaimers, "Why not X?" openings, competitor-suggestion paragraphs, hedging, marketing language, em-dashes. →
[CUT].
- Generic heading: a heading like "Usage" or "Examples" that masks specific content. →
[REWRITE-HEADING].
- Curriculum drift: a section is in the wrong place (advanced surface introduced before basic, callout collected at the end). →
[REORDER] or [RELOCATE].
- Missing callouts: an API in the inventory has a callout candidate in source but no inline qualifier in the README. →
[ADD-CALLOUT].
- Buried spine: spine material exists in the README but appears after a wall of capability bullets or a pitch paragraph. →
[RELOCATE] to top, or [RESTRUCTURE] opening + relocate.
- Capability bullets with no curriculum value (a flat list of features with no worked example introduction). →
[RESTRUCTURE] into hook paragraphs or [CUT] if redundant with a later worked section.
Step 4: Inventory coverage check
Every entry in the API surface inventory should be present in the README. For each missing entry:
- If the entry is small (one method, one type) and the README has a section it logically belongs in: this is OUT OF SCOPE for cleanup mode. Note it for the supervisor; do not emit an action.
- If the entry is large (a whole new surface area): the README needs full-rewrite mode (
readme-draft), not cleanup. Note it for the supervisor.
Cleanup does not ADD new sections documenting new surfaces. That is the rewrite path.
Step 5: Em-dash inventory
Run a final pass for — characters. Each one is a [CUT] entry with rationale "em-dash; rewrite sentence per [[feedback_no_em_dashes]]". The readme-edit skill knows to rewrite the sentence rather than substitute punctuation; you do not need to specify how.
Reorder discipline
A [REORDER] action is disruptive. Use it sparingly:
- Only when the existing section's content is correct but in the wrong curriculum position.
- Never to move a section just because "it would flow better" — flow is the writer's craft, not a mechanical action.
- When in doubt, decompose into
[CUT] + [RESTRUCTURE] (write the section in place) rather than [REORDER].
A README that needs more than 2-3 reorders is a candidate for full rewrite via readme-draft, not cleanup.
Output contract
Produce a single Markdown document with this structure:
## Spine assessment
<one paragraph: match | drift | wrong shape; what the differential is>
## Actions
1. [TYPE] lines: A-B (or line: N, or from_line/to_line, or at_line)
rationale: <one sentence>
<type-specific fields, e.g. target / replacement_description / current/proposed / source_ref/text>
2. ...
## Out-of-scope findings (note for supervisor)
- <finding>
- ...
The ## Actions list is the contract consumed by readme-edit. Entries must be numbered, line-anchored, and type-tagged. No prose narrative between entries — the rationale field is the only prose per action.
Length expectations
A clean README needs 5-15 actions. A bloated README typically needs 30-60. If your action list exceeds 80 entries, the README probably warrants full rewrite via readme-draft rather than cleanup; flag this in the "Out-of-scope findings" section.
Execution
This sub-skill runs as a single Opus agent dispatched by the supervisor. You do NOT dispatch further sub-agents. All diagnosis happens in your own context:
- Read the source-analysis output (spine, callouts, inventory). Internalize the spine candidate BEFORE Step 2.
- Read the existing README in full.
- Run the script:
bash .claude/skills/readme/readme-check.sh <readme-path> and --callouts mode. Use STRONG findings as automatic candidates for [CUT] actions.
- Walk through Steps 1-5 above in order. Do not edit the README; only diagnose.
- Emit the structured action list per the output contract.
The diagnosis is one cohesive document. Do not split it into multiple files or dispatch parallel agents per section — section-by-section actions are interdependent (a [RELOCATE] from Section 3 to Section 1 must be aware of what [RESTRUCTURE] actions modified Section 1).
