From 280654484e39123afff295f6fd1e9397c709ef4f Mon Sep 17 00:00:00 2001 From: Muhammad Ubaid Raza Date: Fri, 18 Jul 2025 02:24:54 +0500 Subject: [PATCH] feat: :zap: added spec-driven-workflow-v1.instructions Bridge the gap between requirements and implementation. --- .../spec-driven-workflow-v1.instructions.md | 322 ++++++++++++++++++ 1 file changed, 322 insertions(+) create mode 100644 instructions/spec-driven-workflow-v1.instructions.md diff --git a/instructions/spec-driven-workflow-v1.instructions.md b/instructions/spec-driven-workflow-v1.instructions.md new file mode 100644 index 0000000..07158a8 --- /dev/null +++ b/instructions/spec-driven-workflow-v1.instructions.md @@ -0,0 +1,322 @@ +--- +applyTo: '**' +--- +# Spec-Driven Workflow + +**Specification-Driven Workflow:** +Bridge the gap between requirements and implementation. + +**Maintain these artifacts at all times:** + +- **`requirements.md`**: User stories and acceptance criteria in structured EARS notation. +- **`design.md`**: Technical architecture, sequence diagrams, implementation considerations. +- **`tasks.md`**: Detailed, trackable implementation plan. + +## Universal Documentation Framework + +**Documentation Rule:** +Use the detailed templates as the **primary source of truth** for all documentation. + +**Summary formats:** +Use only for concise artifacts such as changelogs and pull request descriptions. + +### Detailed Documentation Templates + +#### Action Documentation Template (All Steps/Executions/Tests) + +```bash +### [TYPE] - [ACTION] - [TIMESTAMP] +**Objective**: [Goal being accomplished] +**Context**: [Current state, requirements, and reference to prior steps] +**Decision**: [Approach chosen and rationale, referencing the Decision Record if applicable] +**Execution**: [Steps taken with parameters and commands used. For code, include file paths.] +**Output**: [Complete and unabridged results, logs, command outputs, and metrics] +**Validation**: [Success verification method and results. If failed, include a remediation plan.] +**Next**: [Automatic continuation plan to the next specific action] +``` + +#### Decision Record Template (All Decisions) + +```bash +### Decision - [TIMESTAMP] +**Decision**: [What was decided] +**Context**: [Situation requiring decision and data driving it] +**Options**: [Alternatives evaluated with brief pros and cons] +**Rationale**: [Why the selected option is superior, with trade-offs explicitly stated] +**Impact**: [Anticipated consequences for implementation, maintainability, and performance] +**Review**: [Conditions or schedule for reassessing this decision] +``` + +### Summary Formats (for Reporting) + +#### Streamlined Action Log + +For generating concise changelogs. Each log entry is derived from a full Action Document. + +`[TYPE][TIMESTAMP] Goal: [X] → Action: [Y] → Result: [Z] → Next: [W]` + +#### Compressed Decision Record + +For use in pull request summaries or executive summaries. + +`Decision: [X] | Rationale: [Y] | Impact: [Z] | Review: [Date]` + +## Execution Workflow (6-Phase Loop) + +**Never skip any step. Use consistent terminology. Reduce ambiguity.** + +### **Phase 1: ANALYZE** + +**Objective:** + +- Understand the problem. +- Analyze the existing system. +- Produce a clear, testable set of requirements. +- Think about the possible solutions and their implications. + +**Checklist:** + +- [ ] Read all provided code, documentation, tests, and logs. + - Document file inventory, summaries, and initial analysis results. +- [ ] Define requirements in **EARS Notation**: + - Transform feature requests into structured, testable requirements. + - Format: `WHEN [a condition or event], THE SYSTEM SHALL [expected behavior]` +- [ ] Identify dependencies and constraints. + - Document a dependency graph with risks and mitigation strategies. +- [ ] Map data flows and interactions. + - Document system interaction diagrams and data models. +- [ ] Catalog edge cases and failures. + - Document a comprehensive edge case matrix and potential failure points. +- [ ] Assess confidence. + - Generate a **Confidence Score (0-100%)** based on clarity of requirements, complexity, and problem scope. + - Document the score and its rationale. + +**Critical Constraint:** + +- **Do not proceed until all requirements are clear and documented.** + +### **Phase 2: DESIGN** + +**Objective:** + +- Create a comprehensive technical design and a detailed implementation plan. + +**Checklist:** + +- [ ] **Define adaptive execution strategy based on Confidence Score:** + - **High Confidence (>85%)** + - Draft a comprehensive, step-by-step implementation plan. + - Skip proof-of-concept steps. + - Proceed with full, automated implementation. + - Maintain standard comprehensive documentation. + - **Medium Confidence (66–85%)** + - Prioritize a **Proof-of-Concept (PoC)** or **Minimum Viable Product (MVP)**. + - Define clear success criteria for PoC/MVP. + - Build and validate PoC/MVP first, then expand plan incrementally. + - Document PoC/MVP goals, execution, and validation results. + - **Low Confidence (<66%)** + - Dedicate first phase to research and knowledge-building. + - Use semantic search and analyze similar implementations. + - Synthesize findings into a research document. + - Re-run ANALYZE phase after research. + - Escalate only if confidence remains low. + +- [ ] **Document technical design in `design.md`:** + - **Architecture:** High-level overview of components and interactions. + - **Data Flow:** Diagrams and descriptions. + - **Interfaces:** API contracts, schemas, public-facing function signatures. + - **Data Models:** Data structures and database schemas. + +- [ ] **Document error handling:** + - Create an error matrix with procedures and expected responses. + +- [ ] **Define unit testing strategy.** + +- [ ] **Create implementation plan in `tasks.md`:** + - For each task, include description, expected outcome, and dependencies. + +**Critical Constraint:** + +- **Do not proceed to implementation until design and plan are complete and validated.** + +### **Phase 3: IMPLEMENT** + +**Objective:** + +- Write production-quality code according to the design and plan. + +**Checklist:** + +- [ ] Code in small, testable increments. + - Document each increment with code changes, results, and test links. +- [ ] Implement from dependencies upward. + - Document resolution order, justification, and verification. +- [ ] Follow conventions. + - Document adherence and any deviations with a Decision Record. +- [ ] Add meaningful comments. + - Focus on intent ("why"), not mechanics ("what"). +- [ ] Create files as planned. + - Document file creation log. +- [ ] Update task status in real time. + +**Critical Constraint:** + +- **Do not merge or deploy code until all implementation steps are documented and tested.** + +### **Phase 4: VALIDATE** + +**Objective:** + +- Verify that implementation meets all requirements and quality standards. + +**Checklist:** + +- [ ] Execute automated tests. + - Document outputs, logs, and coverage reports. + - For failures, document root cause analysis and remediation. +- [ ] Perform manual verification if necessary. + - Document procedures, checklists, and results. +- [ ] Test edge cases and errors. + - Document results and evidence of correct error handling. +- [ ] Verify performance. + - Document metrics and profile critical sections. +- [ ] Log execution traces. + - Document path analysis and runtime behavior. + +**Critical Constraint:** + +- **Do not proceed until all validation steps are complete and all issues are resolved.** + +### **Phase 5: REFLECT** + +**Objective:** + +- Improve codebase, update documentation, and analyze performance. + +**Checklist:** + +- [ ] Refactor for maintainability. + - Document decisions, before/after comparisons, and impact. +- [ ] Update all project documentation. + - Ensure all READMEs, diagrams, and comments are current. +- [ ] Identify potential improvements. + - Document backlog with prioritization. +- [ ] Validate success criteria. + - Document final verification matrix. +- [ ] Perform meta-analysis. + - Reflect on efficiency, tool usage, and protocol adherence. +- [ ] Auto-create technical debt issues. + - Document inventory and remediation plans. + +**Critical Constraint:** + +- **Do not close the phase until all documentation and improvement actions are logged.** + +### **Phase 6: HANDOFF** + +**Objective:** + +- Package work for review and deployment, and transition to next task. + +**Checklist:** + +- [ ] Generate executive summary. + - Use **Compressed Decision Record** format. +- [ ] Prepare pull request (if applicable): + 1. Executive summary. + 2. Changelog from **Streamlined Action Log**. + 3. Links to validation artifacts and Decision Records. + 4. Links to final `requirements.md`, `design.md`, and `tasks.md`. +- [ ] Finalize workspace. + - Archive intermediate files, logs, and temporary artifacts to `.agent_work/`. +- [ ] Continue to next task. + - Document transition or completion. + +**Critical Constraint:** + +- **Do not consider the task complete until all handoff steps are finished and documented.** + +## Troubleshooting & Retry Protocol + +**If you encounter errors, ambiguities, or blockers:** + +**Checklist:** + +1. **Re-analyze**: + - Revisit the ANALYZE phase. + - Confirm all requirements and constraints are clear and complete. +2. **Re-design**: + - Revisit the DESIGN phase. + - Update technical design, plans, or dependencies as needed. +3. **Re-plan**: + - Adjust the implementation plan in `tasks.md` to address new findings. +4. **Retry execution**: + - Re-execute failed steps with corrected parameters or logic. +5. **Escalate**: + - If the issue persists after retries, follow the escalation protocol. + +**Critical Constraint:** + +- **Never proceed with unresolved errors or ambiguities. Always document troubleshooting steps and outcomes.** + +## Technical Debt Management (Automated) + +### Identification & Documentation + +- **Code Quality**: Continuously assess code quality during implementation using static analysis. +- **Shortcuts**: Explicitly record all speed-over-quality decisions with their consequences in a Decision Record. +- **Workspace**: Monitor for organizational drift and naming inconsistencies. +- **Documentation**: Track incomplete, outdated, or missing documentation. + +### Auto-Issue Creation Template + +```text +**Title**: [Technical Debt] - [Brief Description] +**Priority**: [High/Medium/Low based on business impact and remediation cost] +**Location**: [File paths and line numbers] +**Reason**: [Why the debt was incurred, linking to a Decision Record if available] +**Impact**: [Current and future consequences (e.g., slows development, increases bug risk)] +**Remediation**: [Specific, actionable resolution steps] +**Effort**: [Estimate for resolution (e.g., T-shirt size: S, M, L)] +``` + +### Remediation (Auto-Prioritized) + +- Risk-based prioritization with dependency analysis. +- Effort estimation to aid in future planning. +- Propose migration strategies for large refactoring efforts. + +## Quality Assurance (Automated) + +### Continuous Monitoring + +- **Static Analysis**: Linting for code style, quality, security vulnerabilities, and architectural rule adherence. +- **Dynamic Analysis**: Monitor runtime behavior and performance in a staging environment. +- **Documentation**: Automated checks for documentation completeness and accuracy (e.g., linking, format). + +### Quality Metrics (Auto-Tracked) + +- Code coverage percentage and gap analysis. +- Cyclomatic complexity score per function/method. +- Maintainability index assessment. +- Technical debt ratio (e.g., estimated remediation time vs. development time). +- Documentation coverage percentage (e.g., public methods with comments). + +## EARS Notation Reference + +**EARS (Easy Approach to Requirements Syntax)** - Standard format for requirements: + +- **Ubiquitous**: `THE SYSTEM SHALL [expected behavior]` +- **Event-driven**: `WHEN [trigger event] THE SYSTEM SHALL [expected behavior]` +- **State-driven**: `WHILE [in specific state] THE SYSTEM SHALL [expected behavior]` +- **Unwanted behavior**: `IF [unwanted condition] THEN THE SYSTEM SHALL [required response]` +- **Optional**: `WHERE [feature is included] THE SYSTEM SHALL [expected behavior]` +- **Complex**: Combinations of the above patterns for sophisticated requirements + +Each requirement must be: + +- **Testable**: Can be verified through automated or manual testing +- **Unambiguous**: Single interpretation possible +- **Necessary**: Contributes to the system's purpose +- **Feasible**: Can be implemented within constraints +- **Traceable**: Linked to user needs and design elements