/architecture-compass

name: architecture-compass
description: "Architectural thinking partner for an existing repository — scans the codebase, conducts a structured interview, agrees on current architectural state and recommended direction, and produces a shareable insights document. Scoped to one repository, module, or folder. Does not execute transformation — it orients. Use when the user says 'assess my codebase architecture', 'what direction should my codebase go', 'architecture compass', 'understand my architecture', 'audit architecture drift', 'architectural assessment', or 'help me understand what is wrong with my codebase'."

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.

---

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