architecture-compass

# Architecture Compass

## Required Skills

Read, apply:

1. `framework:knowledge-priming` -- Load codebase context: language, framework, structure, conventions (always)
2. `framework:architecture` -- Architectural audit lens and recommended direction guardrails (always)
3. `framework:domain-driven-design` -- Strategic DDD only: bounded contexts, domain seams (conditional: only when domain complexity warrants it)
4. `framework:collaborative-judgment` -- Surface judgment calls during co-design rounds (always)

## Workflow

### Step 1: Load Existing Context

**Check for an existing insights document first.** If `.lattice/insights/architecture.md` already exists:
- Read it. Check the Session Status table using these three states:
  - `pending` — row exists, no content written yet
  - `in-progress` — content exists in the section but no agreed date recorded
  - `✅ agreed` — content exists and date is recorded
- Resume from the earliest `pending` or `in-progress` phase. For `in-progress` phases: present the existing content for re-confirmation rather than regenerating it.
- **In-progress without content:** If Current Architecture is `in-progress` but the document has no Current Architecture content (the previous session's scan context was lost), re-run Step 2 scan before presenting.
- **Staleness check:** If the most recent `✅ agreed` date in the Session Status table is older than 30 days, run a lightweight re-scan (Steps 2.1 and 2.6 only — tree + imports). If material structural changes are detected, present them and ask whether Current Architecture needs revision before proceeding.
- Do not re-scan if Current Architecture is already `✅ agreed` and the staleness check passes.
- Tell the user what was found and which phase the session resumes from.

If no existing document: proceed from Step 2.

Check for `.lattice/config.yaml`. Load `knowledge-base.md` and `architecture.md` from `.lattice/standards/` if they exist — these shape both the audit lens and the recommended direction proposal.

If no `.lattice/` config exists, offer to run `lattice-init` first. If declined, infer defaults from the scan.

Use `framework:knowledge-priming` to establish codebase identity before analysis.

---

### Step 2: Silent Scan — Architectural Signal Extraction

Do not ask any questions yet. Scan first, form a hypothesis, then ask only what code cannot reveal.

**Confirm scope before scanning.** If the working directory is a monorepo or contains multiple independent services/modules, ask: *"Which service or module should this assessment focus on?"* Do not scan the full monorepo root — assess one bounded scope at a time. If the user requests the full monorepo: explain that a single insights document cannot meaningfully capture many independent architectures. Offer: (1) assess the shared infrastructure/platform layer as one scope, (2) produce a lightweight index of all services with one-line architecture classification, then deep-assess the 2–3 most painful ones. If the user still insists, proceed with a service-by-service scan at reduced depth (Steps 2.1 + 2.6 per service).

This is signal extraction, not a full read. **Target: 15–25 file reads** (view/open operations). Grep, glob, and directory listings do not count against this budget — they are structural reconnaissance, not deep reads. Stop reading a module once its responsibility, dependencies, and layer fit are clear.

**Scanning protocol — execute in order:**

1. **Directory tree** (3 levels deep) — intended organization, layer structure, naming conventions. Do this before opening any file.

2. **Dependency manifests** — `package.json`, `pom.xml`, `go.mod`, `requirements.txt`. Language, framework, key external dependencies.

3. **Architecture documents** — `README.md`, `ARCHITECTURE.md`, `docs/`, ADR directories. The intended architecture often lives here — the gap between intention and reality is itself a finding.

4. **Archaeology** — before analysing flows, reduce scope:
   - Dead code (no callers) — candidates for deletion, but verify no side effects first: static initializers, scheduled tasks, event listeners, and framework hooks are invisible to call-graph analysis
   - Duplicate functionality — two implementations of the same concept, must reconcile before any change
   - Implicit coupling — shared mutable state, globals, ambient context, thread-locals
   - Hidden integration points — outbound calls to external systems in unexpected places

5. **Seam identification and viability** — natural boundaries where one side can change without the other knowing:
   - Domain seams (distinct business concepts), technical seams (I/O vs. business logic), team seams, temporal seams
   - For each seam: assess viability — how many callers cross it? Cheap seams become first moves.

6. **Import and dependency patterns** — grep import statements across all source files. Do not open full bodies. Reveals dependency direction, load-bearing modules, layer violations cheaply.

7. **Entry points** — 3–5 files: routes, controllers, CLI handlers, event consumers. Reveals outermost layer.

8. **Interface and contract files** — interfaces, abstract classes, ports. Reveals intended boundaries, whether followed or not.

9. **One representative file per top-level module** — confirm responsibility, catch what import grep missed.

10. **Stop. Form the hypothesis:**
    - What the architecture actually is vs. what it was intended to be
    - **Drift or mismatch?** Drift = sound intention, gradual decay → restore. Mismatch = wrong pattern for domain → replace. This shapes the recommended direction.
    - Which seams are viable (low exploitation cost)
    - Most significant violations, with specific named evidence
    - Dead code and duplicates that can be cleaned up before any structural work

    If a module remains unclear after Step 9, read one additional file from it. This is the only scan extension permitted.

    **If the scan produces no meaningful architectural signal** — few