architecture-exploration

What this skill does

# Architecture Exploration

Reason deeply about a system, generate real architectural options, and help the user choose the best direction before any migration begins.

This skill is intentionally **pre-commit**. Its job is to help pick the right architecture, not to execute the migration. Once a direction is chosen, hand the work off to `audit-and-migrate`.

## Why This Exists

Large engineering efforts fail long before code is written:

1. **Premature commitment** — a promising idea becomes the default architecture before alternatives are seriously examined.
2. **Local reasoning** — the agent optimizes one subsystem without understanding system-wide constraints, ownership, and failure modes.
3. **Strawman comparison** — one favored option is compared against weak alternatives, creating false confidence.
4. **Migration contamination** — the discussion quietly shifts from "what should we build?" to "how should we implement it?" before the target architecture is actually chosen.

This skill exists to force disciplined exploration before implementation.

## Hard Boundary

This skill does **not**:

- create migration slices
- create ratchet budgets for execution
- start refactoring
- write scaffolding or implementation code
- turn the leading option into the assumed winner before comparison is complete

This skill **does**:

- map the current system
- define the decision frame
- generate multiple serious options
- compare them against the same constraints
- stress-test them
- recommend a direction
- produce a handoff package for `audit-and-migrate`

Perform all of this work directly. Do not rely on other skills to do the shaping, stress-testing, or architecture comparison for you.

If the user has already chosen a direction and wants to land it safely, stop using this skill and use `audit-and-migrate`.

## Core Principle

**First excavate reality, then compare options, then recommend.**

Do not start with architecture taste. Start with the actual system, the actual constraints, and the actual problem.

## Evidence Discipline

Before you recommend an architecture, you must earn the recommendation.

For the relevant system, actively inspect:

- current code paths
- ownership boundaries
- state and data flow
- external contracts and integrations
- docs and operational surfaces
- obvious history signals when needed (recent churn, known incidents, partial prior refactors)

Do not recommend major boundary changes based only on the user's summary if the local codebase can answer the question.

When a claim is uncertain, mark it as uncertain. A high-integrity architectural recommendation is one that is well-calibrated, not one that sounds maximally confident.

## Workflow

### Phase 1: Define the Decision Frame

Before exploring options, pin down the decision you are actually making.

Capture:

- **Goal** — what outcome the user wants
- **Problem** — what pain or failure mode motivates the change
- **Invariants** — what must remain true
- **Non-goals** — what should stay out of scope
- **Constraints** — team, tooling, performance, compliance, time, compatibility, ops, or organizational limits
- **External surfaces** — APIs, env vars, queues, dashboards, CLI entrypoints, jobs, data contracts, webhooks, partner integrations
- **Decision horizon** — are we optimizing for the next 3 months, 1 year, or 3 years?

If the user already has a candidate solution in mind, treat it as **Option A**, not as the conclusion.

### Phase 2: Map the Current System

Understand the current system before proposing alternatives.

For the affected system or systems, map:

- **Primary workflows**
- **Current module boundaries**
- **Data flow**
- **Ownership of logic and state**
- **External dependencies**
- **Operational surfaces**
- **Known pain points**
- **Hotspots** — fragile areas, high-churn files, flaky tests, unclear ownership, duplicated logic, stale docs

Produce a concise current-state map:

```markdown
## Current System
| Area | Current Owner | Inputs | Outputs | Dependencies | Pain |
|------|---------------|--------|---------|--------------|------|
| ...  | ...           | ...    | ...     | ...          | ...  |
```

Do not skip this because the user "already knows the system." A rigorous option comparison depends on a shared map of reality.

### Phase 3: Generate the Option Set

Generate **2-4 serious architectural options**.

Do not generate fake alternatives. Every option must be plausible enough that a strong team could reasonably choose it.

When feasible, include:

- **Option 1: Evolutionary path** — improves the current system with lower disruption
- **Option 2: Simplifying path** — removes concepts and indirection aggressively
- **Option 3: Structural path** — introduces stronger boundaries or a new architecture shape
- **Option 4: Do less** — if the problem may be solvable with narrower change than expected

Each option must describe:

- architecture shape
- boundary changes
- ownership model
- data flow
- operational model
- what stays
- what changes
- what gets simpler
- what gets harder

### Phase 4: Analyze Each Option

For every option, run the same analysis.

#### A. Fit

How well does the option satisfy:

- the goal
- invariants
- constraints
- external surface obligations

#### B. Assumptions

List the must-be-true assumptions:

```markdown
## Must-Be-True Assumptions
| Assumption | Why It Matters | How to Verify | Fastest Disproof |
|------------|----------------|---------------|------------------|
| ...        | ...            | ...           | ...              |
```

#### C. Failure Modes

Imagine the option failed one year later. Work backward.

```markdown
## Pre-Mortem
| Failure Mode | Warning Signal | Prevention |
|--------------|----------------|------------|
| ...          | ...            | ...        |
```

#### D. Tradeoffs

Evaluate each option on:

- **Concept count** — how many new ideas someone must carry
- **Boundary clarity** — is ownership sharper or blurrier?
- **Migration difficulty** — how hard this will be to land later
- **Cleanup burden** — how likely it is to leave vestigial code, docs, configs, or adapters
- **Rollback story** — how hard it is to back out
- **Operability** — monitoring, debugging, failure handling, support burden
- **Testability** — can the system be verified deterministically?
- **Extensibility** — what future changes become easier?
- **Lock-in** — what new constraints does this create?

Use relative ratings with justification. Avoid fake precision.

```markdown
## Tradeoff Matrix
| Dimension | Option A | Option B | Option C |
|-----------|----------|----------|----------|
| Simplicity | Medium — ... | High — ... | Low — ... |
| Migration Difficulty | ... | ... | ... |
| Cleanup Burden | ... | ... | ... |
| Operability | ... | ... | ... |
| Testability | ... | ... | ... |
| Long-Term Flexibility | ... | ... | ... |
```

#### E. Disqualifiers

For each option, state what would make it the wrong choice.

Examples:

- requires compatibility the project does not need
- increases operational burden beyond the team's capacity
- creates too much cleanup debt during migration
- depends on an external contract the team does not control
- adds concepts without enough payoff

#### F. Unknowns

What remains uncertain? Distinguish:

- **architectural unknowns** — boundary or ownership uncertainty
- **runtime unknowns** — load, latency, concurrency, failure behavior
- **organizational unknowns** — team readiness, external consumers, ops constraints

### Phase 5: Recommend

Do not stop at listing options. Make a recommendation.

The recommendation must include:

- **Recommended option**
- **Why it wins**
- **Why the runner-up loses**
- **Why the other options were rejected**
- **What could change the recommendation**
- **What must be validated before committing**

If the recommendation is genuinely unclear, say so and explain exactly which uncertainty blocks a good decision.

### Phase 6: Define Validation Spikes

Before co