architect

``` █████╗ ██████╗ ██████╗██╗ ██╗██╗████████╗███████╗ ██████╗████████╗ ██╔══██╗██╔══██╗██╔════╝██║ ██║██║╚══██╔══╝██╔════╝██╔════╝╚══██╔══╝ ███████║██████╔╝██║ ███████║██║ ██║ █████╗ ██║ ██║ ██╔══██║██╔══██╗██║ ██╔══██║██║ ██║ ██╔══╝ ██║ ██║ ██║ ██║██║ ██║╚██████╗██║ ██║██║ ██║ ███████╗╚██████╗ ██║ ╚═╝ ╚═╝╚═╝ ╚═╝ ╚═════╝╚═╝ ╚═╝╚═╝ ╚═╝ ╚══════╝ ╚═════╝ ╚═╝ ``` # Architect the shape first Code is easy to write and hard to reshape. The interface you choose outlives the implementation. This skill produces a deliberate design instead of the first one that compiles. ## 1. Search before you build Before designing anything custom, decide where this work belongs on the ladder: - **Adopt** — a library/tool already does this well. Use it. - **Extend** — something close exists; extend it. - **Compose** — combine existing pieces. - **Build** — only when the above genuinely don't fit. Check package registries, the existing codebase, and installed skills/MCP tools first. Report what you found and why you're building rather than adopting. Most "new" problems are solved problems. ## 2. Design it twice (at least) Never ship the first design. Generate **2-3 genuinely different** designs, each forced apart by a *different constraint*: - minimize the interface surface - maximize flexibility - optimize the common case - imitate a known, well-understood paradigm - survive failure well (idempotency, partial-failure, retries, backpressure) If subagents are available, dispatch them in parallel — one design each — so the options don't converge. Then compare. ## 3. Judge on depth, not effort - A **deep** interface is small but hides significant complexity (good). A **shallow** one is a large surface over a thin implementation (bad — it just relocates complexity onto callers). - Optimize for **ease of correct use** and **hardness of misuse**. - Do **not** rank designs by how much code they take to implement — that's the cheapest part and the wrong axis. - **Record the decision, including the losers.** Output a short comparison (each design × how it scores on the constraints / its key failure mode) and one sentence per rejected design saying exactly why it lost. A design chosen with no written loser isn't a decision — it's the first thing that compiled. ## 4. Earn every abstraction - **Deletion test:** imagine deleting this module. If the same complexity reappears, duplicated across N callers, the module earned its place. If not, you're abstracting for its own sake — don't. - **Two-adapter rule:** one adapter is a *hypothetical* seam; two real adapters prove a seam exists. Don't introduce an interface for a single implementation "in case." (This is `forge:principles` #2 applied to structure.) **Exception:** a test double or an external-boundary port (network, clock, third-party API, persistence you'll mock in tests) *is* the second adapter — seam it. ## 5. Name and record - Name every concept in the project's **ubiquitous language** — one canonical term per idea, aliases explicitly retired. Update CONTEXT.md. - Record an **ADR** only when the decision is hard to reverse *and* surprising without context *and* a real trade-off. Capture the *decision and why*, not file locations (those rot). ## Exit Hand the chosen shape to `forge:plan` to break into vertical slices, then `forge:tdd` to build.