Repository navigation
[Feature]: /speckit.revise - update the current spec without rewriting artifacts #4156
Description
Activity
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.revisefor 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.mdis 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.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
- 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.mdbe 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.mda per-feature artifact (lives inspecs/<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
@mnriemby 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 · ◷
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.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)- No existing
revise.mdtemplate found intemplates/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
specifyorconvergetemplates 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.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) - No SUPERSEDED/RETIRED markers exist anywhere in current command templates; implementing the "ignore dead lines" requirement in
implement,analyze,taskstoissues, andconvergetouches 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
convergealso respect SUPERSEDED/RETIRED markers?] - [NEEDS CLARIFICATION: How does
revisions.mdintegrate 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
@mnriemby 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 · ◷
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.mdand regeneratingtasks.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.specifyhas run — they lose history and miss cleanup work today. - Users: Teams that have already run
/speckit.implementand 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}orRETIRED, 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, andtaskstoissues.
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.mdis a lightweight dated ID log, not a full changelog.
Success Metrics
- After running
/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)- 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.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
- [NEEDS CLARIFICATION: Should
convergealso respect SUPERSEDED/RETIRED markers, or is that too much cross-command coupling for v1?] - [NEEDS CLARIFICATION: How should
revisions.mdbe reflected in check-prerequisites scripts?] - [NEEDS CLARIFICATION: Are
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)Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for issue #4156 · 627.1 AIC · ⌖ 18.4 AIC · ⊞ 38.1K · ◷
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.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. - 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.mdformat precisely enough that the idempotency guarantee holds across agent runs.
Option B — Revise command only, no cross-cutting guards
- Sketch: Add
revise.mdonly. Leaveimplement,analyze,taskstoissuesunchanged. 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.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)
- 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.mdis an ID log only) convergeguard (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.mdandanalyze.md. - The
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)Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for issue #4156 · 627.1 AIC · ⌖ 18.4 AIC · ⊞ 38.1K · ◷
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
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
- [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
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)Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for issue #4156 · 627.1 AIC · ⌖ 18.4 AIC · ⊞ 38.1K · ◷
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:
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:
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
Additional Context
No response