diegosouzapw 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