improve-architecture

1# Improve architecture
2 
3Features pile up, and an app that was easy to change gets hard to change.
4A **check-in** catches that early: survey, propose, let the user pick, then
5refactor in small steps that keep behavior the same. The target shape for
6apps that grow is in [architecture.md](architecture.md).
7 
8## When to run
9 
10Any one signal is enough:
11 
12- The end of a milestone (the `improve-loop` skill calls this skill there).
13- Before a big feature. Ask: "What change to the code would make this
14  feature easy?"
15- A Swift file over 600 lines (act at 1,000), a type over 400 lines, or
16  "unable to type-check this expression".
17- One feature touched more than 6 files or more than 2 targets.
18- The same area shows up in 3 fix-log entries, or the same kind of bug
19  happens twice.
20- State that changes more than 10 times a second sits on a model that many
21  views observe.
22- A dependency cannot be replaced in a test.
23 
24## Vocabulary
25 
26Use these words exactly, so proposals stay comparable:
27 
28- **Module**: anything with an interface and an implementation (a type, a
29  file group, a target).
30- **Interface**: everything a caller must know: signatures, ordering,
31  error modes, threading, performance.
32- **Depth**: how much a module does per unit of interface. Deep modules hide
33  a lot behind a small interface. Shallow modules are pass-throughs.
34- **Seam**: a place where you can swap behavior without editing callers.
35- **Adapter**: one implementation behind a seam. One adapter is a
36…