architecture-review

name

architecture-review

description

Run a repeatable, evidence-based architecture review of an existing codebase. Use when asked to assess modularity, coupling, cohesion, dependency direction, circular dependencies, blast radius, fragile seams, shallow modules, testability, ownership boundaries, architectural drift, structural risk, or fit between intended and observed architecture. Drives local search/read/grep, code graph, GitNexus/change-history, AST/LSP, language, and operational tool evidence; scores with the scorecard and writes cited findings. NOT for line-level code review, target architecture design (use architecture-design), or implementation sequencing (use architecture-plan after design approval). When archfit is available, consumes and calibrates its deterministic facts without replacing independent review judgment.

Architecture review

The review loop, in order. Do not skip ahead — each step gates the next.

When to use

Use when a user wants their architecture reviewed, audited, or scored; wants to understand where modularity, coupling, dependency, blast-radius, or fragility risk lives; or wants to compare intended and observed architecture. For comparing two existing reports use architect-compare-reports. For a combined "review and refactor" request, finish the read-only review first, then recommend exactly one primary next skill: architecture-design when remediation needs a target state, or architecture-plan only when an approved target design already exists. A mutator or engineer applies changes after approval. For target architecture or requirements-to-design work without review, use architecture-design instead.

Skill navigation

• User asks to define target architecture or work from requirements: use architecture-design instead of reviewing implementation quality.
• Current skill: use architecture-review to compare intended architecture with observed implementation. Treat design docs as intent only; actual code, runtime config, and tests may have drifted.
• Next skill after a report: choose one primary next step:
  • stop when the user asked for audit/scoring only;
  • architecture-design when findings need target boundaries, contracts, tests, or fitness checks;
  • architecture-plan only when the target design is already approved and the user asks for implementation sequencing.
• After implementation, run architecture-review again with comparable scope to check whether the code now matches intent.

Task list discipline

Maintain a visible task list for the review flow. Track at least:

1. Context and scope confirmed.
2. Working model validated.
3. System map built.
4. Module volatility/change-rate judgments captured.
5. Evidence gathered by dimension.
6. Deterministic tool facts calibrated when available.
7. Findings triaged.
8. Scores assigned.
9. Report written and checked.
10. Next skill recommendation made.

Keep task names outcome-based. Do not expose runtime-specific mechanics in the instructions or report.

Procedure

1. Interview if context is missing. Do not score from a cold start. If you lack the intended architecture, quality goals, volatile areas, or scope, run the interview first. See references/interview.md. Inspect docs, ADRs, and manifests before asking — never ask a question the repo already answers. Ask only for missing context whose answer would change the architecture assessment. Non-interactive runs (CI, autonomous): when no user is reachable, reconstruct intent from docs/ADRs/CLAUDE.md/changelog, label the context reconstructed, and cap analysis_confidence accordingly. Never invent intent.

2. Validate the working model. Before scoring, surface your current understanding for correction: system purpose, candidate units, responsibilities, major integrations, domain classifications, ownership/deploy assumptions, known pain, and doc-vs-code drift risks. Existing architecture docs describe intended design, not necessarily current implementation. Ask only for corrections that would change the assessment. In non-interactive runs, mark this model as reconstructed and record unconfirmed assumptions in missing_evidence.

3. Build the system map before judging quality. Establish what exists: languages, package managers, units, deploy units, public interfaces, declared modules (manifests/dirs) vs observed modules (graphs/imports/churn), high-risk entrypoints, and missing evidence. This populates system_map in the report frontmatter. Scoring before a map is forbidden. Scoring from directory shape alone is explicitly forbidden — a directory tree is not an architecture.

4. Capture module volatility/change-rate judgments. For every important module or boundary, record reusable labels in module_volatility: module, core/supporting/generic classification, high/medium/low volatility, source (interview, docs, architect-inferred, archfit-label, or git-history as corroboration only), evidence refs, confidence, and notes. Domain role is primary; churn is supporting evidence, never the source that sets volatility. Unconfirmed labels go to archfit_calibration.labels_to_confirm when archfit could consume them.

5. Gather evidence across applicable dimensions. Use tools-code-search for local search/read/grep first. If the repo has .archfit.yaml/archfit.yaml or archfit is available, run tools-archfit as a deterministic preflight: full JSON/scorecard, delta when a base ref is known, tool coverage, findings, and . Then climb the narrowest evidence ladder that can prove each claim: ast-grep/tree-sitter for syntactic presence, LSP for resolved symbol truth, codegraph, codebase-memory-mcp, or language dependency tools for graph shape and cycles, GitNexus or git history for co-change/churn, and operational tools for deploy/runtime coupling. Cite tools and files you used. Record coverage — used, skipped, missing, failed — per dimension, even where you find nothing wrong. Summarize output; do not paste raw dumps.

Output

A completed review produces an architecture report using ../../templates/report.md. The report must include interview_context, system_map, module_volatility, scores, findings, evidence, and tool_coverage. When archfit was used, include an archfit_calibration block or section with confirmed, severity-adjusted, false-positive/noise, missed-by-archfit, config-change, new-fitness-check, and label-to-confirm entries. Each finding must include a human-facing narrative explaining the leak or drift, complexity impact, cascading-change scenarios, recommendation, and trade-offs. If remediation is requested, recommend exactly one primary next skill unless the user asks for the full pipeline: architecture-design for target-state work, or architecture-plan only when an approved design already exists and implementation sequencing is requested.

Quick sweep output

Use this mode when the user asks to compare or sample multiple repos, or when a full report would be too expensive. A quick sweep is still evidence-based, but it returns hypotheses and next checks, not final scores.

For each target, use this compact shape:

• scope: repo/path and review depth (quick-sweep).
• intent_evidence: README/ADR/agent-doc refs that define purpose and intended units.
• system_map: languages, package/deploy units, major directories, public interfaces.
• module_volatility: reusable module/domain/volatility judgments and confidence.
• tool_coverage: tools used, missing, failed, stale, and confidence impact.
• commands_run: exact commands or scripts used, scoped to the repo.
• archfit_calibration: when archfit was used, confirmed/severity-adjusted/ false-positive/missed/config/check/label summary.
• dependency_snapshot: package/module counts, cycles if checked, fan-in/out hotspots if checked; summarize as bullets, not raw JSON.
• coupling_candidates: relationship records only where evidence exists; otherwise label hypotheses.
• likely_findings: confirmed findings only; no evidence means no finding.
• next_checks: the smallest follow-up commands that would turn hypotheses into findings.
• quality_self_check: structure, clarity, usefulness, repeatability, helpfulness with a short reason for each; rerun or revise if any is no or weak.

Quick-sweep hard rules:

• Do not assign architecture scores unless the full review gates were met.
• Do not call a hypothesis a finding.
• Include enough commands and file refs that another agent can repeat the sweep.
• Do not dump raw tool JSON or large dictionaries; turn them into ranked bullets with counts.
• Parse tool output before treating a nonzero exit as failure; many analysis tools use nonzero exits for confirmed findings.
• If the result is only inventory, say it is not useful enough and run one deeper dependency or semantic pass.
• Do not mark the quality self-check as all-yes without a reason for each criterion.

Required response clauses

When asked to describe the review workflow, include these clauses explicitly:

• Inspect docs, ADRs, manifests, and repository structure before asking.
• Treat architecture/design docs as intended architecture, not proof that the implementation still matches them.
• Ask only for missing context whose answer changes the architecture assessment.
• Validate the working model before scoring.
• Build the system map before scoring; never score from directory shape alone.
• Require cited evidence and per-dimension tool coverage before findings or scores.
• Keep the review read-only on source; route implementation to a mutator or engineer.

When the user asks to review and refactor, separate the response into review, scoring/recommendations, next-skill recommendation, and implementation handoff. Use the exact skill name that applies next: architecture-design when target state is missing, or architecture-plan when an approved design already exists. State that the architect refuses source edits, and that the handoff includes verification steps and acceptance criteria for the mutator or engineer.

Structured questions by runtime

Use references/interview.md for the full interview and fallback rules. In the main review flow:

• Determine availability only from the active runtime's exposed tool list, never from source agent metadata, per-target overlays, repo metadata, or generated config.
• Use concrete tool names only when that tool is actually exposed.
• If no structured-question tool is available, ask exactly one plain prose question and wait.
• Ambiguous or deferred answers become missing_evidence and lower analysis_confidence.

Hard rules

• No scoring before a validated working model and system map; never score from directory shape alone.
• No trusting stale architecture docs as implementation truth.
• No finding without cited evidence and a human-facing narrative.
• No coupling_balance score without per-relationship strength, distance, volatility, and evidence records.
• No high-quality band on low confidence or missing/thin evidence.
• No treating archfit, codegraph, GitNexus, or any single tool's green result as complete architecture proof; calibrate coverage and verify important claims.
• Read-only on source. Recommend exactly one primary next skill: route target definition through architecture-design, or route approved implementation sequencing to a mutator/engineer via architecture-plan with verification-backed acceptance criteria.