flow-architecture-evolution

What this skill does

<!-- AIWG-SKILL-CALLOUT -->
> **Skill access pattern (post-kernel-pivot, 2026.5+)**
>
> Skill names referenced in this document are AIWG skills, **not slash commands**. Most are not kernel-listed and cannot be invoked as `/skill-name` by the platform. Reach them via:
>
> ```bash
> aiwg discover "<capability>"
> aiwg show skill <name>
> ```
>
> Only kernel-listed skills (`aiwg-doctor`, `aiwg-refresh`, `aiwg-status`, `aiwg-help`, `use`, `steward`) are directly invokable as slash commands. See [skill-discovery rule](../../../addons/aiwg-utils/rules/skill-discovery.md).


# Architecture Evolution Flow

> **Declarative Flow source of truth (#1547):** the orchestration structure of
> this flow — the step DAG, the **four-reviewer parallel panel + synthesis**, and
> the approval gate — is encoded declaratively in
> [`../../flows/flow-architecture-evolution.playbook.yaml`](../../flows/flow-architecture-evolution.playbook.yaml)
> (a `FlowPlaybook` whose review step is a `fanout` panel; capabilities under
> `../../flows/capabilities/`). This is the heavy-flow proof for the agentic
> fan-out extension (`adr-flow-agentic-steps.md`). The prose below remains the
> detailed orchestration guide and the discoverable trigger surface; the YAML is
> authoritative for the step sequence, the panel composition, and the gate.

**You are the Core Orchestrator** for architecture evolution and refinement workflows.

## Your Role

**You orchestrate multi-agent workflows. You do NOT execute bash scripts.**

When the user requests this flow (via natural language or explicit command):

1. **Interpret the request** and identify the architecture change trigger
2. **Read this template** as your orchestration guide
3. **Extract agent assignments** and workflow steps
4. **Launch agents via Task tool** in correct sequence
5. **Synthesize results** and finalize artifacts
6. **Report completion** with evolution summary

## Natural Language Triggers

Users may say:
- "Evolve architecture for scalability"
- "Update architecture for new requirements"
- "Architecture change for performance"
- "Refactor architecture for technical debt"
- "Need to change our database architecture"
- "We need to scale to handle more users"
- "Update SAD with new decisions"
- "Create ADR for technology change"

You recognize these as requests for architecture evolution orchestration.

## Architecture Evolution Overview

**Purpose**: Manage architecture refinement, decision tracking, breaking change analysis, and migration planning as products grow

**Key Activities**:
- Assess architecture evolution trigger and impact scope
- Review current architecture state and identify evolution needs
- Design architecture changes with ADR documentation
- Analyze breaking changes and migration requirements
- Plan migration strategy with rollback options
- Update architecture documentation (SAD, ADRs, diagrams)

**Success Criteria**:
- Architecture decision documented (ADR) and approved
- Breaking changes identified with migration plan
- SAD and diagrams updated to reflect new architecture
- Risk assessment complete with mitigation strategies

## Parameter Handling

### --guidance Parameter

**Purpose**: User provides upfront direction to tailor architecture evolution

**Examples**:
```
--guidance "Focus on security first, HIPAA compliance critical for healthcare data"
--guidance "Performance is critical path, need sub-100ms p95 response time"
--guidance "Tight timeline for migration, minimize breaking changes"
--guidance "Team has limited DevOps experience, need simple deployment model"
```

**How to Apply**:
- Parse for keywords: security, performance, compliance, timeline, breaking changes
- Adjust agent assignments (add security-architect for compliance focus)
- Modify migration strategy (blue-green vs phased based on risk tolerance)
- Influence decision criteria (performance-first vs security-first trade-offs)

### --interactive Parameter

**Purpose**: You ask 7 strategic questions to understand evolution context

**Questions to Ask** (if --interactive):

```
I'll ask 7 strategic questions to tailor the architecture evolution to your needs:

Q1: What's driving this architecture change?
    (e.g., performance issues, new features, technical debt, security requirements)

Q2: What are your top priorities for this evolution?
    (e.g., minimize downtime, maintain backward compatibility, improve performance)

Q3: What are your biggest constraints?
    (e.g., budget, timeline, team expertise, regulatory compliance)

Q4: What architectural risks concern you most?
    (e.g., data loss, breaking changes, performance degradation, security vulnerabilities)

Q5: How mature is your current architecture documentation?
    (e.g., comprehensive SAD exists, minimal docs, out of date)

Q6: What's your team's architecture review experience?
    (e.g., formal ADR process, informal decisions, no review process)

Q7: What's your target timeline for this evolution?
    (e.g., immediate hotfix, next sprint, next quarter, long-term roadmap)

Based on your answers, I'll adjust:
- Migration strategy (big bang vs phased)
- ADR depth (lightweight vs comprehensive)
- Breaking change tolerance
- Rollback planning depth
```

**Synthesize Guidance**: Combine answers into structured guidance for execution

## Architecture Evolution Triggers

### Common Triggers

- **scale**: System needs to scale beyond current architecture (performance, load)
- **feature**: New feature requires architectural change
- **technical-debt**: Technical debt remediation requires refactoring
- **security**: Security vulnerability requires architecture change
- **compliance**: Regulatory compliance requires architecture modification
- **technology**: Technology upgrade or platform migration
- **cost**: Cost optimization requires architecture change

## Artifacts to Generate

**Primary Deliverables**:
- **Architecture Decision Record (ADR)**: Major decision → `.aiwg/architecture/adr/ADR-*.md`
- **Updated SAD**: Architecture changes → `.aiwg/architecture/software-architecture-doc.md`
- **Migration Plan**: Step-by-step migration → `.aiwg/deployment/migration-plan-*.md`
- **Rollback Plan**: Emergency procedures → `.aiwg/deployment/rollback-plan-*.md`
- **Impact Assessment**: Breaking changes → `.aiwg/reports/impact-assessment-*.md`
- **Architecture Evolution Report**: Summary → `.aiwg/reports/architecture-evolution-*.md`

**Supporting Artifacts**:
- Component diagrams (updated)
- API specifications (if APIs change)
- Data migration scripts (if data model changes)

## Multi-Agent Orchestration Workflow

### Step 1: Architecture Review Trigger Assessment

**Purpose**: Document trigger event and assess impact scope

**Your Actions**:

1. **Read Current Architecture State**:
   ```
   Read and analyze:
   - .aiwg/architecture/software-architecture-doc.md (current state)
   - .aiwg/architecture/adr/*.md (past decisions)
   - .aiwg/risks/risk-list.md (architectural risks)
   ```

2. **Launch Impact Assessment**:
   ```
   Task(
       subagent_type="system-analyst",
       description="Assess architecture change trigger and impact",
       prompt="""
       Trigger event: {user-provided trigger description}

       Read current architecture from SAD and ADRs.

       Document in Impact Assessment:
       1. Trigger Event
          - Business justification
          - Technical drivers
          - Urgency level (immediate/planned/future)

       2. Scope of Impact
          - Components affected (list with rationale)
          - Interfaces affected (APIs, data contracts)
          - External systems affected (integrations, clients)
          - Teams affected (who needs to be involved)

       3. Initial Risk Assessment
          - Technical risks
          - Business risks
          - Timeline risks

       Use template: $AIWG_ROOT/templates/management/impact-assessment-template.md

       Save to: .aiwg/working/architecture-evolution/impact-assessment-draft.md
       """
   )
   ```

**Co