/evanflow-improve-architecture

name: evanflow-improve-architecture
description: Identify refactoring opportunities by surfacing architectural friction. Apply the deletion test, deep-modules vocabulary, and seams analysis. Each opportunity becomes its own evanflow-writing-plans cycle. Use when reviewing code for refactoring, when a file has grown too large, or when architecture concerns surface during feature work.

EvanFlow: Improve Architecture

Vocabulary

See `evanflow` meta-skill. Key terms: **module**, **interface**, **depth**, **seam**, **adapter**, **deletion test**.

When to Use

• "This file is too big" / "this is hard to follow"
• A feature plan reveals friction the existing structure can't accommodate cleanly
• Periodic architectural review (Phase D of EvanFlow rollout)
• After tests reveal a module has the wrong shape

**SKIP when:** the user is doing a small, well-scoped change. Don't try to refactor adjacent code.

The Flow

1. Read Context First

• `CONTEXT.md` (if it exists) — for canonical domain language
• `docs/adr/` — for prior architectural decisions you must respect
• The target file(s) and their direct callers

2. Identify Candidates

Walk the codebase noting friction:

• A concept that bounces across many modules to be understood
• An interface that rivals its implementation in complexity
• Files that have grown unwieldy (>400 lines is a smell, >800 is a klaxon)
• Conditional logic that branches by concept (suggests two adapters in a missing seam)

3. Apply the Deletion Test

For each candidate module: "If I deleted this, where would the complexity go?"

• **Vanishes** → the module is bloat; delete it
• **Concentrates across N callers** → the module earns its existence; preserve and possibly deepen it
• **Moves to one place** → the module is a thin pass-through; consider folding it

4. Embedded Grill — Candidate Selection

Before proposing changes, stress-test:

• "Which candidate has the highest leverage (improves most caller code)?"
• "Which candidate is safest to change (smallest blast radius)?"
• "Are there ADRs that constrain the design we're considering?"
• "Does the proposed deepening match domain language in `CONTEXT.md`, or are we inventing new terms?"
• "If we change this seam, will it require touching tests that currently bypass the interface? (If yes, the test design is also wrong.)"

5. Present Opportunities

For each, name:

• **File(s)** affected
• **Current shape** (what's wrong)
• **Proposed shape** (small interface, complex internals)
• **Benefits** (in domain language from `CONTEXT.md`)
• **Cost** (estimated PRs, blast radius)

Prioritize. Recommend ONE to tackle next.

6. Hand Off Per Opportunity

**Each opportunity becomes its own `evanflow-writing-plans` cycle.** Do not bundle multiple refactors into one plan — that's a horizontal-slice failure.

If the opportunity changes a public interface, route through `evanflow-design-interface` first.

Hard Rules

• **Read `CONTEXT.md` and `docs/adr/` before proposing changes.** Domain language and prior decisions must inform the design.
• **Deletion test first.** Don't add abstractions just because they feel cleaner.
• **One refactor per plan.** Bundling refactors hides their individual value and inflates risk.
• **Two adapters before a seam.** Don't introduce variation points hypothetically — wait until two real implementations exist.
• **Never auto-commit.** Refactor PRs are easy to slip past review when batched; keep them small and explicit.

Hand-offs

• Opportunity selected → `evanflow-design-interface` (if interface changes) or `evanflow-writing-plans` (otherwise)
• New domain term emerged during discussion → `evanflow-glossary` to update `CONTEXT.md`
• Decision behind the design merits an ADR → write under `docs/adr/`