Hickey: Structural Simplicity Evaluation

Tests tell you code works; they tell you nothing about whether it's simple. Complected code can be perfectly correct today — the damage shows up when you change, reason about, or extend it. Full talk: transcript (also transcript.md beside this skill).

Definitions. Simple (one fold): one concern, one role — objective; count the interleavings. Easy (nearby): familiar, at hand — relative. Complect: braid independent concerns so neither can be reasoned about alone. Compose: place independent things side by side, preserving isolation.

Scope

The trigger is a starting point, not a frame. Default to whole-module scope: read the whole file, every touched file of a diff, and adjacent siblings when the pattern recurs there. Don't let the user's framing define the scope — if the cited symptom is one instance of a broader structural issue, the broader finding is the headline, not a footnote. Anchoring on the trigger's framing is itself a finding the review never let form.

The Evaluation Process

Work the layers in order; every finding must later survive /fact-check.

Layer 1: Identify the Concerns

Name the independent concerns explicitly. Can't cleanly name them → that is a finding.

Layer 2: Fragmentation Check

"Don't complect" has a dual: don't fragment what belongs together. One domain concept split across fields, state locations, signals, or modules — held together by an unenforced rule — is the same structural bug from the opposite direction. The fix is reunification at whatever layer the one thing naturally lives (one type, one signal, one module, one file).

For every group of related fields or state locations: does the domain model this as one thing? If yes:

1. Enumerate the invariants coupling the parts, in plain language ("if A then B", "every update of P must update Q").
2. Check consumption sites — fragmentation shows at the reader: every consumer projecting the same value out of a per-entity structure is the fingerprint.
3. Watch for reconciliation machinery — a memo lifting one value from a collection, an effect copying state across entities, a "keep X in sync with Y" comment. The machinery is the bug, not the fix.
4. Collapse at the natural layer — wherever the unity stops needing a rule to hold.
5. Silence is the bug — when nothing is found, write "no invariants found" explicitly; the enumeration forces the check.

Layer 3: Concept Multiplication

For each new abstraction (component, module, signal, type) the code introduces:

1. Name what it represents at the domain level.
2. Survey the codebase for the canonical in-repo pattern for the same kind of operation — a new picker → every other "pick a thing" surface; a new dialog/scheduler/error type/config loader → the project's existing instance of that primitive kind. When the canonical pattern exists and the diff reinvents rather than extends it, that is the headline finding, before any critique inside the new abstraction.
3. "Mirror existing pattern" is an easiness judgment — creating B because A looks similar adds a concept; extending A keeps the count flat.
4. Package surface as a fragmentation site — read a new package's exports the way Layer 2 reads a per-entity structure: a consumer forced to wire several exports together to reconstitute one concept means the package fragmented one primitive into N exports. Collapse to one entry point; see /lowy §6.5 for the volatility-side argument and the worked example.

Budget: the survey fires when the diff adds new files (git diff --diff-filter=A --name-only origin/HEAD...HEAD non-empty) or a new exported abstraction; pure refactors and line-level fixes are exempt.

Concept Multiplication is duplicated wholes (two classes for one concept → delete one); Fragmentation is split wholes (one concept shattered → collapse). One finding can trigger both — that's redundancy, not muddling.

Layer 4: Structural Pattern Catalog

Scan for these plus any project-declared patterns — read .agency/hickey.md if it exists and treat its contents as catalog additions.

Complecting patterns

Construct	What it complects	Simpler alternative
Mutable state	Value + time + identity	Immutable values, controlled state containers
Objects	State + identity + value + namespace	Plain functions + data + namespaces
Methods	Function + state/namespace	Free functions, interfaces
Inheritance	Types with types	Composition, interfaces, traits
Switch/case on type	Who + what	Dynamic dispatch, visitor
Mutable variables	Value + time	const bindings, immutable data
Imperative loops	What + how + when	map/filter/reduce
Actors	What + who	Queues + stateless handlers
ORM	Identity + relational model + query	Plain data + declarative queries
Conditionals scattered across code	One decision braided across sites	Rules, policies, lookup tables
Callbacks over mutable state	Control flow + state + time	Streams, queues, immutable values
Hand-rolled utility (tokenizer, parser, date/semver/URL helper, arg parser) when a focused library fits	Scope decision with implementation choice	Use the library. "Zero deps" is an easiness judgment: code you don't own is simpler than code you do — it doesn't bitrot, and its edge cases are someone else's problem. Hand-roll only when the library adds surface you actively don't want.
New abstraction reimplementing an in-repo canonical pattern for the same kind of operation	Scope decision with placement choice	Reuse/extend the canonical pattern (Layer 3's survey detects this). A standalone abstraction is justified only when extending the canonical one would complect two genuinely independent volatility axes.

Fragmentation patterns

Construct	What it fragments	Simpler alternative
Parallel optionals with coupled presence	Existence + shape, admitting illegal states	Discriminated union
Per-entity state the domain says must agree	One value into N copies with an "all agree" rule	Single source of truth at the containing scope
Reactive pipeline projecting one value out of a per-entity structure	Sharedness reconstituted at read time	Make the state shared; delete the pipeline
Callback-down + value-up across modules	One state location into a cycle	Lift the state to the shared layer
Sum type as parallel optional fields	A discriminator scattered into projections	Actual sum type
Boolean combinations encoding a state machine	One state into independent flags	Enum/union naming each state
"Update X when Y changes" by convention	A rule into memory	Structure making the coupling mechanical
Duplicated derivations	One computation into N copies	Compute once, read N times
Config split across files by accident of history	A concept into cross-referenced shards	Collapse into the owning module
Shared helper living in whichever module imported it first	Its natural home into an authoring-order accident	Alternative-placement test: name the consumers, try the helper in each candidate home, and compare which placement leaves the more cohesive module. The default home owns the concept's generative side (layout, store, identity, lifecycle), not the first reader.

On a catalog match, don't dismiss — design the concrete alternative first (Layer 7), then judge. The proof burden is on the current code.

Layer 5: Structural Entanglement

Per touched module: concern count (>1 = braiding); mutable bindings per function (3+ = scrutinize); closures over mutable state; data-flow topology (cycles = complected); lifecycle nesting (new scopes inside a handler that has its own); temporal coupling beyond what types enforce.

Layer 6: Severity

Assess blast radius, change friction, and reasoning load per finding — but severity does not grant dismissal. Low-severity findings are still findings; the user decides, not you.

Layer 7: Suggest Simplifications

For every finding, propose a concrete structural alternative — pseudocode counts. Never label anything "essential complexity" without first designing the simplified version; only with it in hand can you judge, and then you must say exactly what makes the simple version non-viable. Design questions: cleaner boundary (what), subcomponents as arguments (who), isolated implementation (how), queues over direct calls (when/where), declarative policies over scattered conditionals (why).

Fact-Check Your Own Evaluation

After all layers, invoke /fact-check on your own output. It catches findings you talked yourself out of, "low severity" used as "ignore", bogus essential-complexity labels, and unverified behavior claims.

There is no Defer. "Out of scope", "pre-existing", "orthogonal", "follow-up refactor" are process judgments, not simplicity judgments — every such phrase in the evaluation must correspond to an Actions entry that fixes the finding in this PR. The PR's scope expands to absorb findings.

Phrase shapes that mean you stopped one step early — if these appear, re-open the question they dismiss:

• "X and Y share Z but are separate concerns" — verified at the domain level, or just at today's layout?
• "different consumers read different fields" — domain difference, or how today's UI happens to be organized?
• "technically could diverge, but in practice doesn't" — "in practice" is a promise that won't survive refactors.
• "each X could theoretically have its own Y" — the classic fragmentation cover story.
• "convention, not a constraint" / "we remember to update both" — discipline is not a type system.
• "X is the natural home for Y" / "Y's primary consumer is X" — circular if Y already lives in X; run the alternative-placement test.
• "the existing X is shaped for a different domain" — "different domain, same kind of operation" is concept multiplication; run the Layer 3 survey before accepting the framing.

Revise before presenting if fact-check finds issues.

Output Format

1. Concerns identified

2. Fragmentation findings (or an explicit "no invariants found")

3. Concept multiplication

4. Structural pattern matches — with line references

5. Severity per finding

6. Simplifications — concrete alternative for every finding

7. Fact-check result — including the phrase-shape check

8. Actions — one entry per finding from every layer (a finding that never reaches this section has been dismissed). Each starts with a bolded label (≤8 words), then exactly one disposition:

   • Fix in this PR — the only forward action; scope expands to absorb it.
   • No-op — rare: the diff already deletes the code, or the finding is subsumed verbatim by another entry (cite it).

   Example: **viewportDimensions complects current+default roles** — Fix in this PR: delete the signal, replace with per-tile FitAddon measurement.

   "No findings" → "No actions." Findings with an empty Actions list = incomplete evaluation.

No "What's simple" section — praise biases the framing; absence of findings is its own praise.

Caveats

• Simple ≠ easy, ≠ short, ≠ familiar.
• This complements correctness review, not replaces it.
• Do NOT run tests, builds, or shell commands — purely analytical.
• For volatility-based decomposition, see /lowy.