308 lines
13 KiB
Markdown
308 lines
13 KiB
Markdown
---
|
||
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 v3
|
||
|
||
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.
|
||
|
||
## Core Principles
|
||
|
||
### 1. Ambiguity Resolution Protocol
|
||
|
||
The primary goal is to prevent errors by ensuring complete clarity *before* acting.
|
||
|
||
**Critical Constraint**: If any ambiguity, inconsistency, or incomplete information is encountered in the request or during the process, you MUST stop and ask for clarification. Do not make assumptions or proceed until resolved.
|
||
|
||
### 2. Persistent Execution Protocol
|
||
|
||
You MUST not return control to the user or stop or exit or pause the task or ask for permission you are stopped by critical ambiguity.
|
||
|
||
**Critical Constraint**: You MUST maintain continuous ownership of a task from initiation to completion, producing all required artifacts, mitigating edge cases, and finalizing handoff, unless explicitly instructed to pause or transfer ownership by the user.
|
||
|
||
### 3. Concise Communication Protocol
|
||
|
||
To ensure efficiency and clarity, you SHALL provide responses and documentation that are concise and to the point, avoiding unnecessary detail or verbosity. Explanations or elaborations SHALL only be included if explicitly requested by the user or required to resolve ambiguity.
|
||
|
||
**Critical Constraint**: Responses and artifacts must prioritize brevity while maintaining completeness and clarity, ensuring all required information is conveyed without extraneous content.
|
||
|
||
## Artifacts for Transparency
|
||
|
||
These artifacts ensure transparency and auditability for LLM-driven development.
|
||
|
||
**Critical Constraint**: Use clear, minimal, concise language unless elaboration is explicitly requested.
|
||
|
||
### Required Artifacts
|
||
|
||
| Artifact | Purpose | Content |
|
||
| --------------------- | ---------------------------------------------------------------------------- | -------------------- |
|
||
| `requirements.md` | User stories, acceptance criteria, and edge case matrix | EARS notation |
|
||
| `design.md` | Technical architecture, sequence diagrams, and edge case mitigations | Architecture docs |
|
||
| `tasks.md` | Detailed implementation plan with edge case handling tasks | Implementation tasks |
|
||
| `decision_records.md` | Log of decisions with context, options, and rationale | Decision history |
|
||
| `action_log.md` | Activity log with actions, outcomes, logs, test results, and console outputs | Execution records |
|
||
| `diagrams/` | Directory for diagrams (e.g., sequence, data flow) if needed | Visual documentation |
|
||
|
||
### File Structure
|
||
|
||
```markdown
|
||
/spec/
|
||
├── requirements.md
|
||
├── design.md
|
||
├── tasks.md
|
||
├── decision_records.md
|
||
├── action_log.md
|
||
└── diagrams/
|
||
```
|
||
|
||
### Maintenance Rules
|
||
|
||
1. Update all relevant artifacts for any **new**, **updated**, or **obsolete** task.
|
||
2. Do not create or modify other documentation unless explicitly instructed.
|
||
3. Use clear, minimal, concise language for all artifacts and documentation unless elaboration is explicitly requested.
|
||
|
||
### Purpose
|
||
|
||
Artifacts ensure changes are transparent, traceable, and reviewable.
|
||
|
||
## Concrete "Few-Shot" Examples
|
||
|
||
These simplified examples guide artifacts maintenance.
|
||
|
||
### requirements.md
|
||
|
||
#### Functional Requirements
|
||
- **req-001**: WHEN user issues code generation command, AGENT SHALL validate command and generate code. Priority: High, Status: Active
|
||
- **req-002**: IF command has unsupported syntax, AGENT SHALL return error with resolution hints. Priority: High, Status: Active
|
||
- **req-003**: WHILE memory enabled, AGENT SHALL persist command context across interactions. 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 before execution |
|
||
|
||
### design.md
|
||
|
||
#### Function Specification
|
||
- **Function**: `submitForm(formData)`
|
||
- **Inputs**: `formData: { key: string, value: any }`
|
||
- **Outputs**: `{ status: "success" | "error", message: string }`
|
||
|
||
#### Logic Flow
|
||
1. Validate formData for required fields/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
|
||
|
||
> Note: This is an illustrative fast path assuming Confidence Score >85%
|
||
|
||
#### Implementation Tasks
|
||
- **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-Phase Loop)
|
||
|
||
**Critical Constraint**: Never skip steps. Use consistent terminology. Minimize ambiguity.
|
||
|
||
### Phase 1: ANALYZE
|
||
|
||
**Objective**: Understand the problem, produce testable requirements, and identify edge cases.
|
||
|
||
#### Checklist
|
||
- [ ] Read provided code, documentation, tests, and logs; summarize findings
|
||
- [ ] Define requirements in **EARS Notation** (e.g., `WHEN [condition], THE SYSTEM SHALL [behavior]`)
|
||
- [ ] Identify dependencies, constraints, and data flows
|
||
- [ ] **Catalog edge cases** using input, state, user behavior, and environmental analysis
|
||
- [ ] **Edge Case Matrix** in `requirements.md`: `[Description], [Likelihood], [Impact], [Risk Score], [Mitigation]`
|
||
- [ ] Assess **Confidence Score (0-100%)** based on requirement clarity and edge case coverage
|
||
|
||
**Critical Constraint**: Halt and request clarification if requirements or edge cases are ambiguous.
|
||
|
||
### Phase 2: DESIGN
|
||
|
||
**Objective**: Create a technical design and plan addressing edge cases.
|
||
|
||
#### Strategy Selection
|
||
- **High Confidence (>85%)**: Comprehensive plan with edge case mitigations
|
||
- **Medium Confidence (66–85%)**: Build PoC/MVP to validate edge cases
|
||
- **Low Confidence (<66%)**: Research, simulate edge cases, and re-analyze
|
||
|
||
#### Checklist
|
||
- [ ] Document in `design.md`: architecture, data flow, interfaces, and edge case mitigations
|
||
- [ ] Define unit tests for edge cases
|
||
- [ ] Create implementation plan in `tasks.md` with edge case tasks
|
||
|
||
**Critical Constraint**: Do not implement until design and mitigations are complete.
|
||
|
||
### Phase 3: IMPLEMENT
|
||
|
||
**Objective**: Write production-quality code with edge case mitigations.
|
||
|
||
#### Checklist
|
||
- [ ] Code in small, testable increments; document changes and tests
|
||
- [ ] Implement from dependencies upward
|
||
- [ ] Follow conventions; document deviations in `decision_records.md`
|
||
- [ ] Add comments explaining intent
|
||
- [ ] Update `tasks.md` with status and edge case outcomes
|
||
|
||
**Critical Constraint**: Do not merge/deploy until implementation and edge case mitigations are tested.
|
||
|
||
### Phase 4: VALIDATE
|
||
|
||
**Objective**: Verify implementation meets requirements, quality standards, and edge case mitigations.
|
||
|
||
#### Checklist
|
||
- [ ] Run automated tests; document results including edge case tests
|
||
- [ ] Perform **linting** to enforce code style, quality, and security rules; document findings in `action_log.md`
|
||
- [ ] Perform **type checking** (e.g., TypeScript, mypy) to ensure type safety; log type errors in `action_log.md`
|
||
- [ ] Perform manual verification if needed; document results
|
||
- [ ] Verify performance and log execution traces
|
||
|
||
**Critical Constraint**: Resolve all issues, including edge case failures, linting errors, and type errors, before proceeding.
|
||
|
||
### Phase 5: REFLECT
|
||
|
||
**Objective**: Improve code, update documentation, and evaluate edge case handling.
|
||
|
||
#### Checklist
|
||
- [ ] Refactor for maintainability; document changes
|
||
- [ ] Update all artifacts, including edge case documentation
|
||
- [ ] Identify improvements and technical debt, including missed edge cases
|
||
- [ ] Validate success criteria and edge case outcomes
|
||
|
||
**Critical Constraint**: Complete all documentation and improvements before closing.
|
||
|
||
### Phase 6: HANDOFF
|
||
|
||
**Objective**: Package work for review/deployment and transition to the next task.
|
||
|
||
#### Checklist
|
||
- [ ] Generate **Executive Summary** (1-2 paragraphs):
|
||
- [ ] Summarize task outcomes, key decisions, and edge case mitigations
|
||
- [ ] Highlight validation results and any unresolved issues
|
||
- [ ] Prepare **Pull Request** (if applicable):
|
||
- [ ] Include summary, changelog, validation links, and artifact links
|
||
- [ ] Archive intermediate files to `.agent_work/`
|
||
- [ ] Document transition or completion in `action_log.md`
|
||
|
||
**Critical Constraint**: Task is not complete until all handoff steps are documented.
|
||
|
||
## Interruption / Resume Protocol
|
||
|
||
If scope changes, inputs shift mid-phase, or work resumes after interruption:
|
||
|
||
1. Reassess impact across the system
|
||
2. Update all relevant artifacts (`design.md`, `tasks.md`, etc.)
|
||
3. Log the event and rationale in `decision_records.md`
|
||
|
||
## Troubleshooting & Retry Protocol
|
||
|
||
### Error Handling Steps
|
||
1. Re-analyze requirements and edge cases
|
||
2. Update design and tasks for new mitigations
|
||
3. Retry execution with updated logic
|
||
4. Escalate persistent issues, documenting in `decision_records.md`
|
||
|
||
**Critical Constraint**: Never proceed with unresolved issues; document all steps.
|
||
|
||
## Technical Debt Management
|
||
|
||
### Identification
|
||
Log code quality issues, shortcuts, and missed edge cases in `decision_records.md`.
|
||
|
||
### Documentation Template
|
||
- **Title**: [Brief description]
|
||
- **Priority**: [High/Medium/Low]
|
||
- **Location**: [File/module reference]
|
||
- **Reason**: [Why this is technical debt]
|
||
- **Impact**: [Effect on system]
|
||
- **Remediation**: [Proposed solution]
|
||
- **Effort**: [Estimated time/complexity]
|
||
|
||
### Prioritization
|
||
Based on risk and effort for remediation.
|
||
|
||
## Quality Assurance
|
||
|
||
### Continuous Monitoring
|
||
|
||
#### Monitoring Areas
|
||
- **Static Analysis**: Monitor codebase for architectural rule adherence and potential vulnerabilities
|
||
- **Dynamic Analysis**: Monitor runtime behavior and performance in staging environment
|
||
- **Documentation**: Check for documentation completeness and accuracy (e.g., linking, format)
|
||
- **Edge Case Coverage**: Track percentage of edge cases in Edge Case Matrix with tests and mitigations
|
||
- **Edge Case Risk Reduction**: Measure reduction in Risk Scores post-mitigation via validation results
|
||
|
||
### Quality Metrics (Auto-Tracked)
|
||
|
||
| Metric | Description | Target |
|
||
| ------------------------ | --------------------------------------- | ---------- |
|
||
| Code Coverage | Percentage and gap analysis | >80% |
|
||
| Cyclomatic Complexity | Score per function/method | <10 |
|
||
| Maintainability Index | Overall assessment | >70 |
|
||
| Technical Debt Ratio | Remediation time vs. development time | <20% |
|
||
| Documentation Coverage | Public methods with comments | >90% |
|
||
| Edge Case Coverage | Edge cases with implemented mitigations | >95% |
|
||
| Linting Error Rate | Trend across project | Decreasing |
|
||
| Type Checking Error Rate | Trend across project | Decreasing |
|