67 lines
4.8 KiB
Markdown
67 lines
4.8 KiB
Markdown
# Interface Design
|
||
|
||
When the user wants to explore alternative interfaces for a chosen deepening candidate, use this parallel sub-agent pattern. Based on "Design It Twice" (Ousterhout) — your first idea is unlikely to be the best.
|
||
|
||
Uses the vocabulary in [LANGUAGE.md](LANGUAGE.md) — **module** (= **feature** by default in this repo), **interface**, **seam**, **adapter**, **leverage**.
|
||
|
||
## Process
|
||
|
||
### 1. Frame the problem space
|
||
|
||
Before spawning sub-agents, write a user-facing explanation of the problem space for the chosen candidate:
|
||
|
||
- The constraints any new interface would need to satisfy
|
||
- The dependencies it would rely on, and which category they fall into (see [DEEPENING.md](DEEPENING.md))
|
||
- The **hard constraints from SKILL.md** that the new interface must respect (factory-function shape, per-feature DI, manifest-first, generator-first, brand wrappers, etc.)
|
||
- A rough illustrative code sketch to ground the constraints — not a proposal, just a way to make the constraints concrete
|
||
|
||
Show this to the user, then immediately proceed to Step 2. The user reads and thinks while the sub-agents work in parallel.
|
||
|
||
### 2. Spawn sub-agents
|
||
|
||
Spawn 3+ sub-agents in parallel using the `Agent` tool (`subagent_type=general-purpose` or a more specific type if appropriate). Each must produce a **radically different** interface for the deepened module.
|
||
|
||
Prompt each sub-agent with a separate technical brief (file paths, coupling details, dependency category from [DEEPENING.md](DEEPENING.md), what sits behind the seam). The brief is independent of the user-facing problem-space explanation in Step 1. Give each agent a different design constraint:
|
||
|
||
- **Agent 1**: "Minimise the interface — aim for 1–3 entry points max. Maximise leverage per entry point."
|
||
- **Agent 2**: "Maximise flexibility — support many use cases and extension."
|
||
- **Agent 3**: "Optimise for the most common caller — make the default case trivial."
|
||
- **Agent 4 (if applicable)**: "Design around ports & adapters for cross-seam dependencies."
|
||
|
||
**Every brief MUST also include:**
|
||
|
||
- This repo's vocabulary from [`docs/glossary.md`](../../../docs/glossary.md) (use case, manifest, feature, slice, etc.)
|
||
- The architecture vocabulary from [LANGUAGE.md](LANGUAGE.md)
|
||
- The hard constraints from [SKILL.md](SKILL.md) — sub-agents must not propose interfaces that violate ADR-006 (boundaries), ADR-008 (per-feature DI), ADR-012 (factory shape, one controller per use case), ADR-013 (schemas in use-case file), ADR-014/017 (vendor isolation), ADR-015 (events for cross-feature), ADR-020 (manifest-driven coverage bands), or ADR-021 (versioning by commit-path).
|
||
- The relevant feature `feature.manifest.ts` shape so the proposed interface aligns with manifest-first ordering.
|
||
|
||
Each sub-agent outputs:
|
||
|
||
1. **Interface** (types, methods, params — plus invariants, ordering, error modes, schemas if applicable)
|
||
2. **Usage example** showing how callers in this repo would use it (use real file paths and real existing feature names)
|
||
3. **What the implementation hides** behind the seam
|
||
4. **Dependency strategy and adapters** (see [DEEPENING.md](DEEPENING.md)) — which existing ports/adapters get reused, which (if any) are new
|
||
5. **Manifest + binder impact** — which `feature.manifest.ts` entries and which `bind-production.ts` / `bind-dev-seed.ts` files change
|
||
6. **Trade-offs** — where leverage is high, where it's thin
|
||
7. **ADR conflicts (if any)** — call out by ADR number with rationale, or state "none"
|
||
|
||
### 3. Present and compare
|
||
|
||
Present designs sequentially so the user can absorb each one, then compare them in prose. Contrast by:
|
||
|
||
- **Depth** (leverage at the interface)
|
||
- **Locality** (where change concentrates)
|
||
- **Seam placement** (which existing `*.interface.ts` survives, which gets replaced, which is new)
|
||
- **Conformance impact** (how many manifests change, how many binders change, how many tests rewrite)
|
||
- **Coverage delta** (cumulative L0 band impact — does any layer drop below its declared 100% / 95%?)
|
||
|
||
After comparing, give your own recommendation: which design you think is strongest and why. If elements from different designs would combine well, propose a hybrid. Be opinionated — the user wants a strong read, not a menu.
|
||
|
||
If the chosen design crosses a feature-package boundary (e.g. moves a use case from `@repo/blog` to `@repo/media`), state explicitly:
|
||
|
||
- Which `feature.manifest.ts` files lose / gain entries
|
||
- Which package versions will bump on the next release-please PR (per ADR-021 commit-path bump targeting)
|
||
- Whether the migration needs an intermediate compatibility seam to keep `pnpm conformance` green during the transition
|
||
|
||
The implementation lands via the manifest-first ordering: (1) update the manifests in both packages, (2) write the new contracts in the use-case file, (3) write the failing tests, (4) implement until green. Don't skip the order even when the move feels mechanical.
|