architecture

Find where the structure resists change and propose deepenings: refactors that put more behavior behind smaller interfaces, so the code gets easier to test and easier for an agent to navigate.

A new codebase or area has no friction to find yet. There, skip the search: go straight to the interview (step 3), settle the structure and conventions, and write the result to ARCHITECTURE.md.

The conventions this skill owns are indexed in conventions/ and load only when the work touches them; implement follows them while building.

Fast by default: search only the area or friction the user named, show the strongest few candidates, and hold the parallel interface designs until asked. Deep mode (the deep skill is active): the whole codebase, every candidate, and parallel interface designs for the chosen one.

Vocabulary

Speak in the terms of LANGUAGE.md every time: module, interface, implementation, depth, seam, port, adapter, leverage, locality. Drifting into "component", "service", "API", or "boundary" blurs the distinctions this skill exists to draw. The checks it leans on most:

• Deletion test: would removing the module make complexity vanish (it was a pass-through) or reappear in every caller (it was earning its place)?
• Tests cross the interface that callers cross.
• A seam is real once a second adapter fills it.
• An interface with more than one consumer is a promise. Deepen behind it by adding, never by reshaping what callers rely on; a breaking change to it is a migration to plan, not a refactor to slip in.

The domain model steers the work: names for good seams come from CONTEXT.md, and decisions in docs/adr/ are settled ground, not open questions. Formats: TERMS.md, DECISION-RECORD.md.