# 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