lowy

name	lowy
description	Evaluate architecture and module boundaries for volatility-based decomposition using Juval Lowy's framework (from "Righting Software", building on Parnas 1972). Use when reviewing module splits, service boundaries, new abstractions, or any decomposition decision. Triggers on "where should this boundary be", "how to split this", "module boundaries", "volatility", or references to Lowy, Parnas, or "Righting Software". Complements /hickey (interleaved concerns) with a change-encapsulation lens.
context	fork
agent	Explore
model	sonnet

Lowy: Volatility-Based Decomposition Review

The core question: do boundaries encapsulate axes of change, or just group related functionality? Sources: Juval Lowy, Righting Software (2019); Parnas, "On the Criteria…" (1972).

Key idea. Functional decomposition groups code by what it does (UserService, PaymentController); volatility-based decomposition groups by what changes, encapsulating each axis behind a stable interface — Lowy's electricity receptacle: enormous supply-side volatility, one stable socket. Functional decomposition maximizes the blast radius of change.

Two volatility types in business logic: sequence volatility (workflow order changes independently — belongs in orchestrators/Managers) and activity volatility (how a step is performed changes independently — belongs in strategies/Engines). Conflating them makes either change ripple into the other.

Variable vs. volatile. Not everything that varies is volatile. "If you cannot clearly state what the volatility is, why it is volatile, and what risk it poses in likelihood and effect, look further." Decomposing around mere variability produces over-engineered boundaries.

Scope

The trigger is a starting point, not a frame. Default to whole-module scope; cross-file boundary questions and sibling modules are in scope when the question recurs there. Don't let the framing define the scope: if the volatility actually lives elsewhere (the data model, a sequence/activity split), the redirected finding is the headline.

The graduation sweep — ask the boundary question in both directions: did volatility leak into a module (containment)? And does the diff create app-local machinery hiding a hard volatility (transport, connection lifetime, reconnection, multiplicity racing user intent) that wants its own receptacle/package (graduation)? Name each candidate's volatility and wanted home — as recorded opportunities, never blockers; prove-then-extract governs when.

The Evaluation

For every boundary, split, or new abstraction:

1. Name the Volatility

Be specific — "the payment provider", not "requirements might change". No concrete axis → the boundary may be arbitrary.

Project-declared areas of volatility: read .agency/lowy.md if it exists (table: area · what changes · why volatile (likelihood × effect) · expected encapsulation). Its rows are surviving candidates, not findings and not above review: (a) re-apply Lowy's bar and challenge rows that fail it; (b) audit whether the boundaries under review actually encapsulate the surviving volatilities in one place.

Check for prior encapsulation. Search for the canonical receptacle the project already has for this axis (command palette for "pick a thing", generic dialog for modal interaction, orchestrator for sequence, strategy registry for activity, one tagged error type for failure modes). A parallel receptacle for an already-encapsulated axis is duplicated volatility encapsulation — a first-class finding, surfaced before any critique inside the new abstraction. "New domain, same kind" duplicates the receptacle, not the volatility. Budget: run this survey when the diff adds a new top-level module/boundary (git diff --diff-filter=A --name-only origin/HEAD...HEAD non-empty).

Speculative volatility is not volatility — a scenario counts only if it has happened, is on a roadmap, or is a near-certain consequence of the domain. Weak volatility may not deserve its own boundary — ask whether it justifies the cost or folds into an existing one.

2. Classify

Sequence or activity? Also flag domain decomposition — boundaries around domain entities (ProjectService, AccountsManager) are functional decomposition in a domain hat.

3. Functional vs. Volatility Boundary

Does the boundary exist because the code does something different, or because what's behind it changes independently? The naming test: orchestrators named for the encapsulated volatility (AccountManager — good; BillingManager — bad, the gerund signals functional grouping); engines named for the volatile activity (SearchEngine — good; AccountEngine — bad). Can't name it after an axis → it may not encapsulate one.

4. Change Blast Radius

Trace a plausible change through the modules; leaking across boundaries = functional decomposition. Volatility should decrease downward — the most depended-upon components must be the least volatile. Check symmetry: similar modules should show the same calling patterns; an asymmetry (present or absent) flags a missed axis.

5. Interface Stability

The receptacle doesn't change when you switch grid to solar — an interface that changes with the encapsulated volatility is leaking. Expose atomic business verbs (credit, debit, transfer), not implementation operations; an interface mixing OpenPort/ClosePort with ReadCode jams two axes behind one contract. Good interfaces are reusable (the tool-hand analogy); implementations never are.

6. Reuse Signal

Reuse increases downward through layers; a lower-layer component locked to a single consumer suggests functionality-tracking. But single in-tree consumer is not disqualifying when the interface is stable under the encapsulated axis — a receptacle with one wire plugged in is still a receptacle (precedent: @kolu/surface and the kolu#998 graduations, all extracted at one consumer). The disqualifying shape is "the interface mirrors the implementation", not "one importer today".

6.5 Package Coherence

When an extraction crosses a package boundary, the package must read as one concept, one socket. For each new published-shape package:

1. Read the exports list as a new consumer — one coherent thing, or a topic-bundle? (@kolu/surface exports defineSurface — coherent. @kolu/solid-xterm@0.1 exported createXtermWebgl + attachXtermStyleSync + createScrollLock — three internal aspects leaked; the fix, @0.2.0 commit 4af1c647, is one createSolidXterm(…) primitive hiding them as submodules.)
2. §5's atomic-verb rule at package altitude — createX_webgl / attachX_style / createX_scroll is three operations on three axes, not one abstraction.
3. The Surface test — one entry point per coherent concept, internal submodules hidden; even exports that individually pass §5 can collectively fail this.
4. The "consumer wires it together" smell — a consumer importing several exports and composing them by hand means the missing primitive is the composition.

Verdict when it fires: not "don't extract" — "extract one socket, not three wires."

7. The Almost-Expendable Test

Expensive to change → too big (coupled concerns). Trivially expendable → an unnecessary boundary. Almost expendable — contains one axis, replaceable with thought but not trivially — correct.

Fact-Check Your Own Evaluation

Invoke /fact-check on your own output. It catches findings talked away, functional boundaries rationalized without a named axis, untraced change scenarios, and domain decomposition in volatility clothing.

Phrase shapes that mean you stopped one step early:

• "could also be seen as encapsulating volatility" — name the axis or it's functional.
• "the interface would only need minor changes" — minor changes are still leaking; the receptacle changes not at all.
• "only used in one place, but that's fine" — investigate; and conversely "fails Lowy's reuse test" on import count alone is a symptom, not a diagnosis — cite the axis (§5), not the count.
• "follows the framework's conventions" — convention is not volatility analysis.
• "could theoretically change independently" — no concrete scenario, no axis.
• "out of scope" / "pre-existing" — process judgment; there is no defer, fix it in this PR.
• "encapsulates [domain entity]" — entities are not axes; what about the entity changes?
• "variable, so we should encapsulate it" — variable is not volatile.
• "a new kind of [picker/dialog/error] for a new domain" — run the prior-encapsulation check; a parallel receptacle is duplicated encapsulation.
• "each export passes §5 in isolation" — §6.5 fires per package; read the exports list as a consumer and ask "what library is this?"

Revise before presenting if fact-check finds issues.

Output Format

1. Boundaries examined

2. Volatility map — per boundary, the axis (sequence/activity) it encapsulates or fails to

3. Findings — functionality-tracking boundaries with blast-radius analysis; symmetry violations; layering inversions

4. Simplifications — concrete restructuring per finding

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

6. Actions — one entry per finding (every finding, including "pre-existing"/"orthogonal" ones — a finding absent here was dismissed), each starting with a bolded label (≤8 words) and exactly one disposition: Fix in this PR (the only forward action; scope expands to absorb it) or No-op (rare: diff already deletes it, or subsumed verbatim by another entry). There is no Defer.

   Example: **useViewport encapsulates ghost concern** — Fix in this PR: delete the hook, let FitAddon measure per-tile.

Relationship to /hickey

Complementary lenses: Hickey asks "are independent concerns interleaved?"; Lowy asks "do boundaries encapsulate axes of change?" Run both on architectural decisions. When they disagree (Lowy: merge the shared volatility; Hickey: a mode flag would complect), unify the volatile axis without complecting the strategies — a shared module encapsulating the volatile part while strategies stay private. If unification needs a mode flag or type-switch, that's complecting; find the layer where it's mechanical.