Architecture Review

Use this skill before implementing a non-trivial structural change. Do not use it for a local bug fix or a small refactor whose boundaries and contracts remain unchanged.

The score is a decision aid, not a substitute for reasoning. Explain the evidence behind each score and reject an abstraction that adds complexity without improving the baseline.

Workflow

1. Describe the current design as the baseline, including its duplication, coupling, contracts, tests, and hot path.
2. Describe the smallest viable proposal and at most one meaningful alternative.
3. Identify affected public APIs, package boundaries, consumers, and per-call production paths.
4. Score the baseline and proposal from 1–10 on each dimension below using baseline → proposal.
5. Require the proposal to score at least 8/10 on five dimensions. Treat regressions in public-surface discipline or hot-path fitness as blockers even if the aggregate score passes.
6. Ask the user before implementation when two viable designs have meaningful trade-offs.
7. Record the selected design's contracts and cover boundaries with observable tests.