You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -15,24 +15,6 @@ You **MUST** consider the user input before proceeding (if not empty). This may
15
15
16
16
---
17
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
18
## Interactions with other Spec Kit commands
37
19
38
20
`/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:
|`functions/`, `triggers/`|`trigger → function → external service`|Serverless (Lambda, Azure Functions)|
64
56
65
-
### Decision rules at a glance
57
+
If the project does not match any pattern, derive the chain from the actual directory names present in the stack trace. Name each role yourself — do not force a known pattern.
66
58
67
-
```
68
-
error received
69
-
│
70
-
├─ violates constitution.md?
71
-
│ └─ YES → STOP. Explain the conflict. No changes made.
**Rule: fix the functional role where the error *originates*, not where it *surfaces*.**
77
+
A `NullPointerException` at the entry point often originates in the data-access layer returning `None`.
78
+
An HTTP 500 in a view often originates in the business-logic layer throwing an uncaught exception.
79
+
80
+
---
81
+
82
+
## Phase 0 — Pre-flight
83
+
84
+
Before any extraction or triage, run these four checks in order. Each one can short-circuit the full workflow.
85
+
86
+
### 0.1 — Confidence threshold
87
+
88
+
If the input is too incomplete to triage (truncated log, blurry screenshot, ambiguous description), **do not guess**. Ask exactly one targeted question:
89
+
90
+
> "To diagnose this precisely, I need: [the one missing piece — full stack trace / the file path / the action that triggered the error]. Can you provide it?"
91
+
92
+
Do not proceed until you have enough information to fill the TRIAGE block.
93
+
94
+
### 0.2 — Multi-error input
95
+
96
+
If the input contains more than one distinct error (multiple FAILED tests, multiple exceptions):
97
+
1. List all errors found.
98
+
2. Identify the **most blocking** one (the one that causes others downstream, or the first in the execution chain).
99
+
3. Fix that one first. State explicitly: _"Fixing [error A] first. [Error B] and [Error C] are noted and will be addressed next if still present."_
100
+
101
+
### 0.3 — Recurrent error check
102
+
103
+
If `specs/[feature]/fix.md` exists, scan it (titles only — do not read full entries) before diagnosing:
104
+
- If a previous `FIX-NNN` entry addresses the same error → read that entry's `ROOT CAUSE` and `Decisions` sections before building the TRIAGE.
105
+
- If a previous fix was applied and the error recurred → the root cause was misidentified. Flag this explicitly in Phase 2: `RECURRENT: YES — previous fix FIX-NNN did not resolve the root cause`.
106
+
107
+
### 0.4 — Trivial fast path
108
+
109
+
If the error is trivially identifiable (one of the below), skip Phases 1–2 entirely and go directly to Phase 3:
110
+
111
+
| Trivial error | Direct action |
112
+
|---|---|
113
+
|`SyntaxError` with file:line| Open the file, fix the syntax, done |
114
+
|`ModuleNotFoundError: No module named 'x'`| Add the import or install the dependency |
115
+
|`NameError: name 'x' is not defined`| Check for typo or missing import |
116
+
| Typo in a config key (e.g. `DATABSE_URL`) | Fix the key name, done |
117
+
|`IndentationError`| Fix indentation at the given line |
118
+
119
+
For trivial fixes: write the `fix.md` entry with `SCOPE: 1 file`, skip Phase 4 invariants (write `not applicable — trivial fix`).
85
120
86
121
---
87
122
88
123
## Phase 1 — Extraction & Context reading
89
124
90
125
### 1.1 Extract the error
91
126
92
-
Run `{SCRIPT}` once from repo root and parse the JSON output. Derive `FEATURE_DIR` and `AVAILABLE_DOCS`.
127
+
If `FEATURE_DIR` is not identifiable from the stack trace paths, run `{SCRIPT}` from repo root to derive it.
93
128
94
129
If an image is provided, extract:
95
130
- The **exact error message** (verbatim text)
@@ -101,20 +136,39 @@ If code or logs are pasted, identify:
101
136
- The first abnormal line (the true entry point of the error)
102
137
- The call chain that led to this state
103
138
104
-
### 1.2 Read the plan and specs
139
+
### 1.2 Triage — classify the error
105
140
106
-
**Before any correction**, read in this order:
141
+
**Before opening any file**, produce this block from the error message and stack trace alone (zero file I/O):
Stack entry : [file:line — the exact line that threw]
147
+
Role : [functional role in this project's chain — e.g. data-access | validation | business-logic | entry-point | guard | routing | ui | api-bridge | config | test]
148
+
Read set : [2–5 files to open — derived from the Data Path Quick Reference — and nothing else]
113
149
```
114
150
115
-
If multiple features exist, identify the one related to the error (module name, endpoint, component).
151
+
Use **Step 1** of the Data Path Quick Reference to identify the project's own chain, then **Step 2** to map the error signature to a functional role. Open only the files listed in `Read set`.
152
+
153
+
If multiple features exist, identify the one related to the error (module name, endpoint, component) before building the read set.
154
+
155
+
**Third-party guard**: if `Stack entry` points to a file inside `node_modules/`, `site-packages/`, `vendor/`, or any external dependency directory, the bug is in your call site, not in the library. Shift `Stack entry` to the last in-project frame in the stack trace, and derive `Read set` from that frame instead.
156
+
157
+
### 1.3 Selective spec read
116
158
117
-
Ask yourself after reading:
159
+
Read spec/plan/tasks **only if** one of these conditions holds after the triage — otherwise skip directly to Phase 2:
160
+
161
+
| Condition | What to read |
162
+
|---|---|
163
+
| The fix would change a public API or data contract |`plan.md` — the relevant section only |
164
+
| The expected behavior is unclear from the code alone |`spec.md` — the section relevant to the broken feature only |
165
+
| A task is confirmed missing or wrongly sequenced |`tasks.md` only |
166
+
| The fix may violate a project-wide constraint |`constitution.md` — if violated, **STOP**|
167
+
| None of the above |**Read nothing.** Fix directly from the Read Set. |
168
+
169
+
`constitution.md` is **never** read proactively — only as a guard when a fix might violate it.
170
+
171
+
After reading (if applicable):
118
172
-**Does the fix violate a principle in `constitution.md`?** → if yes, STOP
119
173
-**Does the error come from a gap between the plan and the implementation?**
120
174
-**Does the spec describe a different behavior from what is coded?**
@@ -125,15 +179,19 @@ Ask yourself after reading:
125
179
126
180
## Phase 2 — Structured diagnosis
127
181
128
-
Produce a 4-point diagnosis before writing anything:
182
+
Produce a layered diagnosis before writing anything:
129
183
130
184
```
131
-
ROOT CAUSE : [precise technical cause, 1 sentence]
LAYER : [functional role in this project — e.g. data-access | validation | business-logic | entry-point | guard | routing | ui | api-bridge | config | test]
186
+
ROOT CAUSE : [precise technical cause, 1 sentence, referencing file:line]
187
+
CHAIN IMPACT : [does this error propagate to upstream roles? YES / NO — which ones?]
188
+
SPEC IMPACT : [none | spec.md | plan.md | tasks.md | multiple — only if triage triggered a read]
133
189
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]
190
+
SCOPE : [2–5 files maximum — code files only unless spec read was triggered]
135
191
```
136
192
193
+
**If `SCOPE` lists more than 5 files → this is not a fix, it is a refactoring. Stop. Recommend `/speckit.plan` to revisit the architecture before proceeding.**
194
+
137
195
**If `NEW FEATURE = YES` → stop immediately and go to Phase 2b. Do not modify any file.**
138
196
139
197
---
@@ -210,6 +268,21 @@ Failure case: if no alternative action exists, the message states this clearly."
210
268
211
269
---
212
270
271
+
### When `/speckit.fix` interacts with each command
272
+
273
+
| Command |`/speckit.fix` interacts when... | Action taken by `/speckit.fix`|
274
+
|---|---|---|
275
+
|`constitution`| The fix violates or exceeds a governing principle | Flag the conflict, **do not fix** — this file is read-only |
276
+
|`specify`| The error reveals unspecified behavior → new feature needed | Produce a ready-to-use `/speckit.specify` prompt (Phase 2b) |
277
+
|`clarify`| The spec is ambiguous and multiple interpretations are possible | Recommend `/speckit.clarify` before proceeding |
278
+
|`plan`| The fix requires revisiting an architectural decision | Update `plan.md` AND flag that `/speckit.plan` must be re-validated |
279
+
|`analyze`| The fix touches multiple features or creates cross-artifact inconsistency | Recommend `/speckit.analyze` after applying the fix |
280
+
|`tasks`| A task in `tasks.md` is missing, mis-ordered, or poorly defined | Update `tasks.md` directly; add any missing tasks |
281
+
|`implement`| The fix corrects an incomplete implementation of an existing task | Fix the code AND mark the relevant task in `tasks.md`|
282
+
|`taskstoissues`| After the fix, uncovered edge cases should be tracked as issues | Suggest `/speckit.taskstoissues` to open them |
283
+
284
+
---
285
+
213
286
## Phase 3 — Applying corrections
214
287
215
288
### Absolute rules
@@ -273,6 +346,20 @@ Examples:
273
346
274
347
For each edge case listed → evaluate whether a follow-up issue is warranted and suggest `/speckit.taskstoissues` if so.
275
348
349
+
### Validation test (mandatory)
350
+
351
+
Before moving to Phase 5, state how to verify the fix is effective:
352
+
353
+
```
354
+
VALIDATION : [exact command, scenario, or navigation path that confirms the error is gone
355
+
— e.g. "run pytest tests/test_payment.py::test_transfer",
356
+
"POST /api/orders with missing field → expect 422 not 500",
357
+
"navigate to /checkout as anonymous user → expect redirect to /login"]
358
+
```
359
+
360
+
If no automated test covers this scenario → flag it:
361
+
`COVERAGE GAP: this fix has no automated test. Consider adding one via /speckit.tasks.`
362
+
276
363
---
277
364
278
365
## Phase 5 — Write to fix.md + final report
@@ -314,20 +401,6 @@ After writing to `fix.md`, display this summary in the conversation:
314
401
315
402
**Edge cases not covered**:
316
403
- [list — full honesty]
317
-
318
-
**Suggested validation test**:
319
-
- [how to reproduce the corrected scenario to verify the fix]
320
404
```
321
405
322
-
---
323
-
324
-
## Forbidden behaviors
325
406
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