majiayu000 Iteration loop: explore for friction, present deepening candidates, grill the chosen one, update domain artifacts inline. Vocabulary is load-bearing — see references/LANGUAGE.md.
Vocabulary [LOAD-BEARING]
Use these terms exactly. Do not substitute "component," "service," "API," or "boundary." Full definitions in references/LANGUAGE.md.
- Module — anything with an interface and an implementation (function, class, package, slice). Scale-agnostic.
- Interface — every fact a caller must know: types, invariants, ordering, error modes, config, performance shape. Not just signature.
- Depth — leverage at the interface. Deep = much behaviour behind a small interface. Shallow = interface as complex as implementation.
- Seam (Feathers) — where an interface lives; a place behaviour can be altered without editing in place. Use this, not "boundary."
- Adapter — a concrete thing satisfying an interface at a seam. Role, not substance.
- Leverage — capability callers gain per unit of interface learned.
- Locality — concentration of change, bug, and knowledge at one site for maintainers.
Principles
- Deletion test: imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep.
- Interface = test surface. Tests cross the same seam callers cross. Wanting to test past the interface = wrong shape.
- One adapter = hypothetical seam. Two adapters = real seam. No port without two real implementations (production + test).
Process
1. Explore [Dispatch-First]
First tool call MUST be Explore-agent dispatch — not direct reads. The agent's brief:
- Read
CONTEXT.md(orCONTEXT-MAP.md+ per-contextCONTEXT.md) and anydocs/adr/. If absent, proceed silently. - Walk the codebase organically; classify friction:
- Concept understanding requires bouncing across many small modules → shallow cluster.
- Interface complexity matches implementation complexity → shallow module.
- Pure functions extracted only for testability while real bugs hide in callers → no locality.
- Tightly coupled modules leaking across their seams.
- For each suspect, run the deletion test before reporting.
2. Present candidates
Numbered list. Each candidate: Files, Problem (concrete friction; cite deletion test), Solution (plain-English description; no interface yet), Benefits (locality, leverage, testability deltas).
ADR conflicts: surface only when friction warrants reopening; mark explicitly: "contradicts ADR-0007 — worth reopening because…".
Ask: "Which candidate to explore?" Do not propose interfaces yet.
3. Grilling loop
Once user picks, drop into adversarial interview — walk the design tree, resolve dependencies one decision at a time, recommend an answer per question. Side effects happen inline:
- New domain term emerging? Update
CONTEXT.mdimmediately (lazy create). - User rejects with a load-bearing reason that future explorers would need? Offer ADR.
- User wants alternative interfaces for the chosen candidate? Pivot to
references/INTERFACE-DESIGN.md— parallel sub-agent design twice (Ousterhout).
Deepening categories (testing strategy per dependency class)
Full treatment in references/DEEPENING.md. Summary:
| Class | Deepenable? | Test strategy |
|---|---|---|
| In-process (pure / in-memory) | Always | Merge modules; test through new interface directly. No adapter. |
| Local-substitutable (PGLite, in-memory FS) | Yes if stand-in exists | Stand-in runs in tests; seam stays internal. |
| Remote but owned (microservices) | Yes via Ports & Adapters | Port at seam; HTTP/gRPC adapter prod, in-memory adapter test. |
| True external (Stripe, Twilio) | Yes | Injected port; mock adapter for tests. |
Replace, don't layer: delete shallow-module tests once interface tests exist.
Language-neutral examples
Rust — shallow validate_address + format_address + geocode_address separately called by a Shipment aggregator. Deletion test: removing format_address concentrates string-handling at one call site → was a pass-through. Deepen into address::Resolver with resolve(raw) -> Result<Resolved, AddressError>; tests cross the new interface; in-memory Geocoder adapter for tests, HTTP adapter for production.
Python — module exposes parse_invoice, apply_tax, round_total as separate top-level functions; every caller chains all three. Deepen into billing.Invoice.finalize(raw) -> Invoice. Internal seams (tax tables, rounding rules) stay private; the test surface is Invoice.finalize.
Reference docs
references/LANGUAGE.md— full vocabulary, principles, rejected framings.references/DEEPENING.md— dependency taxonomy, seam discipline, replace-don't-layer testing.references/INTERFACE-DESIGN.md— parallel sub-agent "Design It Twice" workflow when the chosen candidate's interface needs alternatives.
Forbidden: proposing interfaces in step 2 (premature commitment), bundling unrelated refactors, re-litigating ADRs without a load-bearing reason.