github / github/spec-kit

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

Đang mở
#4,156 6 bình luận 0 reaction 0 người được giao Xem trên GitHub
enhancement feature-assess feature-needs-clarification
Ngôn ngữ chính
Python
Star
137k
Fork
12.3k
Merge trung bình
2 ngày 12 giờ
Pull request đã merge (30 ngày)
159

Mô tả

### 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_

Hướng dẫn đóng góp

Mở hướng dẫn đóng góp

Hướng nghiên cứu

Start with the Specify CLI initialization and existing specify, plan, and tasks command installation, then inspect the handling of spec.md, plan.md, tasks.md, revisions.md, and Git hooks. Review the acceptance criteria and automated-test requirements before deciding how the new command fits with implement, analyze, and taskstoissues. Done means revise is installed, preserves existing artifacts, records requirement changes and task updates, and is covered by tests and documentation.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Đánh giá

Công nghệ
git, python
Lĩnh vực
cli, documentation, testing, tooling
Loại issue
Tính năng
Độ khó
5/5
Thời gian dự kiến
Hơn một tuần
Mức độ hoạt động
Sôi nổi
Độ rõ ràng
Khá rõ ràng
Mức phù hợp với người mới
38/100

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.