evanflow-improve-architecture

Name: evanflow-improve-architecture
Author: evanklem

419stars18forks

How to install evanflow-improve-architecture?

evanklem/evanflow/evanflow-improve-architecture

$npx -y skills add evanklem/evanflow --skill evanflow-improve-architecture

Installs into the current project.

Summary

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, o

Files · 1

View on GitHub

SKILL.md

1	# EvanFlow: Improve Architecture
2
3
4	## Vocabulary
5
6	See `evanflow` meta-skill. Key terms: module, interface, depth, seam, adapter, deletion test.
7
8	## When to Use
9
10	- "This file is too big" / "this is hard to follow"
11	- A feature plan reveals friction the existing structure can't accommodate cleanly
12	- Periodic architectural review (Phase D of EvanFlow rollout)
13	- After tests reveal a module has the wrong shape
14
15	SKIP when: the user is doing a small, well-scoped change. Don't try to refactor adjacent code.
16
17	## The Flow
18
19	### 1. Read Context First
20
21	- `CONTEXT.md` (if it exists) — for canonical domain language
22	- `docs/adr/` — for prior architectural decisions you must respect
23	- The target file(s) and their direct callers
24
25	### 2. Identify Candidates
26
27	Walk the codebase noting friction:
28
29	- A concept that bounces across many modules to be understood
30	- An interface that rivals its implementation in complexity
31	- Files that have grown unwieldy (>400 lines is a smell, >800 is a klaxon)
32	- Conditional logic that branches by concept (suggests two adapters in a missing seam)
33
34	### 3. Apply the Deletion Test
35
36	For each candidate module: "If I deleted this, where would the complexity go?"
37
38	- Vanishes → the module is bloat; delete it
39	- Concentrates across N callers → the module earns its existence; preserve and possibly deepen it
40	- Moves to one place → the module is a thin pass-through; consider folding it
41
42	### 4. Embedded Grill — Candidate Selection
43
44	Before proposing changes, stress-test:
45
46	- "Which candidate has the highest leverage (improves most caller code)?"
47	- "Which candidate is safest to change (smallest blast radius)?"
48	- "Are there ADRs that constrain the design we're considering?"
49	- "Does the proposed deepening match domain language in `CONTEXT.md`, or are we inventing new terms?"
50	- "If we change this seam, will it require touching tests that currently bypass the interface? (If yes, the test design is also wrong.)"
51
52	### 5. Present Opportunities
53
54	For each, name:
55
56	- File(s) affected
57	- Current shape (what's wrong)
58	- Proposed shape (small interface, complex internals)
59	- Benefits (in domain language from `CONTEXT.md`)
60	- Cost (estimated PRs, blast radius)
61
62	Prioritize. Recommend ONE to tackle next.
63
64	### 6. Hand Off Per Opportunity
65
66	Each opportunity becomes its own `evanflow-writing-plans` cycle. Do not bundle multiple refactors into one plan — that's a horizontal-slice failure.
67
68	If the opportunity changes a public interface, route through `evanflow-design-interface` first.
69
70	## Hard Rules
71
72	- Read `CONTEXT.md` and `docs/adr/` before proposing changes. Domain language and prior decisions must inform the design.
73	- Deletion test first. Don't add abstractions just because they feel cleaner.
74	- One refactor per plan. Bundling refactors hides their individual value and inflates risk.
75	- Two adapters before a seam. Don't introduce variation points hypothetically — wait until two real implementations exist.
76	- Never auto-commit. Refactor PRs are easy to slip past review when batched; keep them small and explicit.
77
78	## Hand-offs
79
80	- Opportunity selected → `evanflow-design-interface` (if interface changes) or `evanflow-writing-plans` (otherwise)
81	- New domain term emerged during discussion → `evanflow-glossary` to update `CONTEXT.md`
82	- Decision behind the design merits an ADR → write under `docs/adr/`

People who liked this also viewed

6 picks

Type

evanflow-improve-architecture

419stars18forks

View on GitHub

How to install evanflow-improve-architecture?

evanklem/evanflow/evanflow-improve-architecture

$npx -y skills add evanklem/evanflow --skill evanflow-improve-architecture

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# EvanFlow: Improve Architecture
2
3
4	## Vocabulary
5
6	See `evanflow` meta-skill. Key terms: module, interface, depth, seam, adapter, deletion test.
7
8	## When to Use
9
10	- "This file is too big" / "this is hard to follow"
11	- A feature plan reveals friction the existing structure can't accommodate cleanly
12	- Periodic architectural review (Phase D of EvanFlow rollout)
13	- After tests reveal a module has the wrong shape
14
15	SKIP when: the user is doing a small, well-scoped change. Don't try to refactor adjacent code.
16
17	## The Flow
18
19	### 1. Read Context First
20
21	- `CONTEXT.md` (if it exists) — for canonical domain language
22	- `docs/adr/` — for prior architectural decisions you must respect
23	- The target file(s) and their direct callers
24
25	### 2. Identify Candidates
26
27	Walk the codebase noting friction:
28
29	- A concept that bounces across many modules to be understood
30	- An interface that rivals its implementation in complexity
31	- Files that have grown unwieldy (>400 lines is a smell, >800 is a klaxon)
32	- Conditional logic that branches by concept (suggests two adapters in a missing seam)
33
34	### 3. Apply the Deletion Test
35
36	For each candidate module: "If I deleted this, where would the complexity go?"
37
38	- Vanishes → the module is bloat; delete it
39	- Concentrates across N callers → the module earns its existence; preserve and possibly deepen it
40	- Moves to one place → the module is a thin pass-through; consider folding it
41
42	### 4. Embedded Grill — Candidate Selection
43
44	Before proposing changes, stress-test:
45
46	- "Which candidate has the highest leverage (improves most caller code)?"
47	- "Which candidate is safest to change (smallest blast radius)?"
48	- "Are there ADRs that constrain the design we're considering?"
49	- "Does the proposed deepening match domain language in `CONTEXT.md`, or are we inventing new terms?"
50	- "If we change this seam, will it require touching tests that currently bypass the interface? (If yes, the test design is also wrong.)"
51
52	### 5. Present Opportunities
53
54	For each, name:
55
56	- File(s) affected
57	- Current shape (what's wrong)
58	- Proposed shape (small interface, complex internals)
59	- Benefits (in domain language from `CONTEXT.md`)
60	- Cost (estimated PRs, blast radius)
61
62	Prioritize. Recommend ONE to tackle next.
63
64	### 6. Hand Off Per Opportunity
65
66	Each opportunity becomes its own `evanflow-writing-plans` cycle. Do not bundle multiple refactors into one plan — that's a horizontal-slice failure.
67
68	If the opportunity changes a public interface, route through `evanflow-design-interface` first.
69
70	## Hard Rules
71
72	- Read `CONTEXT.md` and `docs/adr/` before proposing changes. Domain language and prior decisions must inform the design.
73	- Deletion test first. Don't add abstractions just because they feel cleaner.
74	- One refactor per plan. Bundling refactors hides their individual value and inflates risk.
75	- Two adapters before a seam. Don't introduce variation points hypothetically — wait until two real implementations exist.
76	- Never auto-commit. Refactor PRs are easy to slip past review when batched; keep them small and explicit.
77
78	## Hand-offs
79
80	- Opportunity selected → `evanflow-design-interface` (if interface changes) or `evanflow-writing-plans` (otherwise)
81	- New domain term emerged during discussion → `evanflow-glossary` to update `CONTEXT.md`
82	- Decision behind the design merits an ADR → write under `docs/adr/`

People who liked this also viewed

6 picks

Type