[Feature]: /speckit.revise - update the current spec without rewriting artifacts

[harsha09]

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

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

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

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

4. 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.

5. Spec exists, plan/tasks don’t yet. I revise first, then /speckit.plan or /speckit.tasks so they start from the updated contract.

6. 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

[harsha09]

@mnriem
I have a draft on #4158. Happy to open a PR once this shape looks OK.

[github-actions]

Feature assessment — speckit-revise-command · Stage 1/5: Intake

Idea Intake: /speckit.revise Command

• Slug: speckit-revise-command
• Created: 2026-08-19
• Source: GitHub issue [Feature]: /speckit.revise - update the current spec without rewriting artifacts #4156 (github/spec-kit), comment with draft PR Feat/4156 Revise Specs #4158
• Type: new-capability

Idea (as captured)

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.

Add a core command /speckit.revise for requirement changes on the current feature (same specs/ folder). It is not specify, clarify, or converge.

• 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.
• 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.

Raised by: harsha09 (external contributor). Related draft PR: #4158 (draft, self-described as not yet ready).

Restated

The proposal adds a /speckit.revise command that mutates the current feature's spec artifacts in-place — marking old requirements as SUPERSEDED or RETIRED, 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

• Raised by: harsha09 (external contributor)
• Trigger: Repeated pain encountered when requirements change mid-flight or post-implementation; agents currently "fix" this by silently rewriting spec.md and regenerating tasks.md, losing history and omitting remove-old-code tasks

First-Glance Unknowns

• [NEEDS CLARIFICATION: How should revise interact with the checklist system (checklists/requirements.md)?]
• [NEEDS CLARIFICATION: Should revisions.md be tracked as a recognized artifact by check-prerequisites scripts?]
• [NEEDS CLARIFICATION: How does revise handle a feature directory where plan.md exists but tasks.md does not?]
• [NEEDS CLARIFICATION: Is revisions.md a per-feature artifact (lives in specs/<feature>/) or a project-level log?]
• [NEEDS CLARIFICATION: Draft PR Feat/4156 Revise Specs #4158 exists — is this assessment meant to validate/shape the idea before the PR is reviewed, or does the PR already represent a near-final implementation?]

---

Posted on behalf of @mnriem by GitHub Copilot (model: claude-sonnet-4.6, autonomous)

Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for issue #4156 · 627.1 AIC · ⌖ 18.4 AIC · ⊞ 38.1K · ◷

[github-actions]

Feature assessment — speckit-revise-command · Stage 2/5: Research

Idea Research: /speckit.revise Command

• Slug: speckit-revise-command
• Created: 2026-08-19
• Evidence confidence (overall): medium

Users & Demand

• Single reporter with concrete use cases: harsha09 (issue [Feature]: /speckit.revise - update the current spec without rewriting artifacts #4156) provided 6 detailed use cases and a full acceptance criteria list, suggesting real, lived experience rather than speculative demand — confidence: medium (one source, external contributor, no corroboration from maintainers or other users yet) [source: github.com/[Feature]: /speckit.revise - update the current spec without rewriting artifacts #4156] (policy: allowlisted)
• Draft PR already exists: The reporter opened draft PR Feat/4156 Revise Specs #4158 within hours of filing the issue, including a manual test walkthrough across 7 commands — indicates strong personal motivation and willingness to contribute [source: github.com/Feat/4156 Revise Specs #4158] (policy: allowlisted)
• No other open issues requesting this feature were found in the repository search. [NEEDS CLARIFICATION: broader community demand is not yet established]

Prior Art

• /speckit.converge addresses "spec is stable, code lagged" — the inverse of this request; confirmed by codebase review of templates/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: codebase templates/commands/converge.md] (confidence: high, cited)
• /speckit.checklist already uses an append-only, never-rewrite pattern — another internal precedent. [source: codebase templates/commands/checklist.md] (confidence: high, cited)
• No existing revise.md template found in templates/commands/ — the command does not exist in any form today. [source: filesystem scan] (confidence: high, cited)
• Git history can partially substitute (diff 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

• What users do today: agents rewrite spec.md and regenerate tasks.md when asked to apply a requirement change. No guard exists in current specify or converge templates against overwrites. [source: codebase + issue [Feature]: /speckit.revise - update the current spec without rewriting artifacts #4156] (confidence: medium)
• Cost of doing nothing: requirement changes continue to silently erase history; "remove old code" tasks are systematically missed post-implementation; teams cannot audit what was dropped.

Data & Constraints

• A new revise.md in templates/commands/ follows the established convention; adding it requires updating src/specify_cli/ install wiring — mechanical but non-trivial. [source: codebase src/specify_cli/commands/] (confidence: high, cited)
• No SUPERSEDED/RETIRED markers exist anywhere in current command templates; implementing the "ignore dead lines" requirement in implement, analyze, taskstoissues, and converge touches 4+ existing templates. [source: codebase grep — zero matches] (confidence: high, cited)
• PR Feat/4156 Revise Specs #4158 already contains a proposed implementation; this assessment renders an independent verdict.

Evidence Against the Idea

• Scope width: the feature requires changes to at least 5 existing templates plus a new template plus install wiring. Risk of unintended behavioral changes in existing commands is real.
• Single-user signal: demand rests on one reporter; no maintainer endorsement or community upvote signal found.
• Agent compliance gap: enforcement of "ignore SUPERSEDED/RETIRED/CANCELLED" is instruction-level (in command prompts), not enforced by tooling — compliance depends on agent behavior and is untestable without live agent runs.
• Git alternative: for teams using git, diff history of spec.md already records what changed; the proposal adds value mainly for agent-visible in-file context.

Gaps & Open Questions

• [NEEDS CLARIFICATION: Is there community demand beyond the single reporter?]
• [NEEDS CLARIFICATION: What is maintainer appetite for a 5+ template cross-cutting change?]
• [NEEDS CLARIFICATION: Should converge also respect SUPERSEDED/RETIRED markers?]
• [NEEDS CLARIFICATION: How does revisions.md integrate with check-prerequisites scripts?]

Sources

• [Feature]: /speckit.revise - update the current spec without rewriting artifacts #4156 (host: github.com, policy: allowlisted)
• Feat/4156 Revise Specs #4158 (host: github.com, policy: allowlisted)
• Codebase: templates/commands/converge.md, checklist.md, implement.md, src/specify_cli/commands/ (local)

---

Posted on behalf of @mnriem by GitHub Copilot (model: claude-sonnet-4.6, autonomous)

Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for issue #4156 · 627.1 AIC · ⌖ 18.4 AIC · ⊞ 38.1K · ◷

[github-actions]

Feature assessment — speckit-revise-command · Stage 3/5: Problem

Problem Definition: /speckit.revise Command

• Slug: speckit-revise-command
• Created: 2026-08-19
• Inputs used: intake.md | research.md

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.md and regenerating tasks.md, erasing the audit trail and omitting tasks to remove or replace code that was built against superseded requirements.

Affected Users & Stakeholders

• Users: Development teams using Spec Kit with AI agents who need to change a requirement after /speckit.specify has run — they lose history and miss cleanup work today.
• Users: Teams that have already run /speckit.implement and need to update requirements — they currently have no supported path that produces remove-old-code tasks.
• Stakeholders: Spec Kit maintainers — a new command touches 5+ existing templates and install wiring, representing non-trivial maintenance surface.

Goals

• Provide a single, explicitly-named command for applying a requirement change to an existing feature directory (same folder, never a new one).
• Preserve the audit trail: old requirement lines stay in-place, annotated SUPERSEDED by {new-id} or RETIRED, never deleted.
• When tasks.md exists, only append — never rewrite. Appended tasks cover both add-new-code and remove-old-code work.
• Prevent agents from treating SUPERSEDED/RETIRED lines as active requirements in implement, analyze, and taskstoissues.

Non-Goals

• Applying the change to application code (that is /speckit.implement's job).
• Opening a new feature directory (that is /speckit.specify's job).
• Answering unknown questions before a first plan (that is /speckit.clarify's job).
• Reconciling code drift when the spec didn't move (that is /speckit.converge's job).
• Providing a full versioned history system — revisions.md is a lightweight dated ID log, not a full changelog.

Success Metrics

• After running /speckit.revise on a feature where /speckit.implement has 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.implement skips lines marked SUPERSEDED, RETIRED, or CANCELLED in tasks.md when planning work. (baseline: no such guard exists today)
• Running revise twice for the same delta is a no-op — no new R# is added to revisions.md. (baseline: not applicable today)
• specify init --integration <agent> installs a /speckit.revise command 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

• [NEEDS CLARIFICATION: Should converge also respect SUPERSEDED/RETIRED markers, or is that too much cross-command coupling for v1?]
• [NEEDS CLARIFICATION: How should revisions.md be reflected in check-prerequisites scripts?]
• [NEEDS CLARIFICATION: Are before_revise/after_revise consistent with the current git extension's hook naming conventions?]

---

Posted on behalf of @mnriem by GitHub Copilot (model: claude-sonnet-4.6, autonomous)

Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for issue #4156 · 627.1 AIC · ⌖ 18.4 AIC · ⊞ 38.1K · ◷

[github-actions]

Feature assessment — speckit-revise-command · Stage 4/5: Concept

Concept: /speckit.revise Command

• Slug: speckit-revise-command
• Created: 2026-08-19
• Recommended option: Option A — New core command with cross-cutting guards

Options

Option A — New core command with cross-cutting guards

• Sketch: Add templates/commands/revise.md as 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 lightweight revisions.md ID log. Simultaneously, guard language ("skip SUPERSEDED, RETIRED, CANCELLED lines") is added to implement.md, analyze.md, taskstoissues.md, and optionally converge.md. specify init is updated to install revise for all integrations.
• Appetite: medium (weeks) — new template is straightforward; cross-cutting guard additions to 4 existing templates require careful wording and testing.
• Trade-offs: Wins — complete solution, consistent with Spec Kit's instruction-driven architecture; agents get explicit guidance in every relevant command. Sacrifices — widest blast radius for merge conflicts and regressions; guard language must be LLM-reliable (only verifiable via agent runs, not unit tests).
• Rabbit holes: Getting SUPERSEDED/RETIRED detection reliable across all agent implementations; defining the revisions.md format precisely enough that the idempotency guarantee holds across agent runs.

Option B — Revise command only, no cross-cutting guards

• Sketch: Add revise.md only. Leave implement, analyze, taskstoissues unchanged. Markers are in the spec but agents without a guard may still treat them as active.
• Appetite: small (days) — single new file, no changes to existing templates.
• Trade-offs: Wins — minimal risk, fast to ship. Sacrifices — core problem (agents acting on dead requirements) is only partially addressed; "ignore dead lines" AC is not met.
• Rabbit holes: Users assume the markers are respected; agents don't honor them; silent wrong behavior is worse than no feature.

Option C — Do nothing / lightweight documentation

• Sketch: Add a doc entry describing the existing workaround: manually annotate spec.md, then run /speckit.converge. No new command.
• Appetite: small (days).
• Trade-offs: Wins — zero code risk. Sacrifices — no automation; "remove old code" tasks still missing; agents can still rewrite spec.md if asked without the workaround.
• Rabbit holes: Documentation of a manual process agents don't enforce will be ignored in agentic workflows.

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.md template and install wiring first (verifiable), then add guard language to implement, analyze, taskstoissues (additive, low-regression risk), then optionally converge post-v1.

Out of Scope (for the recommended option)

• Automated tooling enforcement of markers (compile-time / lint-time) — agents read instruction text
• New feature directory creation or spec file creation
• Application code changes
• Full versioned changelog (revisions.md is an ID log only)
• converge guard (deferred pending clarification on coupling appetite)

Assumptions to Validate

• AI agents across major integrations will reliably skip lines annotated SUPERSEDED/RETIRED/CANCELLED when guard instructions are present in implement.md and analyze.md.
• The revisions.md idempotency rule is implementable as a simple existence check on the annotation in spec.md.
• specify init wiring 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 @mnriem by GitHub Copilot (model: claude-sonnet-4.6, autonomous)

Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for issue #4156 · 627.1 AIC · ⌖ 18.4 AIC · ⊞ 38.1K · ◷

[github-actions]

Feature assessment — speckit-revise-command · Stage 5/5: Decision — verdict needs-clarification

Decision: /speckit.revise Command

• Slug: speckit-revise-command
• Decided: 2026-08-19
• Verdict: needs-clarification
• Artifacts reviewed: intake.md | research.md | problem.md | concept.md

Scorecard

Criterion	Rating	Justification
Problem validity	strong	Real problem, clearly articulated: no command exists for in-place spec mutation; silent-rewrite behavior confirmed by codebase review. Six concrete use cases provided.
Evidence strength	weak	Demand comes from a single external contributor; no maintainer endorsement, no community upvotes, no corroborating issues. Draft PR #4158 shows personal commitment but not broad signal.
Value vs. inaction	adequate	Cost of doing nothing is real: lost audit trail, missed remove-old-code tasks, spec integrity degradation. Git history partially substitutes but agents cannot use it inline.
Feasibility / appetite	adequate	Medium appetite (weeks) credible given existing template architecture. Draft PR #4158 already exists with a manual test walkthrough. Cross-cutting guard additions are the main risk surface.
Strategic fit	adequate	Consistent with Spec Kit's instruction-driven architecture. Fills a genuine lifecycle gap. Does not duplicate existing commands.
Risk posture	adequate	Key risks identified: cross-cutting guard reliability (LLM-dependent), scope width (5+ templates), maintenance burden. Manageable with phased delivery. No unmitigated blockers.

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 go requires evidence strength of adequate or better; weak evidence mandates needs-clarification, never go.

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

• [NEEDS CLARIFICATION: Has a maintainer reviewed and expressed appetite for this cross-cutting change?]
• [NEEDS CLARIFICATION: Is draft PR Feat/4156 Revise Specs #4158 the intended implementation vehicle, or should a fresh implementation be started post-assessment?]
• [NEEDS CLARIFICATION: Is there community demand beyond the single reporter?]
• [NEEDS CLARIFICATION: Should converge respect SUPERSEDED/RETIRED markers in v1, or is that deferred?]

Revisit stage: research (gather maintainer + community signal), then decide.

---

Posted on behalf of @mnriem by GitHub Copilot (model: claude-sonnet-4.6, autonomous)

Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for issue #4156 · 627.1 AIC · ⌖ 18.4 AIC · ⊞ 38.1K · ◷