4.9 KiB
4.9 KiB
Solution Architecture Checklist
Use this checklist during workflow execution and review.
Pre-Workflow
- analysis-template.md exists from plan-project phase
- PRD exists with FRs, NFRs, epics, and stories (for Level 1+)
- UX specification exists (for UI projects at Level 2+)
- Project level determined (0-4)
During Workflow
Step 0: Scale Assessment
- Analysis template loaded
- Project level extracted
- Level 0 → Skip workflow OR Level 1-4 → Proceed
Step 1: PRD Analysis
- All FRs extracted
- All NFRs extracted
- All epics/stories identified
- Project type detected
- Constraints identified
Step 2: User Skill Level
- Skill level clarified (beginner/intermediate/expert)
- Technical preferences captured
Step 3: Stack Recommendation
- Reference architectures searched
- Top 3 presented to user
- Selection made (reference or custom)
Step 4: Component Boundaries
- Epics analyzed
- Component boundaries identified
- Architecture style determined (monolith/microservices/etc.)
- Repository strategy determined (monorepo/polyrepo)
Step 5: Project-Type Questions
- Project-type questions loaded
- Only unanswered questions asked (dynamic narrowing)
- All decisions recorded
Step 6: Architecture Generation
- Template sections determined dynamically
- User approved section list
- architecture.md generated with ALL sections
- Technology and Library Decision Table included with specific versions
- Proposed Source Tree included
- Design-level only (no extensive code)
- Output adapted to user skill level
Step 7: Cohesion Check
- Requirements coverage validated (FRs, NFRs, epics, stories)
- Technology table validated (no vagueness)
- Code vs design balance checked
- Epic Alignment Matrix generated (separate output)
- Story readiness assessed (X of Y ready)
- Vagueness detected and flagged
- Over-specification detected and flagged
- Cohesion check report generated
- Issues addressed or acknowledged
Step 7.5: Specialist Sections
- DevOps assessed (simple inline or complex placeholder)
- Security assessed (simple inline or complex placeholder)
- Testing assessed (simple inline or complex placeholder)
- Specialist sections added to END of architecture.md
Step 8: PRD Updates (Optional)
- Architectural discoveries identified
- PRD updated if needed (enabler epics, story clarifications)
Step 9: Tech-Spec Generation
- Tech-spec generated for each epic
- Saved as tech-spec-epic-{{N}}.md
- project-workflow-analysis.md updated
Step 10: Polyrepo Strategy (Optional)
- Polyrepo identified (if applicable)
- Documentation copying strategy determined
- Full docs copied to all repos
Step 11: Validation
- All required documents exist
- All checklists passed
- Completion summary generated
Quality Gates
Technology and Library Decision Table
- Table exists in architecture.md
- ALL technologies have specific versions (e.g., "pino 8.17.0")
- NO vague entries ("a logging library", "appropriate caching")
- NO multi-option entries without decision ("Pino or Winston")
- Grouped logically (core stack, libraries, devops)
Proposed Source Tree
- Section exists in architecture.md
- Complete directory structure shown
- For polyrepo: ALL repo structures included
- Matches technology stack conventions
Cohesion Check Results
- 100% FR coverage OR gaps documented
- 100% NFR coverage OR gaps documented
- 100% epic coverage OR gaps documented
- 100% story readiness OR gaps documented
- Epic Alignment Matrix generated (separate file)
- Readiness score ≥ 90% OR user accepted lower score
Design vs Code Balance
- No code blocks > 10 lines
- Focus on schemas, patterns, diagrams
- No complete implementations
Post-Workflow Outputs
Required Files
- /docs/architecture.md (or solution-architecture.md)
- /docs/cohesion-check-report.md
- /docs/epic-alignment-matrix.md
- /docs/tech-spec-epic-1.md
- /docs/tech-spec-epic-2.md
- /docs/tech-spec-epic-N.md (for all epics)
Optional Files (if specialist placeholders created)
- Handoff instructions for devops-architecture workflow
- Handoff instructions for security-architecture workflow
- Handoff instructions for test-architect workflow
Updated Files
- analysis-template.md (workflow status updated)
- prd.md (if architectural discoveries required updates)
Next Steps After Workflow
If specialist placeholders created:
- Run devops-architecture workflow (if placeholder)
- Run security-architecture workflow (if placeholder)
- Run test-architect workflow (if placeholder)
For implementation:
- Review all tech specs
- Set up development environment per architecture
- Begin epic implementation using tech specs