architecture-evolution

What this skill does

# architecture-evolution

Manage architecture changes with impact analysis, ADR generation, and migration planning.

## Triggers


Alternate expressions and non-obvious activations (primary phrases are matched automatically from the skill description):

- "ADR" → Architecture Decision Record creation
- "C4 model" → architecture diagram update
- "architecture drift" → deviation from baseline

## Purpose

This skill manages controlled architecture evolution by:
- Analyzing impact of proposed changes
- Generating Architecture Decision Records (ADRs)
- Planning migration paths
- Tracking breaking changes
- Coordinating cross-team dependencies
- Maintaining architecture health

## Behavior

When triggered, this skill:

1. **Identifies change scope**:
   - Parse proposed change
   - Map affected components
   - Identify stakeholders
   - Classify change type

2. **Performs impact analysis**:
   - Direct dependencies
   - Transitive dependencies
   - Data migration needs
   - API compatibility
   - Performance implications

3. **Generates documentation**:
   - Create or update ADR
   - Update component diagrams
   - Document migration path
   - Update API contracts

4. **Plans migration**:
   - Phase-by-phase approach
   - Rollback strategy
   - Feature flags if needed
   - Communication plan

5. **Coordinates execution**:
   - Notify affected teams
   - Track migration progress
   - Validate each phase
   - Confirm completion

## Change Categories

### Component Addition

```yaml
component_addition:
  description: Adding new service, module, or component

  impact_areas:
    - infrastructure: New deployment resources
    - networking: New routes, load balancing
    - security: Access controls, secrets
    - monitoring: New dashboards, alerts
    - dependencies: Integration points

  artifacts:
    - adr: ADR for new component
    - diagram: Updated architecture diagram
    - contract: API specification
    - runbook: Operational documentation
```

### Component Deprecation

```yaml
component_deprecation:
  description: Phasing out existing component

  impact_areas:
    - dependents: Who uses this component?
    - migration: Where do they migrate to?
    - timeline: How long to deprecate?
    - data: What happens to stored data?
    - cleanup: Resource removal plan

  artifacts:
    - adr: Deprecation decision record
    - migration_guide: How to migrate
    - timeline: Phase-out schedule
    - communication: Stakeholder notifications
```

### Breaking Change

```yaml
breaking_change:
  description: Incompatible change to existing interface

  impact_areas:
    - api_consumers: Who calls this API?
    - contract: What changes in the contract?
    - versioning: How to version the change?
    - backward_compat: Can we support both?
    - rollout: How to phase the rollout?

  artifacts:
    - adr: Breaking change decision
    - migration_guide: Upgrade instructions
    - changelog: Version history update
    - deprecation_notice: Timeline for old version
```

### Technology Migration

```yaml
technology_migration:
  description: Replacing underlying technology

  impact_areas:
    - learning_curve: Team training needs
    - code_changes: Rewrite scope
    - data_migration: Data format changes
    - testing: New test requirements
    - operations: New ops procedures

  artifacts:
    - adr: Technology choice rationale
    - migration_plan: Step-by-step migration
    - runbooks: Updated operational docs
    - training: Team education materials
```

## Impact Analysis Template

```markdown
# Architecture Impact Analysis

**Change**: [Description of proposed change]
**Date**: 2025-12-08
**Author**: [Name]
**Status**: Under Review

## Change Summary

### What is Changing
[Detailed description of the change]

### Why This Change
[Business or technical driver]

### Scope
- **Type**: Component Addition / Deprecation / Breaking Change / Migration
- **Risk Level**: Low / Medium / High / Critical
- **Estimated Effort**: [Time estimate]

## Impact Assessment

### Direct Dependencies

| Component | Impact | Migration Required | Effort |
|-----------|--------|-------------------|--------|
| Service A | High | Yes | 2 weeks |
| Service B | Medium | Yes | 1 week |
| Library X | Low | No | N/A |

### Transitive Dependencies

```
Proposed Change
    ├── Service A (direct)
    │   ├── Service C (transitive)
    │   └── Service D (transitive)
    └── Service B (direct)
        └── Service E (transitive)
```

Total affected: 5 components

### Data Impact

| Data Store | Action | Data Volume | Downtime |
|------------|--------|-------------|----------|
| PostgreSQL | Schema migration | 10M rows | ~5 min |
| Redis | Key format change | 100K keys | None |
| S3 | Path restructure | 500GB | None |

### API Impact

| API | Change Type | Breaking | Version Strategy |
|-----|-------------|----------|------------------|
| /users | Response field added | No | Additive |
| /orders | Endpoint deprecated | Yes | v1 → v2 |
| /auth | Token format | Yes | Dual support 30d |

### Performance Impact

| Metric | Current | Expected | Risk |
|--------|---------|----------|------|
| Latency p99 | 150ms | 180ms | Medium |
| Throughput | 1000 rps | 1200 rps | Positive |
| Memory | 2GB | 2.5GB | Low |

### Security Impact

| Area | Change | Risk | Mitigation |
|------|--------|------|------------|
| Auth | New token type | Medium | Security review |
| Data | New PII field | High | Privacy assessment |
| Network | New endpoint | Low | Firewall rules |

## Risk Assessment

| Risk | Probability | Impact | Mitigation |
|------|-------------|--------|------------|
| Migration failure | Medium | High | Rollback plan |
| Performance regression | Low | Medium | Load testing |
| Data loss | Low | Critical | Backup + validation |
| Extended downtime | Low | High | Blue-green deploy |

## Migration Plan

### Phase 1: Preparation (Week 1)
- [ ] Create new infrastructure
- [ ] Deploy in shadow mode
- [ ] Set up monitoring
- [ ] Train ops team

### Phase 2: Gradual Rollout (Week 2-3)
- [ ] 10% traffic migration
- [ ] Monitor for issues
- [ ] 50% traffic migration
- [ ] Validate performance

### Phase 3: Full Migration (Week 4)
- [ ] 100% traffic migration
- [ ] Deprecate old system
- [ ] Cleanup resources

### Rollback Plan

| Phase | Rollback Time | Data Impact | Procedure |
|-------|---------------|-------------|-----------|
| Phase 1 | 5 minutes | None | Disable shadow |
| Phase 2 | 15 minutes | Sync required | Route traffic back |
| Phase 3 | 30 minutes | Manual merge | Full rollback |

## Stakeholders

| Role | Name | Notification | Approval |
|------|------|--------------|----------|
| Architecture | Sarah Chen | Required | Required |
| Security | Elena Rodriguez | Required | Required |
| Ops/SRE | David Kim | Required | Informed |
| Product | James Wilson | Informed | Informed |
| Affected Teams | [List] | Required | Informed |

## Decision

**Recommendation**: Proceed with Phase 1
**Conditions**:
- Security review complete
- Load test passes
- Stakeholder sign-off

## Related Documents

- ADR: .aiwg/architecture/adr-XXX.md
- Migration Guide: .aiwg/architecture/migrations/XXX.md
- Rollback Procedure: .aiwg/deployment/rollback-XXX.md
```

## ADR Generation

When evolution is approved, generate ADR:

```markdown
# ADR-XXX: [Title]

## Status

Proposed → Accepted → Superseded by ADR-YYY (if applicable)

## Context

[What is the issue that we're seeing that is motivating this decision or change?]

## Decision

[What is the change that we're proposing and/or doing?]

## Consequences

### Positive
- [Benefit 1]
- [Benefit 2]

### Negative
- [Trade-off 1]
- [Trade-off 2]

### Risks
- [Risk 1 with mitigation]
- [Risk 2 with mitigation]

## Alternatives Considered

### Option A: [Name]
[Description and why rejected]

### Option B: [Name]
[Description and why rejected]

## Implementation

### Migration Path
[High-level migration steps]

### Timeline
- Phase 1: [Date] - [Description]
- Phase 2: [Date] - [Description]
-