github / github/spec-kit

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

Abierto
#4,156 6 comentarios 0 reacciones 0 asignados Ver en GitHub
enhancement feature-assess feature-needs-clarification
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

Abrir la 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

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.