git:20260709.322dd02 to git:20260714.a0e0c5f

---

name: spec-revise

description: Edit a single proposal.md section (why / what / how / risk). A full rewrite goes through $spec-propose. After editing, the HARD GATE must run again.

---

<!-- GENERATED from core/commands/revise.md — edit the core file and run node tools/generate.mjs; hand edits will be overwritten -->

# $spec-revise

Target section: $ARGUMENTS

## Flow

1. Parse the parameter:

| Parameter | Section edited |

|---|---|

| `why` | `## Why` |

| `what` | `## What` |

| `how` | `## How` |

| `risk` | `## Risk` |

| none | ask the user which section to edit by presenting numbered options: "Which section to edit? 1) why 2) what 3) how 4) risk" |

2. Read `spec/changes/<name>/proposal.md`, locate the target section

3. **Remove the old `<!-- APPROVED: ... -->` approval marker** (any revision invalidates the old approval)

4. Edit the target section, **leaving the other sections untouched**

5. **Re-emit the HARD GATE**

## HARD GATE re-emission

Any revision must pass through the HARD GATE again:

```

<HARD-GATE>

=== Proposal revised (<section>) ===

Path: spec/changes/<name>/proposal.md

Changes — same explanation layer as propose's gate, scoped to the edit:

<the revised decision in one plain sentence>

(never paste the proposal line verbatim; define domain terms at first use)

(the old APPROVED marker has been removed)

Next:

✅ Looks good → run $spec-apply to start implementing

apply will automatically append the new <!-- APPROVED: ... --> marker

🔧 Edit another section → $spec-revise [why | what | how | risk]

💭 Want to discuss more → $spec-chat

🔄 Direction changed, redo research → $spec-research "<new direction>"

</HARD-GATE>

```

**NEVER carry over the old approval state.**

## When to use

- During the HARD GATE wait the user says "in How, change Caffeine to Redis" → `$spec-revise how`

- Mid-implementation you find Risk missed an item → `$spec-revise risk` to add it

- After brainstorming in `$spec-chat` you decide to change Why → `$spec-revise why`

## Boundary with other commands

| Scenario | Use |

|---|---|

| Goal changed, needs fresh research | `$spec-research <new direction>` |

| Just want to talk, touch no file | `$spec-chat` |

| Full rewrite of the proposal | `$spec-propose` (revise edits a single section only; propose has hooks guarding TBD / single-change, revise has no hook) |

| Local edit of one proposal section | `$spec-revise [section]` |

## Anti-patterns

- ❌ Editing a section without re-running the HARD GATE before continuing

- ❌ Not removing the old APPROVED marker (letting the `$spec-apply` hook think it's approved)

- ❌ "Tidying up" other sections while editing one (don't touch what the user didn't ask for)