System Architecture Skill

Description: Analyze system architecture, evaluate trade-offs, and provide comprehensive planning for architectural changes. Usage: /system-arch [architecture question or proposed change]

Trigger this skill when:

• •Planning major system architecture changes
• •Evaluating new architectural patterns
• •Assessing impact of architectural decisions
• •Designing new system components
• •Refactoring existing architecture
• •User asks "should we use X pattern?", "how should we structure Y?"

Skip for: Code implementation (use code-architect), code review (use code-reviewer), testing (use integration-test-validator)

Phase 1: Context Gathering

Step 1.1: Understand Current State

Step 1.2: Understand Proposed Change

Phase 2: Impact Assessment

2.1: System Structure Impact

Component Analysis:

• • New components needed
• • Existing components modified
• • Components to deprecate
• • Dependency changes

Data Flow Changes:

• • New data paths
• • Modified interfaces
• • API changes
• • Database schema changes

2.2: Quality Attribute Analysis

2.3: Risk Assessment

Phase 3: Trade-off Analysis

Trade-off Matrix

## Trade-off Analysis: [Change Name]

### Option A: [Approach Name]
| Aspect | Positive | Negative |
|--------|----------|----------|
| Performance | [Benefits] | [Costs] |
| Complexity | [Benefits] | [Costs] |
| Maintainability | [Benefits] | [Costs] |
| Time to Implement | [Benefits] | [Costs] |

### Option B: [Approach Name]
[Same format]

### Comparison Summary
| Criterion | Option A | Option B | Winner |
|-----------|----------|----------|--------|
| Performance | [Score] | [Score] | [A/B] |
| Complexity | [Score] | [Score] | [A/B] |
| Time | [Score] | [Score] | [A/B] |
| Risk | [Score] | [Score] | [A/B] |

### Recommendation
[Which option and why]

Phase 4: Common Patterns Reference

Microservices

Event-Driven

CQRS

Serverless

Phase 5: Implementation Planning

Planning Template

## Architecture Change: [Name]

### Current State
- **Architecture:** [Description]
- **Components:** [List]
- **Data Flow:** [Description]

### Proposed Changes
- **New Components:** [List with purpose]
- **Modified Components:** [List with changes]
- **Removed Components:** [List with reason]
- **Interface Changes:** [API modifications]

### Implementation Phases

#### Phase 1: Foundation (Week 1-2)
- [ ] [Task 1]
- [ ] [Task 2]

#### Phase 2: Core Changes (Week 3-4)
- [ ] [Task 1]
- [ ] [Task 2]

#### Phase 3: Integration (Week 5-6)
- [ ] [Task 1]
- [ ] [Task 2]

#### Phase 4: Validation (Week 7-8)
- [ ] [Task 1]
- [ ] [Task 2]

### Rollback Strategy
- **Quick Rollback:** [Immediate steps]
- **Gradual Rollback:** [Phased approach]
- **Data Migration:** [Cleanup procedures]

### Success Metrics
| Metric | Current | Target | How to Measure |
|--------|---------|--------|----------------|
| [Metric 1] | [Value] | [Value] | [Method] |
| [Metric 2] | [Value] | [Value] | [Method] |

### Dependencies
- [External dependency 1]
- [Team dependency 1]

### Risks & Mitigations
| Risk | Likelihood | Impact | Mitigation |
|------|------------|--------|------------|
| [Risk 1] | [H/M/L] | [H/M/L] | [Approach] |

Phase 6: Decision Output

Architecture Decision Record (ADR)

## ADR: [Title]

### Status
[Proposed / Accepted / Deprecated / Superseded]

### Context
[What is the issue we're seeing that motivates this decision?]

### Decision
[What is the change we're proposing/doing?]

### Consequences
**Positive:**
- [Consequence 1]

**Negative:**
- [Consequence 1]

**Neutral:**
- [Consequence 1]

### Alternatives Considered
1. [Alternative 1] - Rejected because [reason]
2. [Alternative 2] - Rejected because [reason]

Phase 7: Transition to Implementation (MANDATORY)

After architecture is approved by user:

1. •

   IMMEDIATELY invoke the code-implementation skill

   code

   /code-implementation "Implement [architecture name] as specified in the approved architecture plan"
   

2. •

   Pass the following context to code-implementation:

   • •Architecture decision made
   • •Components to create/modify
   • •Interface definitions
   • •Implementation phases from the plan
   • •Success metrics and verification criteria
3. •

   Ensure code-implementation includes:

   • •Test cases for all new components
   • •Integration tests for modified interfaces
   • •Verification against architecture requirements

DO NOT:

• •Leave architecture as a plan-only document
• •Wait for user to explicitly ask for implementation
• •Skip transition to implementation phase

Example:

User: "Looks good, let's proceed with Option A"
Assistant: "Great! I'll now transition to implementation. Invoking /code-implementation..."

Quality Guidelines

ALWAYS:

• •Consider multiple options before recommending
• •Quantify trade-offs where possible
• •Think about operational impact
• •Consider security implications
• •Provide rollback strategy
• •Define success metrics

NEVER:

• •Recommend without trade-off analysis
• •Ignore non-functional requirements
• •Skip security considerations
• •Forget about operational complexity
• •Assume one-size-fits-all

Risk Thresholds

Escalation Triggers

Consult Oracle if:

• •Multiple viable options with unclear winner
• •Unfamiliar architectural patterns
• •Security or performance concerns
• •Cross-cutting concerns affect many systems

Ask User if:

• •Business constraints unclear
• •Resource availability unknown
• •Timeline requirements ambiguous
• •Stakeholder priorities needed