spec-step-execution
Execute a single step from a spec with zero ambiguity. Report back with clear result.
Input
Before starting, you need:
- Spec file path
- Step number/name to execute
- Progress file path (if exists) - context on previous steps
- Research file path (if exists) - contains objective, defined terms, findings, decisions
Process
1. Read the Step
Read the spec and locate the exact step to execute. Note:
- Step description
- Expected outcome
- Verification items (if any)
2. Gap Test
A gap is any situation where the spec doesn't tell you what to do.
Check before and during execution:
- "Could two reasonable people interpret this differently?" → GAP
- "Something unexpected happened that spec doesn't cover" → GAP
- "Prerequisites not met or unavailable" → GAP
- "I need to make a judgment call" → GAP
| Situation | Action |
|---|---|
| Gap detected | Stop and return GAP result immediately |
| No gap | Proceed with execution |
Gap examples by domain:
| Domain | Gap (return GAP) | Not a gap (execute) |
|---|---|---|
| Code | "Improve error handling" | "Add try-catch around parseConfig() that logs error and returns null" |
| Code | API returns unexpected 403 error | API returns expected data |
| Testing | "Test the auth flow" | "Run npm test -- --grep 'auth' and verify all pass" |
| Research | "Analyze competitors" | "List pricing tiers for Competitor A, B, C in a table" |
| Research | Stats website is down or data missing | Stats available as expected |
| Content | "Write introduction" | "Write 2-sentence intro: what the tool does, who it's for" |
| Data | "Clean the dataset" | "Remove rows where 'email' column is empty or invalid format" |
| Data | File format differs from spec description | File matches expected format |
3. Execute
Do exactly what the step says. No more, no less.
- Follow the spec literally
- Use research file for context (terms, decisions)
- Don't add improvements not in the step
- Don't skip parts that seem unnecessary
4. Verify
If the step has verification items, complete each one:
- Verification item 1
- Verification item 2
- ...
If verification fails, the step is FAILED (not SUCCESS).
5. Return Result
Return exactly one of:
SUCCESS
Result: SUCCESS
Step: [step number/name]
Summary: [1-2 sentences of what was done]
Artifacts modified: [list if any]
Verification: [all items passed / N/A if none specified]
Observations: [optional - potential improvements, edge cases noticed, or other relevant notes]
FAILED
Result: FAILED
Step: [step number/name]
Summary: [what was attempted]
Error: [what went wrong]
Artifacts modified: [list if any, even partial]
Verification: [which items failed]
Observations: [optional - context that might help diagnose or fix]
GAP
Result: GAP
Step: [step number/name]
Gap: [what situation the spec doesn't cover]
Context: [what was happening when gap was hit]
Options: [possible interpretations or resolutions, if clear]
Recommendation: [suggested clarification to add to spec]
Available Tools
Use any available tools for implementation:
- Invoke skills (TDD, debugging, etc.) as needed
- Use MCP tools (Context7 for docs, etc.)
- Spawn focused sub-agents for specific sub-tasks (e.g., Explore agent)
- Run commands, tests, builds as needed
Rules
- Never proceed past a GAP - return immediately (gaps can occur before or during execution)
- Never mark SUCCESS if verification failed
- Never modify artifacts outside the step's scope
- Never make judgment calls - if unsure, it's a GAP
- Observations are optional - include if genuinely useful, skip if nothing notable