architect-design

Architect Design

Structured design process: from grill/domain-modeling conclusions to complete NOTES.md + tech-spec.md + any needed domain documentation updates.

Vocabulary

Use design-vocabulary.md throughout — module, interface, depth, seam, deletion test, leverage, locality. Do not drift into "component," "service," "API," or "boundary."

Inputs

• Grill conclusions (assumptions exposed, constraints identified)
• CONTEXT.md domain glossary (from /aiops-setup)
• docs/adr/ existing architecture decision records
• .scratch/<feature>/VERDICT.md (if prototyper ran)
• graphify-out/graph.json (if /code-graph has been run — query via /code-graph query god-nodes, /code-graph query communities for overview)

Process

Step 1: Constraint gathering

Extract constraints from all inputs. Classify:

• Hard constraints: cannot be violated (existing ADRs, platform limits, team capacity, compliance)
• Soft constraints: preferences that can be traded off (performance targets, code style, library preferences)

List constraints explicitly in NOTES.md Context section. Reference ADRs by number — do not re-litigate settled decisions unless friction is real enough to warrant revisiting (mark clearly).

Step 1.5: Graph validation (if code graph available)

If graphify-out/graph.json exists, validate constraints against the actual code structure:

1. Query /code-graph query modules to get the current module inventory
2. For each constraint referencing existing modules, verify the module exists and matches the constraint's assumptions
3. Query /code-graph query deps <module> to check dependency claims
4. Flag any constraint that contradicts the graph (e.g., "Module A doesn't depend on Module B" but the graph shows it does)

Record graph-validated constraints in NOTES.md with [graph-verified] tags.

Step 2: Module identification

Identify the modules needed to satisfy the requirements. For each candidate module:

1. Deletion test: imagine deleting it. Does complexity vanish (pass-through → merge into caller)? Or does complexity reappear across N callers (earning its keep → keep it)?
2. Depth assessment: is the interface small relative to the behaviour it hides? Deep = high leverage for callers. Shallow = interface nearly as complex as implementation → merge or split.
3. Scope check: does the module own a coherent slice of the problem, or is it a grab-bag?

Label each module as new (greenfield) or deepening (refactoring existing shallow modules into one deep one).

Step 3: Dependency mapping

For each module, map its dependencies and decide the integration strategy:

Dependency type	Examples	Integration
In-process	Pure computation, in-memory state	Merge directly into module, no seam needed
Local-substitutable	PGlite for Postgres, in-memory FS	Test with stand-in; seam stays internal
Remote but owned	Internal microservices, internal APIs	Define interface at seam; production transport + in-memory test double
True external	Stripe, Twilio, third-party	Inject behind interface; mock for tests

Rule: don't introduce a seam unless at least two implementations are justified (typically production + test). A single-implementation seam is just indirection.

Step 4: Interface design

For each module, design the interface:

• Minimize entry points: fewer methods = fewer tests needed = higher leverage per method
• Simplify parameters: what can the interface hide from callers?
• Accept dependencies, don't create them: inject what the module needs, don't hardcode it
• Return results over side effects: prefer pure outputs when possible
• Document everything a caller must know: invariants, ordering, error modes, configuration, performance

The interface is the test surface — callers and tests cross the same seam.

Step 5: Explore alternatives

For the most critical module (highest risk, most callers, or deepest impact), design ≥2 radically different interfaces:

• Design A: minimize interface — 1–3 entry points, maximum leverage per entry point
• Design B: maximize flexibility — support many use cases and extension points
• Design C (if applicable): optimize for the most common caller — default case trivial

Compare: which design gives callers the most capability per unit of interface they learn? Where does change concentrate? Where are the seams?

Pick the strongest, or propose a hybrid. Record in NOTES.md:

• Chosen approach
• Rationale: why this one
• Rejected alternatives: at least one, with reason for rejection
• Constraints imposed: what this decision locks in

Step 6: Domain documentation pass

Before finalizing the design artifacts, run a short /domain-modeling pass:

1. Extract new or changed domain terms from the design.
2. Add only project-specific domain language to CONTEXT.md; skip general engineering terms.
3. Check each design decision against the ADR threshold: hard to reverse, surprising without context, and a real trade-off with alternatives.
4. Create docs/adr/NNNN-slug.md only for decisions that meet all three criteria; otherwise skip the ADR.
5. Record the outcome in NOTES.md so downstream agents know whether domain docs were changed or intentionally left alone.

Step 7: Specification output

Produce the primary design artifacts:

NOTES.md — design decisions, trade-off analysis, constraints:

• Problem statement (one sentence)
• Context (existing system, known constraints, relevant ADRs)
• Design decisions (chosen + rejected + rationale + constraints imposed)
• Domain docs (CONTEXT.md updates, ADRs created, ADRs skipped with brief reason)
• Scope (in scope / out of scope)
• Open questions (blocking items must be resolved before planner)

tech-spec.md — technical specification:

• Architecture (module relationship description)
• Module inventory (each module: interface, depth assessment, dependencies, integration strategy)
• Data model (entities, fields, types)
• API contracts (method + path + request/response for each interface)
• Sequence (step-by-step interaction between modules)
• Risks (risk + impact + mitigation)

Constraints

• Do not write implementation code (interface signatures and pseudocode only)
• Every design decision must list at least one rejected alternative with reason
• Name modules using CONTEXT.md domain terms; if introducing a new term, add it to CONTEXT.md
• ADRs stay optional: write one only when the /domain-modeling ADR threshold is met
• Existing ADRs are not re-litigated unless friction warrants it (mark explicitly)
• Open questions with blocking items must be flagged — planner cannot start until resolved
• Label each module as new or deepening existing modules