| name | architectural-decisions |
| description | Guide explicit, factual trade-off analysis for architectural choices. Use when choosing between libraries, patterns, technologies, databases, or API designs. Presents 2-4 options with comparison matrices and recommendations. Do NOT use for trivial choices, variable naming, or code formatting decisions. |
| metadata | {"author":"Geoff","version":"1.0.0"} |
Architectural Decisions
Never make architectural decisions unilaterally. Always present options with explicit, factual trade-off analysis.
Instructions
Step 1: Identify the Decision Point
State clearly what needs to be decided:
- Decision Required: Specific choice to be made
- Context: Why this decision matters now
- Impact: What will be affected
Step 2: Present Options (2-4 alternatives)
For each option, provide:
- Name: Clear, descriptive label
- Description: What this approach entails
- Pros: Factual advantages (measurable when possible)
- Cons: Factual disadvantages (measurable when possible)
- Implementation Effort: Low/Medium/High
- Maintenance Impact: Long-term considerations
Step 3: Build a Comparison Matrix
Compare options across key dimensions:
- Performance characteristics
- Development time
- Maintenance burden
- Scalability implications
- Testing complexity
- watchOS compatibility / offline-first alignment
Step 4: Make a Recommendation
If one option is clearly superior for the context:
- State factual reasoning based on project constraints
- Explain why alternatives are less suitable
- Always let the user make the final decision
Factual vs Subjective Analysis
Use factual statements: "SQLite supports WAL mode for concurrent reads", "@Observable requires watchOS 10+"
Avoid subjective statements: "SQLite is better", "SwiftUI is more modern"
Examples
Example 1: Quick Decision Template
## Architectural Decision: [Topic]
**Context**: [Why we need to decide this now]
**Impact**: [What parts of the system are affected]
### Option 1: [Name]
**Pros**: ...
**Cons**: ...
**Implementation**: [Low/Medium/High]
### Option 2: [Name]
**Pros**: ...
**Cons**: ...
**Implementation**: [Low/Medium/High]
### Comparison Matrix
| Criterion | Option 1 | Option 2 |
|-----------|----------|----------|
| Performance | ... | ... |
| Dev Time | ... | ... |
### Recommendation
**Recommended**: Option X
**Rationale**: [Factual reasoning]
**Question for User**: Which option should we proceed with?
Example 2: When NOT to Use This Skill
- Variable naming choices -> just follow project conventions
- Code formatting -> use SwiftFormat / Ruff
- Trivial choices with no trade-offs -> just pick one
- Decisions already made -> follow existing patterns
Troubleshooting
Error: Analysis paralysis with too many options
- Limit to 2-4 realistic options
- Eliminate obviously unsuitable options early
- Focus comparison on the 3-4 most important criteria for this project
