architecture-refiner

# Architecture Refiner

## Step 0: Style Selection

Before anything else, ask the user which architecture style their team uses:

"What architecture style does your team use?

1. **Clean Architecture** (default) — layers (Domain, Application, Interface, Infrastructure), dependency inversion, command/query separation
2. **Hexagonal / Ports & Adapters** — core domain surrounded by ports, adapters on the outside
3. **Modular Monolith** — vertical slices, each module owns its own layers
4. **Custom / Define from scratch** — you describe the layers and rules"

**Branching:**

- **Option 1** → proceed to the clean architecture flow below (existing interview). Template: `./assets/template-clean-arch.md`. Output: `.lattice/standards/architecture.md`. Config key: `paths.architecture`. No `architecture_mode` key needed (defaults to `clean`).
- **Options 2–4** → proceed to the generic architecture flow. Template: `./assets/template-generic.md`. Output: `.lattice/standards/architecture.md`. Config key: `paths.architecture`. Additionally, set `architecture_mode: custom` in `.lattice/config.yaml`.

The rest of this document describes the **clean architecture flow** (Option 1). For the **generic flow** (Options 2–4), read `./assets/template-generic.md` and follow its `<!-- INTERVIEW GUIDANCE: -->` comments. The facilitation approach, conversation style, output assembly, and document quality checks below apply to both flows — substitute the appropriate template, output path, and config key.

## What This Produces

**For clean architecture (Option 1):**

- **Output**: `.lattice/standards/architecture.md` (or custom path from `.lattice/config.yaml` → `paths.architecture`)
- **Two modes**:
  - **Overlay** (`mode: overlay`): A slim document containing only sections that differ from the defaults. The architecture atom reads its embedded clean-architecture defaults first, then applies this document's sections on top. This is the expected common case.
  - **Override** (`mode: override`): A comprehensive standalone document that fully replaces the atom's embedded defaults. For teams that want to define clean architecture from scratch.
- **Default mode**: Overlay -- produces only what the user wants to change
- **Config key**: `paths.architecture` in `.lattice/config.yaml`
- **Template**: Read `./assets/template-clean-arch.md` for the full document structure, default content, and interview guidance comments

**For other styles (Options 2–4):**

- **Output**: `.lattice/standards/architecture.md` (or custom path from `.lattice/config.yaml` → `paths.architecture`)
- **Mode**: Always `override` — there are no embedded defaults to overlay onto for non-clean-architecture styles
- **Config key**: `paths.architecture` in `.lattice/config.yaml`
- **Additional config**: Sets `architecture_mode: custom` in `.lattice/config.yaml`
- **Template**: Read `./assets/template-generic.md` for the document structure and interview guidance comments

## Before You Begin

### Check for existing documents

Before starting the interview, check whether a custom document already exists:

1. Read `.lattice/config.yaml` — check `paths.architecture`.
2. If the relevant path exists (based on the style selected in Step 0), read that file. Ask the user:
   - "You already have a custom architecture document. Would you like to **revise** it (update specific sections), **start fresh** (new interview), or **add to it** (add new sections)?"
   - Revise: Load the existing document, walk through only the sections the user wants to change, and update in place.
   - Start fresh: Proceed with the full interview flow below.
   - Add to it: Skip to the "New Sections" part of the interview.
3. If no config or no existing document, proceed with the full interview flow.

### Scan the repository

Look for signals that inform the conversation:

- **Directory structure**: Does `src/` (or equivalent) already have layers? What are they named?
- **Existing patterns**: Are there existing controllers, services, repositories, providers? What naming conventions are in use?
- **DI patterns**: Is there a DI container, manual injection, or framework-provided injection?
- **Architecture docs**: Any existing architecture documentation (ADRs, README sections)?
- **Framework**: What framework is in use? (NestJS, Spring, Django, etc.) This affects naming conventions and common patterns.

Share relevant findings with the user at the start: "I noticed your project already has [X structure]. I'll use that as context."

If the project is new with no code, proceed with pure defaults as the starting point.

## Choosing the Mode

The first decision in the conversation. Present the three options:

"How would you like to define your architecture principles?

1. **Customize specific sections** (overlay) — Keep the defaults and change only what differs for your project. This produces a slim document. Most teams choose this.
2. **Define everything from scratch** (override) — Walk through all sections and produce a comprehensive standalone document.
3. **Add project-specific sections only** (overlay with additions) — Keep all defaults as-is and add new sections for your team's specific rules.

The defaults cover standard clean architecture well. Option 1 is recommended unless your architecture is fundamentally different."

Map the choice:
- Options 1 and 3 → `mode: overlay`
- Option 2 → `mode: override`

## Facilitation Approach

### Conversation style

- **One section at a time.** Do not dump all questions at once. Walk through the template sequentially.
- **Defaults-first.** For each section, briefly summarize the default, then ask if it matches. Do not read the entire default verbatim -- summarize the key points and ask.
- **Record decisions, not discussion.** The output document reads as a specification, not meeting notes. "We discussed X and decided Y" is wrong. "Y" is right.
- **Probe, don't interrogate.** Use the probing questions in the template guidance comments as follow-ups when