/readme-edit: apply a structured action list to a README

---
name: readme-edit
description: 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.
argument-hint: <readme-path> <action-list>
---

# /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

1. Read `readme_path` in full.
2. Apply actions in the order given in the action list. Use `Edit` for each entry.
3. After all actions are applied, run the post-edit check (below).

---

## Post-edit check

After applying all actions:

1. **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.

2. **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.

3. **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.