---
description: 'A robust, interactive approach to software development, ensuring requirements are clarified before implementation. It prioritizes safety and transparency through structured artifacts and clear protocols, with a proactive approach to edge case handling.'
applyTo: '**'
---

# Spec Driven Workflow v4

Structured, transparent software development process ensuring clarity before action, prioritizing safety and edge case handling.

## Core Principles

1. **Ambiguity Resolution**: Stop and clarify any unclear, inconsistent, or incomplete request before proceeding. No assumptions allowed.
2. **Persistent Execution**: Own task from start to finish, producing all artifacts and handling edge cases unless explicitly paused or transferred.
3. **Concise Communication**: Use minimal, clear language in responses and artifacts unless elaboration requested.

## Artifacts

Ensure transparency and auditability with minimal, clear documentation.

### Required Artifacts
- `requirements.md`: User stories, acceptance criteria, edge case matrix (EARS notation)
- `design.md`: Architecture, sequence diagrams, edge case mitigations
- `tasks.md`: Implementation plan with edge case tasks
- `decision_records.md`: Decision log with context, options, rationale
- `action_log.md`: Activity log with actions, outcomes, logs, test results
- `diagrams/`: Directory for visual documentation (e.g., sequence, data flow)

### File Structure
```
/spec/
├── requirements.md
├── design.md
├── tasks.md
├── decision_records.md
├── action_log.md
└── diagrams/
```

### Maintenance
- Update artifacts for new, updated, or obsolete tasks.
- Modify documentation only if instructed.
- Use concise language unless elaboration requested.

## Examples

### requirements.md
**Functional Requirements**
- req-001: WHEN user issues code generation command, AGENT SHALL validate and generate code. Priority: High, Status: Active
- req-002: IF command has unsupported syntax, AGENT SHALL return error with hints. Priority: High, Status: Active
- req-003: WHILE memory enabled, AGENT SHALL persist command context. Priority: Medium, Status: Active

**Edge Case Matrix**
| ID       | Description                          | Likelihood | Impact | Risk Score | Mitigation                              |
| -------- | ------------------------------------ | ---------- | ------ | ---------- | --------------------------------------- |
| edge-001 | Unsupported syntax/prompt            | Frequent   | High   | 85         | Parse/validate; return actionable error |
| edge-002 | Memory context mismatch              | Occasional | High   | 75         | Validate memory; prompt user if unclear |
| edge-003 | Ambiguous instruction interpretation | Occasional | Medium | 60         | Ask clarifying question                 |

### design.md
**Function**: `submitForm(formData)`  
**Inputs**: `formData: { key: string, value: any }`  
**Outputs**: `{ status: "success" | "error", message: string }`  

**Logic Flow**  
1. Validate formData format  
2. Save to IndexedDB or queue if offline  
3. Return success/error  

**Dependencies**  
- IndexedDB API  
- FormData model  

**Edge Cases**  
- edge-001: Empty fields (Risk: 70)  
  - Mitigation: Check empty fields; return error  
  - Test: Empty/partial submissions  
- edge-002: Offline submission (Risk: 80)  
  - Mitigation: Queue in IndexedDB; sync on reconnect  
  - Test: Simulate offline mode  

**Error Handling**  
- Return specific error messages  
- Log with timestamps  

### tasks.md
**task-001**: Implement submitForm  
- Depends: FormData model  
- Status: To Do  
- Outcome: Validates/saves form data or queues offline  
- Edge Cases: Empty fields, offline scenarios  
- Priority: High  

**task-002**: Add form validation UI feedback  
- Depends: FormHandler  
- Status: To Do  
- Outcome: Show error messages for invalid inputs  
- Edge Cases: Real-time validation for malformed inputs  
- Priority: Medium  

### decision_records.md
**Decision 001**  
- Date: 2025-07-21T15:00:00Z  
- Decision: Use IndexedDB for offline form storage  
- Context: Store form submissions offline  
- Options:  
  1. IndexedDB: Pros - Efficient; Cons - Browser compatibility  
  2. LocalStorage: Pros - Simple; Cons - Limited capacity  
- Rationale: IndexedDB supports larger datasets  
- Impact: Needs compatibility checks for older browsers  
- Review: 2026-01-21  
- Status: Approved  

### action_log.md
**Activity 001**  
- Action: Implemented submitForm  
- Date: 2025-07-21T14:00:00Z  
- Outcome: Validates/saves form data  
- Logs: [Console output]  
- Tests: [Unit tests]  
- Linting: ESLint, fixed 2 warnings (trailing commas, unused variables)  
- Type Checking: TypeScript, fixed 1 formData type mismatch  
- Issues: None  
- Edge Cases: Handled empty fields, offline queuing  
- Next Steps: Test malformed inputs, verify offline sync  

## Execution Workflow (6 Phases)

1. **ANALYZE**  
   - Read code, docs, tests, logs; summarize findings  
   - Define requirements in EARS notation  
   - Identify dependencies, constraints, data flows  
   - Catalog edge cases in matrix: [Description], [Likelihood], [Impact], [Risk Score], [Mitigation]  
   - Assess Confidence Score (0-100%)  
   - Halt if ambiguous; request clarification  

2. **DESIGN**  
   - High Confidence (>85%): Plan with edge case mitigations  
   - Medium Confidence (66–85%): Build PoC/MVP  
   - Low Confidence (<66%): Research, simulate edge cases  
   - Document in `design.md`: architecture, interfaces, mitigations  
   - Define unit tests for edge cases  
   - Plan tasks in `tasks.md`  

3. **IMPLEMENT**  
   - Code in small, testable increments  
   - Build from dependencies upward  
   - Follow conventions; log deviations in `decision_records.md`  
   - Add comments for intent  
   - Update `tasks.md` with status, edge case outcomes  

4. **VALIDATE**  
   - Run tests; log results including edge cases  
   - Perform linting; log in `action_log.md`  
   - Perform type checking; log in `action_log.md`  
   - Verify performance; log traces  
   - Resolve all issues before proceeding  

5. **REFLECT**  
   - Refactor for maintainability; document changes  
   - Update artifacts, including edge case docs  
   - Identify improvements, technical debt, missed edge cases  
   - Validate success criteria, edge case outcomes  

6. **HANDOFF**  
   - Generate Executive Summary: Task outcomes, decisions, edge case mitigations, validation results  
   - Prepare Pull Request: Summary, changelog, validation/artifact links  
   - Archive intermediate files to `.agent_work/`  
   - Document completion in `action_log.md`  

## Interruption/Resume
- Reassess system impact  
- Update artifacts (`design.md`, `tasks.md`, etc.)  
- Log event in `decision_records.md`  

## Troubleshooting
- Re-analyze requirements, edge cases  
- Update design, tasks for new mitigations  
- Retry with updated logic  
- Escalate persistent issues; log in `decision_records.md`  

## Technical Debt
- Log in `decision_records.md`: [Title], [Priority], [Location], [Reason], [Impact], [Remediation], [Effort]  
- Prioritize by risk and effort  

## Quality Assurance
**Monitoring**  
- Static Analysis: Check architecture, vulnerabilities  
- Dynamic Analysis: Monitor runtime, performance  
- Documentation: Verify completeness, accuracy  
- Edge Case Coverage: Track mitigations in matrix  
- Edge Case Risk Reduction: Measure post-mitigation