/readme-edit: apply a structured action list to a README
The task is:
$ARGUMENTS
Inputs required:
readme_path: path to the README file to edit.action_list: structured findings document produced by readme-analyze-existing, containing one or more entries of the types listed below.
This sub-skill is mechanical. The action list is already approved. Do not re-diagnose, re-evaluate, or second-guess entries. Apply every entry in the list, in order, unless an entry requests an addition that is NOT in the allowed list (see "Out-of-scope additions" below).
Action type semantics
| Type |
What it means |
What to do |
[CUT] |
Delete the line range entirely. |
Remove those lines. No replacement. |
[RELOCATE] |
Move the line range to the target location specified in the entry. |
Cut from source; insert at target. Preserve the content verbatim. |
[RESTRUCTURE] |
Replace the line range with the description-of-replacement in the entry. |
Synthesize replacement content from the entry's rationale and the existing README material. Do NOT invent new content beyond what the rationale describes. |
[REWRITE-HEADING] |
Change heading text from current to proposed. |
Replace only the heading text. Keep the heading level (##, ###, etc.) unchanged. |
[REORDER] |
Move the entire section (from the heading at from_line to just before the next ## heading at the same level) to immediately before the section at to_line. |
Relocate the whole section block as a unit. |
[ADD-CALLOUT] |
Insert a callout paragraph at the specified location, sourced from the entry's source reference. |
Insert one or two sentences at the specified line. Content must come from the source reference named in the entry (scaladoc, test, implementation comment). Do not invent. |
Em-dash rewriting (special case)
When the action list contains [CUT] entries on em-dashes, do NOT mechanically substitute ; or -. The fix is to REWRITE the sentence so the em-dash is not needed.
Per-context options (lifted verbatim from the project rule):
- Incidental clause ("kyo-compat — built for library authors — supports all 6 backends"): use commas, or restructure so the clause is no longer parenthetical. "kyo-compat supports all 6 backends. Library authors are the target audience."
- Parenthetical aside ("the runtime — ZIO, CE, or Future — is chosen at deploy time"): use parentheses, or fold the aside into the main clause. "the runtime (ZIO, CE, or Future) is chosen at deploy time" OR "the runtime is chosen at deploy time: ZIO, CE, or Future."
- Joining two thoughts ("Flow is a plan — not an execution"): use a period and start a new sentence, or use a colon if the second thought elaborates the first. "Flow is a plan, not an execution." OR "Flow is a plan: not an execution."
- Setting off a list or example ("supported runtimes — ZIO, Cats Effect, Future"): use a colon. "supported runtimes: ZIO, Cats Effect, Future."
- DO NOT mechanically substitute
; for —. A semicolon is correct only when joining two complete, independent clauses; most em-dash usages are not that case. Overusing ; produces awkward staccato prose.
- DO NOT substitute a hyphen (
-) for an em-dash. It looks wrong and reads worse.
- After removing an em-dash, READ THE SENTENCE OUT LOUD (or simulate the read). If it sounds awkward or staccato, rewrite further.
Out-of-scope additions
If the action list contains an entry requesting an addition that is NOT in the allowed list below, stop and report it as out-of-scope. Do not silently apply.
Allowed (these may appear in [RESTRUCTURE] or [ADD-CALLOUT] entries):
- Synthesize a 1-2 paragraph spine from existing material already in the README.
- Rewrite a flat heading to a content-specific one based on what the section already discusses.
- Reshape a capability list into hooks derived from existing material.
- Add an inline callout from a named source:
Note: / Unlike / Caution: annotations in scaladoc, tests, or implementation comments.
NOT allowed (reject and report if the action list requests these):
- A new section documenting an API surface the existing README did not cover.
- New code examples demonstrating something new.
- "Frequently asked questions" or similar new sections with no basis in existing content.
Execution order
- Read
readme_path in full.
- Apply actions in the order given in the action list. Use
Edit for each entry.
- After all actions are applied, run the post-edit check (below).
Post-edit check
After applying all actions:
Diff size sanity. Confirm the diff is roughly stable or a decrease. A small increase is acceptable when a [RESTRUCTURE] promoted a buried spine (relocated text now appears earlier, not duplicated). A large increase signals scope creep: a RESTRUCTURE entry was interpreted too broadly. Stop and audit what was added.
Banned phrase scan. Confirm no banned phrases survived: audience disclaimers used defensively, "Why not X?" in the opening, competitor-suggestion paragraphs, em-dashes. Flag any that remain so downstream readme-verify has them on record.
Script check. Run:
bash .claude/skills/readme/readme-check.sh <readme-path>
If STRONG findings remain that the action list should have addressed, stop and report them. Do not silently pass.
1---2name: readme-edit3description: Apply a structured action list (CUT/RELOCATE/RESTRUCTURE/REWRITE-HEADING/REORDER/ADD-CALLOUT) to a README. Mechanical only; no diagnosis. Em-dash removal must rewrite the sentence, not substitute punctuation.4---56# /readme-edit: apply a structured action list to a README78The task is:910$ARGUMENTS1112**Inputs required:**13- `readme_path`: path to the README file to edit.14- `action_list`: structured findings document produced by `readme-analyze-existing`, containing one or more entries of the types listed below.1516This sub-skill is mechanical. The action list is already approved. Do not re-diagnose, re-evaluate, or second-guess entries. Apply every entry in the list, in order, unless an entry requests an addition that is NOT in the allowed list (see "Out-of-scope additions" below).1718---1920## Action type semantics2122| Type | What it means | What to do |23|---|---|---|24| `[CUT]` | Delete the line range entirely. | Remove those lines. No replacement. |25| `[RELOCATE]` | Move the line range to the target location specified in the entry. | Cut from source; insert at target. Preserve the content verbatim. |26| `[RESTRUCTURE]` | Replace the line range with the description-of-replacement in the entry. | Synthesize replacement content from the entry's rationale and the existing README material. Do NOT invent new content beyond what the rationale describes. |27| `[REWRITE-HEADING]` | Change heading text from `current` to `proposed`. | Replace only the heading text. Keep the heading level (`##`, `###`, etc.) unchanged. |28| `[REORDER]` | Move the entire section (from the heading at `from_line` to just before the next `##` heading at the same level) to immediately before the section at `to_line`. | Relocate the whole section block as a unit. |29| `[ADD-CALLOUT]` | Insert a callout paragraph at the specified location, sourced from the entry's source reference. | Insert one or two sentences at the specified line. Content must come from the source reference named in the entry (scaladoc, test, implementation comment). Do not invent. |3031---3233## Em-dash rewriting (special case)3435When the action list contains `[CUT]` entries on em-dashes, do NOT mechanically substitute `;` or `-`. The fix is to REWRITE the sentence so the em-dash is not needed.3637Per-context options (lifted verbatim from the project rule):3839- **Incidental clause** ("kyo-compat — built for library authors — supports all 6 backends"): use commas, or restructure so the clause is no longer parenthetical. "kyo-compat supports all 6 backends. Library authors are the target audience."40- **Parenthetical aside** ("the runtime — ZIO, CE, or Future — is chosen at deploy time"): use parentheses, or fold the aside into the main clause. "the runtime (ZIO, CE, or Future) is chosen at deploy time" OR "the runtime is chosen at deploy time: ZIO, CE, or Future."41- **Joining two thoughts** ("Flow is a plan — not an execution"): use a period and start a new sentence, or use a colon if the second thought elaborates the first. "Flow is a plan, not an execution." OR "Flow is a plan: not an execution."42- **Setting off a list or example** ("supported runtimes — ZIO, Cats Effect, Future"): use a colon. "supported runtimes: ZIO, Cats Effect, Future."43- **DO NOT** mechanically substitute `;` for `—`. A semicolon is correct only when joining two complete, independent clauses; most em-dash usages are not that case. Overusing `;` produces awkward staccato prose.44- **DO NOT** substitute a hyphen (`-`) for an em-dash. It looks wrong and reads worse.45- After removing an em-dash, READ THE SENTENCE OUT LOUD (or simulate the read). If it sounds awkward or staccato, rewrite further.4647---4849## Out-of-scope additions5051If the action list contains an entry requesting an addition that is NOT in the allowed list below, stop and report it as out-of-scope. Do not silently apply.5253**Allowed** (these may appear in `[RESTRUCTURE]` or `[ADD-CALLOUT]` entries):54- Synthesize a 1-2 paragraph spine from existing material already in the README.55- Rewrite a flat heading to a content-specific one based on what the section already discusses.56- Reshape a capability list into hooks derived from existing material.57- Add an inline callout from a named source: `Note:` / `Unlike` / `Caution:` annotations in scaladoc, tests, or implementation comments.5859**NOT allowed** (reject and report if the action list requests these):60- A new section documenting an API surface the existing README did not cover.61- New code examples demonstrating something new.62- "Frequently asked questions" or similar new sections with no basis in existing content.6364---6566## Execution order67681. Read `readme_path` in full.692. Apply actions in the order given in the action list. Use `Edit` for each entry.703. After all actions are applied, run the post-edit check (below).7172---7374## Post-edit check7576After applying all actions:77781. **Diff size sanity.** Confirm the diff is roughly stable or a decrease. A small increase is acceptable when a `[RESTRUCTURE]` promoted a buried spine (relocated text now appears earlier, not duplicated). A large increase signals scope creep: a `RESTRUCTURE` entry was interpreted too broadly. Stop and audit what was added.79802. **Banned phrase scan.** Confirm no banned phrases survived: audience disclaimers used defensively, "Why not X?" in the opening, competitor-suggestion paragraphs, em-dashes. Flag any that remain so downstream `readme-verify` has them on record.81823. **Script check.** Run:83 ```84 bash .claude/skills/readme/readme-check.sh <readme-path>85 ```86 If STRONG findings remain that the action list should have addressed, stop and report them. Do not silently pass.
getkyo