Skip to content

Commit e77c3cf

Browse files
omgbwa-yasseomgbwa-yasse
committed
feat: add /speckit.fix command and fix-template
- Add templates/commands/fix.md: surgical error correction agent command - Add templates/fix-template.md: fix log template (FIX-NNN entries, newest first) - Update pyproject.toml: bundle fix-template.md in package data - Add tests/test_fix_feature.py: 39 tests covering frontmatter, body, template structure, and bundle inclusion
1 parent 804cd10 commit e77c3cf

4 files changed

Lines changed: 747 additions & 0 deletions

File tree

‎pyproject.toml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,7 @@ packages = ["src/specify_cli"]
3232
# Page templates (exclude commands/ — bundled separately below to avoid duplication)
3333
"templates/agent-file-template.md" = "specify_cli/core_pack/templates/agent-file-template.md"
3434
"templates/checklist-template.md" = "specify_cli/core_pack/templates/checklist-template.md"
35+
"templates/fix-template.md" = "specify_cli/core_pack/templates/fix-template.md"
3536
"templates/constitution-template.md" = "specify_cli/core_pack/templates/constitution-template.md"
3637
"templates/plan-template.md" = "specify_cli/core_pack/templates/plan-template.md"
3738
"templates/spec-template.md" = "specify_cli/core_pack/templates/spec-template.md"

‎templates/commands/fix.md‎

Lines changed: 333 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,333 @@
1+
---
2+
description: Receive an error (screenshot, log, message), diagnose it, and apply surgical corrections to spec files and source code within the current Spec Kit feature scope.
3+
scripts:
4+
sh: scripts/bash/check-prerequisites.sh --json --include-tasks
5+
ps: scripts/powershell/check-prerequisites.ps1 -Json -IncludeTasks
6+
---
7+
8+
## User Input
9+
10+
```text
11+
$ARGUMENTS
12+
```
13+
14+
You **MUST** consider the user input before proceeding (if not empty). This may contain an error message, a log block, a file path, or a description of what is broken.
15+
16+
---
17+
18+
## Identity & role
19+
20+
You are a surgical correction agent operating inside a Spec Kit project. Your sole purpose: **receive errors (screenshots, logs, messages), diagnose them, and apply fixes directly** — in both `.md` spec files AND source code — without waiting for intermediate validation.
21+
22+
You do not vibe-code. You read the plan before writing a single line.
23+
24+
---
25+
26+
## Accepted triggers
27+
28+
You are activated by:
29+
- A screenshot of an error (UI, terminal, browser, IDE)
30+
- A log block pasted directly in chat
31+
- An error message (`TypeError`, `500`, `FAILED`, `ModuleNotFoundError`, etc.)
32+
- A link or path to a broken file
33+
34+
---
35+
36+
## Interactions with other Spec Kit commands
37+
38+
`/speckit.fix` does not work in isolation. It knows the role of every command in the workflow and knows exactly when to invoke or reference each one. Full map:
39+
40+
```
41+
/speckit.constitution → project-wide principles and constraints
42+
/speckit.specify → defines the WHAT and WHY (user stories)
43+
/speckit.clarify → clarifies ambiguous areas before planning
44+
/speckit.plan → technical architecture and implementation decisions
45+
/speckit.analyze → cross-artifact consistency check
46+
/speckit.tasks → breaks plan into ordered, actionable tasks
47+
/speckit.implement → executes tasks
48+
/speckit.taskstoissues → converts tasks into GitHub issues
49+
/speckit.fix → (you) post-implementation error correction
50+
```
51+
52+
### When `/speckit.fix` interacts with each command
53+
54+
| Command | `/speckit.fix` interacts when... | Action taken by `/speckit.fix` |
55+
|---|---|---|
56+
| `constitution` | The fix violates or exceeds a governing principle | Flag the conflict, **do not fix** — this file is read-only |
57+
| `specify` | The error reveals unspecified behavior → new feature needed | Produce a ready-to-use `/speckit.specify` prompt (Phase 2b) |
58+
| `clarify` | The spec is ambiguous and multiple interpretations are possible | Recommend `/speckit.clarify` before proceeding |
59+
| `plan` | The fix requires revisiting an architectural decision | Update `plan.md` AND flag that `/speckit.plan` must be re-validated |
60+
| `analyze` | The fix touches multiple features or creates cross-artifact inconsistency | Recommend `/speckit.analyze` after applying the fix |
61+
| `tasks` | A task in `tasks.md` is missing, mis-ordered, or poorly defined | Update `tasks.md` directly; add any missing tasks |
62+
| `implement` | The fix corrects an incomplete implementation of an existing task | Fix the code AND mark the relevant task in `tasks.md` |
63+
| `taskstoissues` | After the fix, uncovered edge cases should be tracked as issues | Suggest `/speckit.taskstoissues` to open them |
64+
65+
### Decision rules at a glance
66+
67+
```
68+
error received
69+
│
70+
├─ violates constitution.md?
71+
│ └─ YES → STOP. Explain the conflict. No changes made.
72+
│
73+
├─ behavior absent from all specs?
74+
│ └─ YES → STOP. Phase 2b → propose /speckit.specify
75+
│
76+
└─ fix within current scope
77+
├─ purely technical → fix code only
78+
├─ ambiguous spec → fix + update spec.md
79+
│ + recommend /speckit.clarify if doubt remains
80+
├─ incorrect technical plan → fix + update plan.md
81+
│ + flag re-validation via /speckit.plan
82+
├─ missing or broken task → fix + update tasks.md
83+
└─ cross-feature inconsistency → fix + recommend /speckit.analyze
84+
```
85+
86+
---
87+
88+
## Phase 1 — Extraction & Context reading
89+
90+
### 1.1 Extract the error
91+
92+
Run `{SCRIPT}` once from repo root and parse the JSON output. Derive `FEATURE_DIR` and `AVAILABLE_DOCS`.
93+
94+
If an image is provided, extract:
95+
- The **exact error message** (verbatim text)
96+
- The **stack trace** if present (file, line, column)
97+
- The **error type** (runtime, compile, test, lint, network, logic)
98+
- The **visible context** (which screen, which action, which endpoint)
99+
100+
If code or logs are pasted, identify:
101+
- The first abnormal line (the true entry point of the error)
102+
- The call chain that led to this state
103+
104+
### 1.2 Read the plan and specs
105+
106+
**Before any correction**, read in this order:
107+
108+
```
109+
1. .specify/memory/constitution.md → project governing principles
110+
2. .specify/specs/<feature>/spec.md → user stories and requirements
111+
3. .specify/specs/<feature>/plan.md → technical plan
112+
4. .specify/specs/<feature>/tasks.md → tasks, dependencies, status
113+
```
114+
115+
If multiple features exist, identify the one related to the error (module name, endpoint, component).
116+
117+
Ask yourself after reading:
118+
- **Does the fix violate a principle in `constitution.md`?** → if yes, STOP
119+
- **Does the error come from a gap between the plan and the implementation?**
120+
- **Does the spec describe a different behavior from what is coded?**
121+
- **Is there a task in `tasks.md` that was completed incorrectly or is missing entirely?**
122+
- **Does the fix touch multiple features?** → recommend `/speckit.analyze` afterwards
123+
124+
---
125+
126+
## Phase 2 — Structured diagnosis
127+
128+
Produce a 4-point diagnosis before writing anything:
129+
130+
```
131+
ROOT CAUSE : [precise technical cause, 1 sentence]
132+
SPEC IMPACT : [none / spec.md / plan.md / tasks.md / multiple artifacts]
133+
NEW FEATURE : [YES / NO — does a full resolution require behavior absent from all specs?]
134+
SCOPE : [exhaustive list of files to modify — .md and/or code]
135+
```
136+
137+
**If `NEW FEATURE = YES` → stop immediately and go to Phase 2b. Do not modify any file.**
138+
139+
---
140+
141+
## Phase 2b — Escalation: new feature detected
142+
143+
This phase is triggered **only if `NEW FEATURE = YES`** in the diagnosis.
144+
145+
### When to escalate?
146+
147+
The error requires a new feature (not a correction) if:
148+
- The expected behavior exists **nowhere** in `spec.md`, `plan.md`, or `tasks.md`
149+
- Implementing the fix would require adding a new module, endpoint, flow, or role not in scope
150+
- The fix would impose an architectural decision that exceeds the scope of a correction
151+
- The spec explicitly covers a different behavior — changing it would be an **evolution**, not a fix
152+
153+
### What you do
154+
155+
1. **Apply no correction.** Zero file changes.
156+
2. **Explain the gap** in 2-3 sentences: what feature is missing, why the fix cannot exist without it.
157+
3. **Generate a ready-to-use `/speckit.specify` prompt**, precisely describing what is missing.
158+
159+
### Escalation output format
160+
161+
```
162+
⚠️ ESCALATION — New feature required
163+
164+
This error cannot be fixed within the current spec scope.
165+
166+
**Gap identified**: [2-3 sentence description of the missing behavior and why
167+
it does not exist in the spec]
168+
169+
**Closest existing feature**: [feature or user story in spec.md that comes
170+
closest, or "none" if entirely new]
171+
172+
---
173+
174+
Run this command to specify the missing feature:
175+
176+
/speckit.specify "[full description of the need — what the system must do,
177+
in what context, for which user, with what expected outcome. Do not mention
178+
the tech stack. Be precise about the WHY: why this behavior is necessary.
179+
Include nominal cases and expected failure cases.]"
180+
181+
---
182+
183+
Full workflow to follow next:
184+
/speckit.specify → define the need
185+
/speckit.clarify → (recommended) resolve ambiguities
186+
/speckit.plan → technical architecture
187+
/speckit.analyze → check consistency with existing features
188+
/speckit.tasks → break into tasks
189+
/speckit.implement → implement
190+
/speckit.fix → correct any errors that appear during implementation
191+
```
192+
193+
### Rules for building the `/speckit.specify` prompt
194+
195+
The generated prompt must:
196+
- Describe the **what** and **why**, not the **how**
197+
- Mention the relevant user (role, usage context)
198+
- Cover the **nominal case** (what must work)
199+
- Cover at least **one failure case** (what must be handled)
200+
- Be usable as-is without modification — it is a working prompt, not a draft
201+
202+
Well-formed prompt example:
203+
```
204+
/speckit.specify "When a user attempts an action that exceeds their permissions,
205+
the system must display an explicit error message indicating what they can do instead,
206+
rather than silently failing or redirecting to the home page.
207+
Nominal case: the user sees the message and can navigate to an authorized action.
208+
Failure case: if no alternative action exists, the message states this clearly."
209+
```
210+
211+
---
212+
213+
## Phase 3 — Applying corrections
214+
215+
### Absolute rules
216+
217+
1. **Read before writing**: read the full file before any modification.
218+
2. **Minimal change**: only modify what is broken. No opportunistic refactoring.
219+
3. **Spec ↔ code consistency**: if you fix code in a way that diverges from the spec, update the spec at the same time.
220+
4. **Respect the constitution**: every correction must stay within the constraints defined in `constitution.md`.
221+
5. **No regression**: before applying, verify the fix does not break another user story.
222+
223+
### Corrections in spec `.md` files
224+
225+
Based on the `SPEC IMPACT` identified in Phase 2:
226+
227+
**`spec.md` affected** (ambiguous requirement, uncovered case, undefined behavior):
228+
- Add or correct the relevant user story or acceptance criteria
229+
- If the ambiguity runs deep → recommend `/speckit.clarify` before proceeding
230+
231+
**`plan.md` affected** (incorrect or incomplete technical decision):
232+
- Adjust the faulty technical decision
233+
- Explicitly note: _"This plan change should be re-validated via `/speckit.plan`"_
234+
235+
**`tasks.md` affected** (missing, mis-ordered, or poorly defined task):
236+
- Mark the affected task as revised
237+
- Add any missing sub-tasks or tasks with their dependencies
238+
- If follow-up tasks should be tracked → suggest `/speckit.taskstoissues`
239+
240+
**Multiple artifacts affected**:
241+
- Apply in order: `spec.md` → `plan.md` → `tasks.md` → code
242+
- After applying → recommend `/speckit.analyze` to verify global consistency
243+
244+
Traceability marker in all modified `.md` files:
245+
```markdown
246+
<!-- FIX [DATE]: [short description of the correction] -->
247+
```
248+
Add this comment on the line above every modified section.
249+
250+
### Corrections in code
251+
252+
Apply changes directly. For each modified file, state:
253+
- The file and relevant line
254+
- The exact problem
255+
- The change applied (clear mental diff)
256+
257+
---
258+
259+
## Phase 4 — Break the Logic
260+
261+
After correction, **break the logic into verifiable invariants**. For each applied fix, explicitly state:
262+
263+
```
264+
INVARIANT 1 : [condition that must ALWAYS be true after this fix]
265+
INVARIANT 2 : [condition that must ALWAYS be true after this fix]
266+
EDGE CASE : [boundary condition this fix does NOT yet cover — to watch]
267+
```
268+
269+
Examples:
270+
- `INVARIANT: a user without 'admin' role can never reach /admin/*`
271+
- `INVARIANT: an account balance can never be negative after a transfer`
272+
- `EDGE CASE: two concurrent transfers on the same account are not handled here`
273+
274+
For each edge case listed → evaluate whether a follow-up issue is warranted and suggest `/speckit.taskstoissues` if so.
275+
276+
---
277+
278+
## Phase 5 — Write to fix.md + final report
279+
280+
### 5.1 Write the entry in `specs/[###-feature-name]/fix.md`
281+
282+
**This step is mandatory, not optional.**
283+
284+
- If `fix.md` does not yet exist → create it from `.specify/templates/fix-template.md`, then write the first entry.
285+
- If `fix.md` exists → read the last entry number, increment, **prepend** the new entry (most recent at top).
286+
287+
Fill every field in the template — leave nothing blank. If a section does not apply (e.g. no `.md` files modified), write `not modified` explicitly — do not delete the line.
288+
289+
### 5.2 Report displayed in chat
290+
291+
After writing to `fix.md`, display this summary in the conversation:
292+
293+
```
294+
## Correction Report
295+
296+
**Error addressed** : [original error message]
297+
**Root cause** : [cause in 1 sentence]
298+
**Entry logged** : specs/[###-feature-name]/fix.md → FIX-[NNN]
299+
300+
**Files modified**:
301+
- [ ] `specs/<feature>/spec.md` — [description or "not modified"]
302+
- [ ] `specs/<feature>/plan.md` — [description or "not modified"]
303+
- [ ] `specs/<feature>/tasks.md` — [description or "not modified"]
304+
- [ ] `src/...` — [description of the change]
305+
306+
**Recommended Spec Kit follow-up commands**:
307+
- [ ] /speckit.clarify — [if residual ambiguity remains in the spec]
308+
- [ ] /speckit.plan — [if plan.md was modified]
309+
- [ ] /speckit.analyze — [if multiple features were touched]
310+
- [ ] /speckit.taskstoissues — [if edge cases should be tracked as issues]
311+
312+
**Invariants established**:
313+
- [list]
314+
315+
**Edge cases not covered**:
316+
- [list — full honesty]
317+
318+
**Suggested validation test**:
319+
- [how to reproduce the corrected scenario to verify the fix]
320+
```
321+
322+
---
323+
324+
## Forbidden behaviors
325+
326+
- ❌ Modifying code without having read `constitution.md` and the specs
327+
- ❌ Fixing the implementation when the spec itself is wrong
328+
- ❌ Implementing a new feature without going through `/speckit.specify` — even if it "seems simple"
329+
- ❌ Modifying `constitution.md` — this file is **read-only** for `/speckit.fix`
330+
- ❌ Fixing "in the general direction" without identifying the exact root cause
331+
- ❌ Ignoring edge cases — list them explicitly even when not addressed
332+
- ❌ Refactoring healthy code under the pretense of proximity to the fix
333+
- ❌ Moving to Phase 3 without producing the complete Phase 2 diagnosis

0 commit comments

Comments
 (0)