name: architecture-planning description: Create detailed architecture plans with decision records and risk assessments. Use when planning significant features or system changes.
Architecture Planning Skill
Purpose
Produce consistent, thorough architecture documentation for system design.
When to Use
- Planning significant feature implementations
- Making technology or pattern decisions
- Designing new modules or services
- Before major refactoring efforts
- System integration planning
Templates
Main Templates
- templates/architecture-doc.md - Full architecture document
- templates/decision-record.md - ADR (Architecture Decision Record) format
- templates/risk-assessment.md - Risk matrix template
Pattern Library
Reference established architectural patterns:
- patterns/microservices.md - Microservices architecture
- patterns/monolith.md - Monolithic architecture
- patterns/serverless.md - Serverless architecture
Decision Framework
When to Create an ADR
Create a formal Architecture Decision Record when:
- Choosing between technologies (database, framework, library)
- Selecting architectural patterns (monolith vs microservice)
- Defining integration approaches (sync vs async)
- Making security model changes
- Decisions that are hard to reverse
ADR Format (Lightweight)
# ADR-[N]: [Title]
**Status:** Proposed | Accepted | Deprecated | Superseded
**Date:** [YYYY-MM-DD]
## Context
[Why is this decision needed? What's the situation?]
## Decision
[What was decided?]
## Consequences
[What follows from this decision?]
Risk Assessment Matrix
Use this matrix to categorize risks:
| Probability ↓ / Impact → | Low | Medium | High |
|---|---|---|---|
| High | Medium | High | Critical |
| Medium | Low | Medium | High |
| Low | Low | Low | Medium |
Risk Categories
- Technical: Technology limitations, complexity, performance
- Timeline: Schedule impacts, dependencies
- Integration: External system dependencies, API changes
- Security: Vulnerabilities, compliance requirements
- Operational: Deployment, monitoring, maintenance
Architecture Document Sections
Required Sections
- Overview - High-level description
- Design Decisions - Key choices with rationale
- Component Design - Responsibilities and interfaces
- Risk Assessment - Identified risks and mitigations
Optional Sections (as needed)
- Data Flow diagrams
- Integration Points
- Security Considerations
- Performance Requirements
- Migration Strategy
Quality Checklist
Before finalizing an architecture document:
- All major decisions documented with options considered
- Rationale provided for each decision
- Trade-offs explicitly stated
- Risks identified with mitigation strategies
- Aligns with existing codebase patterns (from research)
- Integration points clearly defined
- Component responsibilities are clear and non-overlapping
- Security implications considered
- Performance requirements addressed
Output Location
Save architecture documents to: docs/plans/architecture-{session}.md
Save ADRs to: docs/plans/adr-{number}-{title}.md
Integration with Workflow
- Research phase provides codebase context and patterns
- Questioning phase provides validated requirements
- Architecture planning creates design documents (this skill)
- Task breakdown converts architecture to executable tasks
- Implementation follows the approved plan