[Feature]: /speckit.revise - update the current spec without rewriting artifacts
- Lenguaje dominante
- Python
- Estrellas
- 137k
- Forks
- 12.3k
- Merge medio
- 2 d 12 h
- PR fusionados (30 d)
- 159
Descripción
### 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_
Guía de contribución
Línea de trabajo
Comienza con la inicialización de Specify CLI y la instalación existente de los comandos specify, plan y tasks; después, inspecciona el manejo de spec.md, plan.md, tasks.md, revisions.md y Git hooks. Revisa los criterios de aceptación y los requisitos de pruebas automatizadas antes de decidir cómo encaja el nuevo comando con implement, analyze y taskstoissues. Se considera terminado cuando revise está instalado, se conservan los artefactos existentes, se registran los cambios en los requisitos y las actualizaciones de las tareas, y todo está cubierto por pruebas y documentación.
Escrito por el modelo de indexación a partir del texto del issue.
Evaluación
- Stack tecnológico
- git, python
- Área
- cli, documentation, testing, tooling
- Tipo de issue
- Nueva funcionalidad
- Dificultad
- 5/5
- Tiempo estimado
- Más de una semana
- Estado de actividad
- Activo
- Claridad
- Bastante claro
- Aptitud para principiantes
- 38/100