Repository navigation
[Feature]: /speckit.revise - update the current spec without rewriting artifacts #4156
Description
Problem Statement
I'm frustrated when requirements change after /speckit.specify, sometimes after /speckit.implement, and the only options are bad ones.
/speckit.specify always opens a new feature folder. /speckit.clarify asks questions I already answered. /speckit.converge assumes the spec didn't move. So agents fix it by rewriting spec.md and regenerating tasks.md. History disappears. I can't tell what was dropped, and if we already shipped, nothing says "remove the old code."
I need a way to add or drop a requirement on the current feature: keep the old AC/FR visible as superseded or retired, add a new ID if something replaces it, and if plan/tasks already exist, only append, including remove-code work when implementation is already done. Not a full rewrite of the artifacts.
Proposed Solution
Add a core command /speckit.revise for requirement changes on the current feature (same specs/ folder). It is not specify, clarify, or converge.
What it should do:
- Never rewrite spec.md, plan.md, or tasks.md. Never open a new feature directory. Never touch application code.
- Add a requirement -> new ID (FR/AC/SC).
- Replace a live one -> mark the old line SUPERSEDED by {new-id}, add the new ID. Don't edit the old line to mean something else.
- No longer valid -> mark the old line RETIRED. No new ID.
- revisions.md is only a dated list of those IDs, not a second spec.
- If plan.md / tasks.md exist, only append. After implement: tasks to add new code and/or remove old code. Open tasks for a dead ID get cancelled/superseded; finished [x] tasks stay.
- Then I run /speckit.implement for the new/cleanup tasks.
Duplicates (already true on a live line) should be a no-op. Implement/analyze/taskstoissues should ignore SUPERSEDED, RETIRED, and CANCELLED lines. Git should have before/after revise hooks like the other commands.
Alternatives Considered
A few things I tried or thought about:
- Run /speckit.specify again. Always creates 002-….. Fine for a new feature, wrong for “this AC on the current spec is no longer valid.”
- /speckit.clarify. It’s for unknowns before the first plan (questions). I already know the change.
- /speckit.converge. That’s “spec is stable, code lagged.” Opposite of a requirement change. After a retire it would try to put the old behavior back.
- Edit spec.md / regenerate /speckit.tasks by hand. This is what agents do today. They rewrite the files. History and “remove the old code” both get lost.
- Make specify update in place. Mixes “new feature” and “change this feature.” Breaks teams that want a new folder per change.
That’s why I want a separate /speckit.revise instead of stretching specify/clarify/converge.
Component
Specify CLI (initialization, commands)
AI Agent (if applicable)
None
Use Cases
-
After implement, product says password login is dead, SSO only. I need the old FR marked superseded/retired, a new FR for SSO, and tasks to remove the password code and add SSO. I don’t want tasks.md regenerated.
-
Mid-flight, before implement, we add one AC (expired session -> login page). Spec gets a new AC id. Plan/tasks only gain a small append if they already exist. No new 002- folder.
-
A success criterion is no longer valid. Mark it RETIRED. If we already built toward it, append a cleanup task. If we haven’t implemented yet, just cancel the open tasks.
-
Same revise run twice (or I ask to add an AC that’s already live). Should be a no-op, no new R#, no file rewrite.
-
Spec exists, plan/tasks don’t yet. I revise first, then /speckit.plan or /speckit.tasks so they start from the updated contract.
-
Two people on the same feature: one shipped, QA/product changes the requirement. The folder still has a readable trail (old line + new id), not a silently rewritten spec.
Acceptance Criteria
- specify init installs /speckit.revise for the active agent (same as specify/plan/tasks).
- It never creates a new specs/ folder and never rewrites spec.md / plan.md / tasks.md from scratch.
- Add -> new FR/AC/SC id. Replace -> old line SUPERSEDED by {new-id}, new id added. Drop -> old line RETIRED. Live lines don’t contradict each other.
- revisions.md is only a dated id list. Re-running the same delta is a no-op (no new R#).
- If plan/tasks exist, they are only appended. After implement, retiring/superseding a requirement adds remove-old-code work (and add-new-code when something replaces it). Open tasks for a dead id are cancelled/superseded; [x] tasks stay.
- Revise does not edit application code. /speckit.implement does the add/remove. Implement, analyze, and taskstoissues ignore SUPERSEDED / RETIRED / CANCELLED lines.
- Works before plan/tasks too: only spec (+ log) changes; next step is plan or tasks, not a regenerated feature.
- Docs (README / living-spec / agentic-sdd) describe when to use revise vs specify / clarify / converge.
- Git has before/after revise hooks. Automated tests cover install + these rules. A sample project run shows the files weren’t regenerated.
Additional Context
No response
Activity
harsha09 commentedon Aug 16, 2026
@mnriem
I have a draft on #4158. Happy to open a PR once this shape looks OK.
github-actions commentedon Aug 19, 2026
Feature assessment — speckit-revise-command · Stage 1/5: Intake
Idea Intake: /speckit.revise Command
Idea (as captured)
Raised by: harsha09 (external contributor). Related draft PR: #4158 (draft, self-described as not yet ready).
Restated
The proposal adds a
/speckit.revisecommand that mutates the current feature's spec artifacts in-place — marking old requirements asSUPERSEDEDorRETIRED, adding new requirement IDs, and appending (never rewriting) tasks.md/plan.md — so that requirement changes after specification or implementation leave an auditable trail and trigger the right cleanup/addition work.Origin & Context
First-Glance Unknowns
checklists/requirements.md)?]revisions.mdbe tracked as a recognized artifact by check-prerequisites scripts?]revisions.mda per-feature artifact (lives inspecs/<feature>/) or a project-level log?]Posted on behalf of
@mnriemby GitHub Copilot (model: claude-sonnet-4.6, autonomous)github-actions commentedon Aug 19, 2026
Feature assessment — speckit-revise-command · Stage 2/5: Research
Idea Research: /speckit.revise Command
Users & Demand
Prior Art
/speckit.convergeaddresses "spec is stable, code lagged" — the inverse of this request; confirmed by codebase review oftemplates/commands/converge.md. The append-only contract in converge (it never rewrites tasks.md) is the closest architectural precedent; the proposed revise command borrows the same append-only principle. [source: codebasetemplates/commands/converge.md] (confidence: high, cited)/speckit.checklistalready uses an append-only, never-rewrite pattern — another internal precedent. [source: codebasetemplates/commands/checklist.md] (confidence: high, cited)revise.mdtemplate found intemplates/commands/— the command does not exist in any form today. [source: filesystem scan] (confidence: high, cited)spec.md), but this gives no in-file audit trail visible to AI agents at command invocation time — the request correctly identifies the gap. [ASSUMPTION — confidence: medium]Market & Context
specifyorconvergetemplates against overwrites. [source: codebase + issue [Feature]: /speckit.revise - update the current spec without rewriting artifacts #4156] (confidence: medium)Data & Constraints
revise.mdintemplates/commands/follows the established convention; adding it requires updatingsrc/specify_cli/install wiring — mechanical but non-trivial. [source: codebasesrc/specify_cli/commands/] (confidence: high, cited)implement,analyze,taskstoissues, andconvergetouches 4+ existing templates. [source: codebase grep — zero matches] (confidence: high, cited)Evidence Against the Idea
Gaps & Open Questions
convergealso respect SUPERSEDED/RETIRED markers?]revisions.mdintegrate with check-prerequisites scripts?]Sources
templates/commands/converge.md,checklist.md,implement.md,src/specify_cli/commands/(local)Posted on behalf of
@mnriemby GitHub Copilot (model: claude-sonnet-4.6, autonomous)github-actions commentedon Aug 19, 2026
Feature assessment — speckit-revise-command · Stage 3/5: Problem
Problem Definition: /speckit.revise Command
Problem Statement
When requirements change on an in-progress or already-implemented feature, Spec Kit has no first-class command for recording that change: agents respond by silently rewriting
spec.mdand regeneratingtasks.md, erasing the audit trail and omitting tasks to remove or replace code that was built against superseded requirements.Affected Users & Stakeholders
/speckit.specifyhas run — they lose history and miss cleanup work today./speckit.implementand need to update requirements — they currently have no supported path that produces remove-old-code tasks.Goals
SUPERSEDED by {new-id}orRETIRED, never deleted.implement,analyze, andtaskstoissues.Non-Goals
/speckit.implement's job)./speckit.specify's job)./speckit.clarify's job)./speckit.converge's job).revisions.mdis a lightweight dated ID log, not a full changelog.Success Metrics
/speckit.reviseon a feature where/speckit.implementhas run: tasks.md contains appended remove-old-code and add-new-code tasks; no existing task or spec line is deleted or rewritten. (baseline: currently not possible without manual edits)/speckit.implementskips lines marked SUPERSEDED, RETIRED, or CANCELLED in tasks.md when planning work. (baseline: no such guard exists today)revisions.md. (baseline: not applicable today)specify init --integration <agent>installs a/speckit.revisecommand for the active agent. (baseline: command does not exist)Cost of Inaction
Without this command, requirement changes on live features are handled by agent improvisation — typically rewriting spec.md and regenerating tasks.md. This systematically: (1) loses the record of what was dropped; (2) generates no tasks to remove code built against dead requirements; (3) sends mixed signals to
implement/analyze(active-looking requirements that are actually obsolete). Spec integrity degrades for iteratively-developed features.Open Questions
convergealso respect SUPERSEDED/RETIRED markers, or is that too much cross-command coupling for v1?]revisions.mdbe reflected in check-prerequisites scripts?]before_revise/after_reviseconsistent with the current git extension's hook naming conventions?]Posted on behalf of
@mnriemby GitHub Copilot (model: claude-sonnet-4.6, autonomous)github-actions commentedon Aug 19, 2026
Feature assessment — speckit-revise-command · Stage 4/5: Concept
Concept: /speckit.revise Command
Options
Option A — New core command with cross-cutting guards
templates/commands/revise.mdas a new core command following the existing markdown template convention. The command annotates spec.md in-place (SUPERSEDED/RETIRED markers), appends tasks.md/plan.md only, and writes a lightweightrevisions.mdID log. Simultaneously, guard language ("skip SUPERSEDED, RETIRED, CANCELLED lines") is added toimplement.md,analyze.md,taskstoissues.md, and optionallyconverge.md.specify initis updated to install revise for all integrations.revisions.mdformat precisely enough that the idempotency guarantee holds across agent runs.Option B — Revise command only, no cross-cutting guards
revise.mdonly. Leaveimplement,analyze,taskstoissuesunchanged. Markers are in the spec but agents without a guard may still treat them as active.Option C — Do nothing / lightweight documentation
/speckit.converge. No new command.Recommendation
Option A — the new core command with cross-cutting guards — is the right approach. The problem's root cause is the absence of both a guarded command and recognition of dead markers in downstream commands. Option B ships the command without the guards and leaves the core failure mode intact. Option C addresses neither. Option A is the only option that meets all stated ACs.
Implementation should be phased: ship
revise.mdtemplate and install wiring first (verifiable), then add guard language toimplement,analyze,taskstoissues(additive, low-regression risk), then optionallyconvergepost-v1.Out of Scope (for the recommended option)
revisions.mdis an ID log only)convergeguard (deferred pending clarification on coupling appetite)Assumptions to Validate
implement.mdandanalyze.md.revisions.mdidempotency rule is implementable as a simple existence check on the annotation in spec.md.specify initwiring for revise follows the same pattern as any other command template — no architectural changes needed. [ASSUMPTION — confidence: high, based on codebase review]Posted on behalf of
@mnriemby GitHub Copilot (model: claude-sonnet-4.6, autonomous)github-actions commentedon Aug 19, 2026
Feature assessment — speckit-revise-command · Stage 5/5: Decision — verdict needs-clarification
Decision: /speckit.revise Command
Scorecard
Verdict & Rationale
needs-clarification — the idea is sound and the concept is well-shaped, but evidence strength is rated weak: demand rests entirely on one external contributor with no maintainer signal or community corroboration. Per the decide command rules, a
gorequires evidence strength ofadequateor better;weakevidence mandatesneeds-clarification, nevergo.Two specific unknowns also need resolution before specification begins: (1) maintainer appetite for a cross-cutting change touching 5+ templates, and (2) the disposition of draft PR #4158.
This is not a kill — the problem is real, the concept is shaped, the draft implementation demonstrates feasibility, and the solution is architecturally consistent with Spec Kit. It is a promising idea blocked on validation of demand and maintainer buy-in.
Blocking questions
convergerespect SUPERSEDED/RETIRED markers in v1, or is that deferred?]Revisit stage: research (gather maintainer + community signal), then decide.
Posted on behalf of
@mnriemby GitHub Copilot (model: claude-sonnet-4.6, autonomous)