build-loop:architecture-review

Files (1)

• SKILL.md

SKILL.md (first lines)

<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->

# Architectural Integrity Review

Orchestrates impact analysis, data-flow tracing, the rules engine, and the lessons system into a 5-phase architectural review. Native to build-loop — content adapted from `NavGator/skills/code-review/SKILL.md`. This skill is an architectural integrity reviewer — not a linter, not a bug hunter.

## What This Skill IS vs. IS NOT

**IS:**
- System flow — how data moves from user input through the system to output
- Component communication — APIs, data formats, connection patterns between layers
- API contract validation — interface changes and whether consumers are updated
- LLM architecture — provider routing, prompt patterns, model selection logic
- Documentation drift — whether docs reflect what the code actually does
- Lessons learned — patterns that caused issues, tracked and matched over time
- Freshness validation — periodic research to avoid stale architectural knowledge

**IS NOT:**
- Code linter or style checker
- Individual function bug hunter — local logic errors, off-by-one mistakes
- Security vulnerability scanner — use `security-reviewer` agent or dedicated tools
- Test coverage auditor
- TypeScript type error detector — the compiler handles that
- Performance optimizer — out of scope

## When to Activate

- Build-orchestrator Phase 4 Review when the build touches 2+ layers (cross-layer change)
- User asks "review architecture", "is this safe to merge", "what did I break"
- After a large refactor

## Scope Resolution

| Invocation | Scope |
|------------|-------|
| Default (no flags) | `git diff origin/main..HEAD` — changed files since branch diverged |
| `--all` | Full architecture review across all components |
| `<component>` | Focused review on one component and its direct connections |
| `--validate` | Run Phase 5 freshness validation regardless of age |
| `learn "..."` | Record a manual lesson, skip full review |

When scope is ambiguous, default to `git diff origin/main..HEAD`. If the branch has no divergence from main, ask the user what to review.

## Prerequisites

1. `.navgator/architecture/index.json` must exist. If not, run `build-loop:architecture-scan` first.
2. If `generated_at` is >24 hours old, warn before proceeding.
3. Load `.navgator/architecture/file_map.json` for file-to-component resolution.
4. Load `.navgator/architecture/graph.json` for connection traversal.
5. If `.navgator/lessons/lessons.json` is missing, create:
   ```json
   { "schema_version": "1.0.0", "lessons": [] }
   ```

Do not proceed without architecture data. Stale data is worse than pausing.

---

## Phase 1 — Structural Changes

**Goal:** Identify which components and layers were touched.

1. Run `git diff [scope] --stat` to get changed files
2. For each changed file, look it up in `file_map.json` → parent component ID
3. Look up component ID in `index.json` → type and layer
4. Classify each change: new component / modified connection / config change / documentation
5. Identify which layers were touched: frontend, backend, database, infra, external
6. Flag any cross-layer change as **higher risk**
7. Note any new files that don't resolve to any tracked component

```
PHASE 1: STRUCTURAL CHANGES
  N components touched across N layers
  Cross-layer: [ComponentA (frontend→backend), ComponentB (backend→database)]
  New components: [unconnected — needs scan to track]
  Layers: frontend(N) | backend(N) | database(N) | infra(N)
```

---

## Phase 2 — Connection & Flow Integrity

**Goal:** Verify connections valid, data flows intact.

For each component from Phase 1:

1. Call `build-loop:architecture-impact` (uses `mcp__plugin_navgator__impact`)
2. Call `build-loop:architecture-trace` direction=both
3. Call `mcp__plugin_navgator__connections` direction=both

| Issue | Severity | Detection |
|-------|----------|-----------|
| Orphaned component | Important | New component with 0 incoming AND 0 outgoing connections |
| Broken reference | Critical | Connection points to a component not in `graph.json` |
| Layer violation | Critical | Frontend connects directly to database, bypassing backend |
| High fan-out | Important | Component has >8 outgoing dependencies |
| Import cycle | Critical | Component A → B → A |
| API contract mismatch | Critical | Interface changed, consumers not updated |
| Self-referencing connection | Important | Component listed as its own dependency |

```
PHASE 2: CONNECTION INTEGRITY
  Rules: N violations (N critical, N important, N minor)
  [CRITICAL] Layer violation: ComponentA (frontend) → ComponentB (database)
    File: src/pages/users.tsx:45
    Why: Frontend bypasses API layer, creating tight coupling.
```

If no violations: report "No connection integrity issues found" — do not omit.

---

## Phase 2.5 — LLM Purpose Classification

**Goal:** Classify what each LLM call does, not just who it calls.

1. Run `mcp__plugin_navgator__llm_map` with `--classify`
2. For each uncategorized use case: read the primary file, determine purpose (summarization, extraction, search/ranking, generation, embedding, classification, translation, agent/tool-use, validation, analysis, synthesis)
3. Note system effect (search results, UI charts, DB writes, queue processing, API responses)

From tyroneross/build-loop, Apache-2.0.

More from tyroneross/build-loop