evanflow-improve-architecture

Original：🇺🇸 English

Translated

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.

2installs

Sourceevanklem/evanflow

Added on2026-04-28

NPX Install

npx skill4agent add evanklem/evanflow evanflow-improve-architecture

SKILL.md Content

View Translation Comparison →

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/
```