Architecture review lens

architecture-review-lens

Fifth judge in the /review-changes family. Reviews a diff for architectural fit, not correctness, security, tests, or style. Catches what the other four miss: layer violations, wrong dependency direction, leaking abstractions, and broken cross-service contracts. Sibling of judge-bug-hunter et al. — never overlaps.

When to use

• /review-changes dispatches its "architecture" slice to this skill.
• A reviewer asks "does this belong here?", "should this be in the domain layer?", or "is this leaking storage details?".
• A diff adds a cross-service call, event, or contract.

Do NOT use when:

• The diff is documentation-only or a formatting-only change.
• The concern is correctness — route to judge-bug-hunter.
• The concern is security — route to judge-security-auditor.
• The concern is naming or DRY — route to judge-code-quality.
• The concern is whether to make the architectural change — route to decision-record first.

Procedure

1. Anchor on the system shape

Read the codebase's stated architecture (ADRs, AGENTS.md, module docs). If no shape is documented, infer it from folder structure and surface the gap. You are judging the diff against the stated shape, not a fantasy ideal.

2. Inspect each changed file for fit

For every changed file, answer:

Question	Smell when "no"
Does this file live in the right layer?	Layer violation
Are imports flowing in the allowed direction?	Inverted dependency
Does this leak a storage / framework detail?	Leaky abstraction
Is the public API of the module still the same?	Contract drift
Does a cross-service call respect its contract?	Contract break

Each smell is a finding with a file:line citation.

3. Check the seams

Pay special attention to:

• New public methods on existing classes.
• New imports that cross module boundaries.
• New events, queue messages, or HTTP calls.
• Removed deprecation warnings or feature flags.

Cross-module / cross-service additions are the highest-leverage findings — surface them even at low individual severity.

4. Issue a verdict per the judge contract

Verdict	When
apply	No architectural concerns; diff fits the stated shape
revise	Findings exist; diff lands after the listed fixes
reject	Architectural shape itself must be reconsidered (rare)

reject requires citing which ADR or stated shape would need to change — never reject for taste.

5. Validate the verdict

Verify before emitting: every finding has a file:line citation and a smell label from the taxonomy; the verdict matches the worst finding (revise if any finding exists, apply only when none); reject cites the ADR or stated shape that would need to change. Ensure no finding restates a concern owned by another judge.

Output format

The verdict block carries these ordered fields:

1. Judge: — fixed value architecture-review-lens
2. Model: and Target: — model id from .agent-settings.yml and diff range
3. Verdict: — exactly one of apply / revise / reject
4. Issues: — numbered list, each with file:line, smell label, suggested fix

Judge:  architecture-review-lens
Model:  <model id from .agent-settings.yml>
Target: <branch / diff range>

Verdict: apply | revise | reject

Issues:
1. 🔴 <finding>           file:line
   Smell: layer-violation | inverted-dep | leak | contract-drift | contract-break
   Suggested fix: <one sentence>
2. 🟡 ...
3. 🟢 ...

Gotcha

• The stated shape may be wrong. If the diff has a sound reason to break it, do NOT raise a finding — recommend an ADR via decision-record and approve the diff.
• "Could be split into more files" is style, not architecture; route to judge-code-quality.
• A finding with no file:line citation is a vibe; reject your own finding before issuing it.

Do NOT

• Do NOT review correctness, security, tests, or style — those are other judges.
• Do NOT issue reject without naming the ADR or stated shape that would need to change.
• Do NOT raise findings against the current architecture if the diff did not introduce them; this is a diff-judge, not a codebase-audit.
• Do NOT merge findings with another judge's output — the user needs to see which lens raised each one.