Software Design Review Router

Software Design Review Router

Review software design by routing to the smallest useful set of reference lenses, then synthesize one system-level judgment.

Match the user's language when asking questions, explaining tradeoffs, and delivering the final review.

This skill is especially useful for:

• reviewing AI-generated implementation plans before execution
• reviewing AI-generated code changes for structural risk
• collaborating on feature-change plans where long-term evolvability matters
• critiquing proposals that feel locally convenient but globally fragile

Default behavior:

1. Pick exactly one primary review lens. 2. Add up to two secondary lenses only when they materially change the judgment. 3. Read only the references you selected. 4. Return one integrated review, not a stack of disconnected mini-reviews.

When Not To Use This Skill

Do not use this skill when the task is primarily:

• implementing a feature
• fixing a syntax or type error
• answering framework or library how-to questions
• debugging a single defect with no design tradeoff to evaluate
• reviewing code only for style, lint, or local correctness

If the task is mostly code maintainability with no meaningful design question, do not trigger this router just because maintainability is mentioned.

Workflow

Follow this sequence:

1. Frame the review. 2. Select references. 3. Review through the selected lenses. 4. Synthesize a system-level judgment. 5. Self-check before responding.

Reference reading rule:

• start with the shared front sections of each selected reference
• go into Deep checks only when the initial review reveals meaningful ambiguity, structural weakness, or high-impact risk
• do not expand into deep checks for every lens by default

1. Frame The Review

Before opening references, identify:

• the design decision or design tension being evaluated
• the dominant concern that should drive the judgment
• the likely system scope: component, service, bounded context, API, schema, workflow, or platform capability
• whether the user wants critique of an existing design, comparison of options, or validation of a proposed direction
• whether the artifact under review is a plan, a code change, an ADR, or a broader design proposal

Choose one dominant concern. Good defaults:

• architectural decision quality for ambiguous tradeoffs
• dependency impact for risky change propagation
• coupling for boundary and responsibility leakage
• change resilience for ad hoc fixes, workaround hardening, or future modification pressure
• domain language or modeling for semantic ambiguity
• non-functional governance for scale, latency, throughput, or cost constraints
• security governance for authorization, trust boundaries, auditability, or tenant isolation

Good artifact-to-lens defaults:

• AI-generated plan with plausible structure but weak reasoning: start with decision-quality-review
• change plan with rollout, migration, or blast-radius uncertainty: start with dependency-change-impact-analysis
• code or plan that feels ad hoc, workaround-heavy, or over-abstracted: start with change-resilience-review
• service split, shared schema, or cross-team friction debate: start with software-coupling-review
• domain confusion, naming drift, or aggregate tension: start with domain-description-language, ubiquitous-language-naming-review, or relationship-modeling-review

2. Select References

Pick one primary reference first. Add secondary references only if they change the recommendation, not merely because they are related.

Primary Lens Selection

• Read references/decision-quality-review.md when the main question is whether the decision framing, criteria, alternatives, or reasoning are sound. This is the default primary lens for ADR critique and architecture tradeoff review.
• Read references/dependency-change-impact-analysis.md when the main risk is blast radius, migration safety, hidden consumers, or compatibility fallout from a change.
• Read references/software-coupling-review.md when the main issue is service boundaries, schema or API coupling, responsibility placement, or change propagation across layers.
• Read references/change-resilience-review.md when the main issue is ad hoc structure, workaround hardening, speculative extensibility, or whether the change makes the next likely change easier without overbuilding for unknown futures.
• Read references/domain-description-language.md when the main issue is ambiguous business meaning, fuzzy rules, overloaded states, or unclear domain operations.
• Read references/ubiquitous-language-naming-review.md when the main issue is naming, term consistency, vocabulary drift, or context-specific semantics.
• Read references/relationship-modeling-review.md when the main issue is aggregates, ownership, lifecycle relationships, conceptual boundaries, or entity coordination.
• Read references/non-functional-budget-governance.md when the main issue is scale, latency, throughput, reliability, performance-cost tradeoffs, or operational budget governance.
• Read references/security-authorization-auditability-governance.md when the main issue is authorization, trust boundaries, privileged flows, auditability, or tenant isolation.

Secondary Lens Selection

• Add references/maintainability-review.md only as a secondary lens when long-term changeability, readability, or testability would materially alter the design recommendation.
• Add references/decision-quality-review.md as a secondary lens when another primary lens finds a structural issue but the deeper problem may be bad framing or a distorted evaluation axis.
• Add references/software-coupling-review.md as a secondary lens when another primary lens exposes boundary leakage or cascading ownership problems.
• Add references/change-resilience-review.md as a secondary lens when the main proposal looks locally convenient but may harden a workaround, increase future change friction, or introduce speculative abstraction.
• Add references/non-functional-budget-governance.md as a secondary lens when the design may be locally elegant but operationally expensive or unstable.
• Add references/security-authorization-auditability-governance.md as a secondary lens when a design change crosses trust boundaries or weakens accountability.
• Add references/domain-description-language.md, references/ubiquitous-language-naming-review.md, or references/relationship-modeling-review.md when the primary issue is really semantic drift or broken conceptual boundaries.

3. Review Through The Selected Lenses

For each selected reference:

• apply its method faithfully
• keep findings in the language of that reference
• extract only the findings that matter to the current design tension

Do not turn every review into a full checklist run. Prefer the smallest set of decisive findings.

If the initial pass reveals hidden risk, contradictory signals, or unclear structural tradeoffs, read the Deep checks section of the selected reference before finalizing the judgment.

4. Synthesize One Judgment

Integrate the findings in this order:

1. conflicting optimization goals 2. local optimizations that displace cost elsewhere 3. short-term versus long-term tradeoffs 4. final system-level recommendation

If lenses disagree, explain which dominant concern wins and why.

Output Contract

Structure the final review with these sections:

• framing: what problem is actually being solved and what decision is under review
• dominant concern: the primary evaluation axis and why it should dominate
• findings: the most important design findings, ordered by severity or decision impact
• tradeoffs: the real tradeoffs, including what gets worse if the recommendation is adopted
• recommended direction: the best current direction, with any preconditions or sequencing advice
• open questions: missing information that could change the judgment

When the user asked for a review of existing material, keep the output in a review voice. When they asked for guidance, keep the same structure but phrase the recommendation as design advice.

Gotchas

• Do not blur multiple references into generic architecture advice.
• Do not include a secondary lens unless it changes the recommendation.
• Do not let maintainability replace the primary design judgment; it is a supporting axis here.
• Do not confuse naming symptoms with domain-model problems without checking both possibilities.
• Do not stop at isolated critiques; always conclude with a system-level judgment.
• Do not optimize for short-term implementation convenience if it shifts complexity into future change, operations, or governance.
• Do not skip Deep checks when the proposal feels polished but under-evidenced, or when an AI-generated plan or code change looks coherent yet structurally suspicious.

Self-Check

Before responding, verify:

• one primary lens is explicit
• no more than two secondary lenses were used
• each selected reference was necessary
• the review explains the dominant concern
• the conclusion is integrated rather than a list of unrelated observations
• the response stays at design-review level rather than drifting into implementation details

software-design-review-router

このスキルは何か

設計レビューの相談を、いちばん効く評価レンズ（どの軸で設計を評価するか）に整理し、最小限の軸で設計判断を進めるためのスキルです。

作った意図

設計の相談は、違和感はあっても何が論点なのかが曖昧なまま広がりやすく、結果として一般論の感想戦になりがちです。このスキルは、依存影響、結合、変更耐性、ドメイン言語、非機能、セキュリティなどのどれを主軸に見るべきかを先に定め、設計レビューを散らかしにくくするために作っています。

AI がそれらしく見える設計案や実装案を出したときに、どの軸で疑うべきかを整理したい、という意図も強いです。

どういう人・場面に向いているか

• 設計に違和感はあるが、何を基準に評価すべきかまだ曖昧な人
• ADR や設計案をレビューしたい人
• AI 生成の計画やコード変更を、設計観点で見直したい人

使いどころの例

• service 分割、shared schema、責務境界の置き方をどう評価するか迷う
• 一見きれいな提案だが、将来の変更や運用まで含めると怪しさを感じる
• 命名やモデルの違和感が、単なる言葉の問題なのか設計問題なのか切り分けたい

依頼イメージ

入力例: 「この設計案をレビューして。結合の強さを見るべきか、変更耐性を見るべきか、自分ではまだ定まっていない」

返ってくるもの: まず何を評価軸にすべきか、その軸で見たときの主要な懸念、どの方向で設計判断を進めるとよいかを整理したレビュー

関連するスキル

• refactoring-review-router: 設計一般ではなく、具体的なリファクタリングの進め方を決めたいときに向いています
• delivery-slice-planner: 設計の方向が見えた後、実行順に落としたいときに向いています

Change Resilience Review

Purpose

Review whether a design or change can absorb likely future modification without hardening ad hoc workarounds or overbuilding for hypothetical futures.

When to use

Use this reference when the main concern is that a plan, implementation, or proposed structure feels too temporary, too workaround-heavy, or too speculative to hold up under future change.

Primary questions

• Does this proposal make the next likely change easier or harder?
• Is variability being localized, or spread through exceptions and flags?
• Is a short-term workaround being turned into permanent structure?
• Is the design adding abstraction for real pressure or imaginary flexibility?

Review procedure

1. Identify the next likely changes that matter. 2. Trace where those changes would land in the current proposal. 3. Check whether transition logic or edge cases are shaping the main design. 4. Distinguish proven extension pressure from speculative generalization. 5. Recommend the smallest durable structure that improves future change safety.

Output cues

Produce a review that explains whether the design improves change resilience, where it increases future friction, and whether it is under- or over-structured for the change pressure that actually exists.

Review stance

Do not equate flexibility with quality.

The goal is not maximum extensibility. The goal is to make credible future changes:

• cheaper
• safer
• more local

without inventing infrastructure for futures nobody has earned yet.

Likely-change check

Before judging abstraction, identify:

• which follow-on changes are actually plausible
• which pressures are already recurring
• which constraints are stable
• which edge cases are temporary

If the proposal cannot name the future change it helps, its flexibility may be unproven.

Variability checks

Look for where change pressure is being absorbed.

Good signs:

• one local policy point
• clear extension seam where variation is real
• stable concepts kept stable

Bad signs:

• repeated conditionals in several places
• flags controlling unrelated behavior
• migration logic leaking into steady-state structure
• option surfaces with no current owner

Workaround hardening

Be suspicious when:

• temporary compatibility logic becomes the dominant abstraction
• rare cases shape the common model
• current implementation pain is being embedded as permanent design

A workaround can be necessary. The problem starts when the workaround becomes the architecture.

Speculative generalization

Ask:

• how many real consumers need this abstraction now?
• what repeated pattern proves the variability?
• would the simpler design still be easy to extend after a second real use case appears?

Generalize after pressure is visible, not before.

Common change-resilience traps

Workaround as foundation

A transitional solution is promoted into the base design.

Local patch, distributed cost

Today's simple shortcut creates tomorrow's synchronized edits.

Exception-path architecture

Rare behavior defines the mainline model.

Abstraction before demand

Indirection is added without real variation or repeated need.

Option surface inflation

Public surface area grows faster than real business scenarios.

Deep checks

Use this section when the initial review suggests that the design may be surviving today's problem by making tomorrow's changes harder.

What to probe further

• whether temporary compatibility or exception logic is becoming the steady-state model
• whether one real use case is being used to justify broad abstraction
• whether the next likely change would still scatter across modules
• whether a claimed extension seam has more imagined consumers than real ones

Strong warning signs

• strategy, plugin, or mode systems appear before real variation exists
• feature flags and conditionals keep accumulating without being retired
• a workaround is being promoted because removing the root cause feels harder
• the design claims flexibility but still requires broad edits for the next realistic change

Review prompts

• Which future change is this abstraction actually buying?
• What temporary concern is becoming permanent structure?
• Would a smaller design make the second real use case easier or harder?
• Where is change pressure spreading instead of being absorbed?

Recommendation rules

• Keep temporary concerns isolated from steady-state structure.
• Introduce abstraction only where recurring variation is visible.
• Prefer local complexity over system-wide indirection when change pressure is still narrow.
• Collapse premature frameworks that exist only to feel extensible.
• Add structure when known variability is already scattering across the codebase.

Output shape

Structure findings around:

• the next likely changes that matter
• where those changes would land
• whether the design is too rigid or too abstract
• what smallest structural adjustment improves resilience

Acceptance checks

A strong review from this reference should:

• name the next likely changes that matter
• distinguish workaround hardening from justified structure
• detect speculative extensibility
• make an explicit YAGNI-aware judgment
• recommend the smallest durable structure

Decision Quality Review

Purpose

Review whether a software design decision is being made for the right problem, with the right criteria, and with a realistic path to execution.

When to use

Use this reference when the main question is not "will this work at all?" but "is this the right decision for this context?" This is especially useful for ADR critique, architecture options, major refactors, boundary changes, and AI-generated plans that look persuasive but may be optimizing the wrong thing.

Primary questions

• What problem is actually being solved?
• Which evaluation axis is truly dominant in this situation?
• Which constraints are real, and which are assumed or unexamined?
• Were meaningful alternatives considered, or did the first plausible answer become the decision?
• Can the team actually adopt, operate, and evolve this choice?

Review procedure

1. Clarify the decision under review and the decision it is pretending to be. 2. Identify the dominant evaluation axis for this context. 3. Separate facts, assumptions, and copied best-practice reasoning. 4. Check whether real alternatives were considered. 5. Test whether the proposal is organizationally and operationally survivable. 6. State the most important decision distortions and the best next move.

Output cues

Produce a review that explains what is being optimized, what is being ignored, why that mismatch matters, and what decision direction is strongest now.

Review stance

Judge the quality of the decision, not the aesthetics of the solution.

Do not give extra credit for:

• novelty
• architectural fashion
• abstraction density
• "enterprise-ready" appearance
• AI-generated confidence

A decision can be technically clever and still be poor.

Decision framing checks

Before reviewing details, identify:

• the actual choice being made
• the boundary of the decision
• the expected lifespan of the decision
• the main stakeholders
• the failure mode that matters most
• the cost of being wrong

Red flags:

• the proposal solves several different problems at once
• the review focuses on implementation shape before decision criteria
• "future-proofing" is used without naming a concrete future change
• urgency is used to avoid clarifying the problem

Evaluation axes

The important question is not "which axes exist?" but "which axis should dominate here?"

Common dominant axes:

• purpose fit
• constraint fit
• technical feasibility
• organizational feasibility
• long-term evolvability
• short-term containment
• compatibility stability
• risk reduction

Use one axis as the driver. Treat the others as constraints or tradeoffs.

Information quality checks

Distinguish:

• measured facts
• strong evidence
• operating assumptions
• aspirational claims
• aesthetic preferences

Be skeptical of reasoning built on:

• benchmarkless performance claims
• "industry standard" appeals without context
• framework defaults treated as architecture
• AI-generated plans with no source-of-truth evidence

Alternative quality checks

Ask whether the review compares:

• at least one simpler option
• at least one option with lower operational burden
• at least one option that optimizes a different dominant axis

Weak alternative analysis often looks like:

• one real option plus one strawman
• one option with cosmetic variations
• one default selected before tradeoffs are named

Organizational fit checks

Test whether the choice matches:

• team skill level
• release and rollback capability
• debugging reality
• on-call burden
• ownership clarity
• expected maintenance discipline

A design that requires a stronger organization than the one that exists is not ready, even if it is technically valid.

Common decision distortions

Wrong problem, right-looking solution

The proposal is internally coherent, but aimed at the wrong problem.

Signals:

• solution detail is richer than problem framing
• the stated pain and the optimized metric do not match
• a local complaint is driving a strategic redesign

Criteria drift

The team starts with one goal and gradually judges the proposal on another.

Signals:

• reliability problem becomes a technology prestige debate
• compatibility problem becomes a performance debate
• emergency mitigation becomes a platform rewrite

Evidence theater

The proposal feels well-argued but rests mostly on confidence and vocabulary.

Signals:

• repeated claims without concrete system evidence
• generic references standing in for local facts
• no clear distinction between knowns and unknowns

Alternative collapse

The first credible option becomes the only option.

Signals:

• no honest simpler candidate
• no option optimized for operational reality
• no explicit tradeoff against the current state

Adoption fantasy

The design assumes a stronger execution culture than the organization actually has.

Signals:

• rollout, monitoring, and debugging are missing
• cross-team coordination is assumed to be easy
• the proposal requires discipline that current systems do not show

Deep checks

Use this section when the initial review suggests the decision may be well-presented but poorly grounded.

What to probe further

• whether the stated problem and optimized metric still match after reading the whole proposal
• whether the dominant axis changes between problem framing, comparison, and recommendation
• whether the proposal relies on local constraints while pretending to solve a strategic problem
• whether adoption complexity is being treated as an implementation detail instead of a decision constraint

Strong warning signs

• the proposal explains implementation shape in more detail than decision criteria
• the "alternative analysis" is really one option plus weaker variants
• the most confident parts of the argument are also the least evidenced
• organizational burden appears only near the end, after the architecture is already chosen

Review prompts

• What decision is this proposal actually making?
• If the dominant axis changed, when did it change and why?
• What simpler or more local option deserves a fair comparison?
• What part of the recommendation depends on execution discipline the team does not consistently have?

Recommendation rules

• If the framing is wrong, fix the framing before comparing solutions.
• If the dominant axis is unclear, make it explicit before discussing detail.
• If evidence is weak, narrow the decision or insert validation steps.
• If alternatives were not explored, treat confidence as premature.
• If organizational fit is weak, simplify before scaling ambition.

Output shape

Structure findings around:

• the real decision being made
• the dominant evaluation axis
• the strongest distortion or blind spot
• the most credible alternative or reframing
• the best next step

Acceptance checks

A strong review from this reference should:

• identify the actual decision, not just the proposed implementation
• name the dominant evaluation axis
• separate facts from assumptions
• show whether real alternatives were considered
• make organizational fit part of the judgment
• produce a recommendation that is narrower and clearer than the original debate

Dependency & Change Impact Analysis

Purpose

Review the real blast radius of a proposed change across code, contracts, data, runtime behavior, operations, tests, and ownership boundaries.

When to use

Use this reference when the main risk is hidden consumers, migration coupling, compatibility fallout, rollout danger, or a change that appears local but may propagate widely.

Primary questions

• What actually depends on this change?
• Which consumers, producers, contracts, or operational assumptions are easy to miss?
• What migration, rollout, rollback, or verification work is implied?
• Where is the current impact analysis too optimistic?

Review procedure

1. Define the change boundary clearly. 2. Map the dependency surfaces it touches. 3. Look for hidden or indirect consumers and producers. 4. Separate compatibility concerns from rollout safety concerns. 5. Review migration shape, change order, and evidence. 6. State the real blast radius and what must happen to make the change safe.

Output cues

Produce a review that makes hidden dependencies, migration shape, operational risk, and residual uncertainty explicit.

Review stance

Do not confuse "small diff" with "small impact."

Many dangerous changes are dangerous because:

• dependency surfaces are invisible
• ownership is unclear
• rollout order matters
• tests cover only part of the real dependency graph

Dependency surfaces

Review across:

• modules and libraries
• APIs and internal contracts
• database schemas and data shape
• events and message formats
• configuration and feature flags
• jobs, pipelines, and scheduled processes
• observability and operations
• team ownership boundaries

Hidden-dependency checks

Look for:

• undocumented consumers
• consumers reading data through side paths
• copied schemas or DTOs
• operational scripts depending on the old behavior
• tests that are the only current proof of safety
• rollout steps that assume a specific deployment order

Migration checks

Ask:

• is this additive, mutating, or destructive?
• what compatibility window is needed?
• can new and old behavior coexist safely?
• what cutover signal will show readiness?
• what cleanup step exists after migration?

Migration is part of design, not postscript.

Compatibility versus safety

Separate these questions:

• can old and new parties still communicate?
• can the system be changed in this order without incident?

A change may be technically compatible and still unsafe to roll out.

Common impact traps

Hidden consumer

The change breaks an actor nobody accounted for.

Implicit contract drift

The shape still compiles, but meaning has shifted.

Rollout order hazard

The change only works if several moving parts happen in the right sequence.

Migration without reconciliation

The design changes shape, but not how existing data or behavior will be brought forward.

Ownership vacuum

The change crosses boundaries without clear responsibility for validation and recovery.

Deep checks

Use this section when the initial review suggests that the blast radius is larger or less understood than the proposal admits.

What to probe further

• whether hidden consumers exist outside the main code path or main team
• whether migration steps assume a rollout order that has not been named
• whether rollback is possible once data or contracts have moved forward
• whether operational scripts, dashboards, or support procedures depend on the old behavior

Strong warning signs

• the change is described as additive but cutover still has a sharp edge
• cleanup exists only implicitly and nobody owns it
• compatibility is discussed, but verification is vague
• different teams assume someone else will validate the dangerous step

Review prompts

• Who breaks if this change lands in the wrong order?
• What dependency is easy to miss because it is not in the normal call graph?
• What must be true before cleanup is safe?
• If the change is wrong in production, how exactly do we step back?

Recommendation rules

• Narrow the change if the dependency footprint is not understood.
• Add compatibility stages when destructive change is currently too direct.
• Insert verification and observability before the irreversible step.
• Name the deployment and rollback order explicitly when order matters.
• Treat unclear ownership as a design risk, not just a process issue.

Output shape

Structure findings around:

• the real change boundary
• dependency surfaces touched
• hidden or weakly understood dependencies
• migration and rollout implications
• the safest next move

Acceptance checks

A strong review from this reference should:

• define the real blast radius
• find dependencies beyond the obvious call graph
• distinguish compatibility from rollout safety
• evaluate migration and rollback shape
• identify missing ownership or evidence

Domain Description Language

Purpose

Review or shape the language used to describe a domain so that concepts, operations, states, and rules are expressed precisely enough to support consistent design and implementation.

When to use

Use this reference when the main problem is ambiguous business meaning, overloaded terminology, weak state modeling, or domain behavior being described in technical rather than business language.

Primary questions

• Which concepts actually matter in this domain?
• Which distinctions are getting collapsed into vague or overloaded terms?
• Which operations change business meaning rather than just storage?
• Which states, transitions, and constraints need to be made explicit?

Review procedure

1. Extract the core vocabulary of the domain. 2. Separate concepts, actions, states, and constraints. 3. Identify the distinctions that the current language is hiding. 4. Rework terms so business meaning is carried directly in the language. 5. Check that the resulting language makes behavior, rules, and illegal states easier to see.

Output cues

Produce a review that clarifies domain vocabulary, highlights critical distinctions, and recommends wording that makes business behavior easier to reason about.

Review stance

This is not a programming-language design exercise.

The goal is not elegance or clever naming. The goal is to express domain meaning with enough precision that:

• rules are visible
• states are legible
• behavior is discussable
• invalid situations are harder to hide

Vocabulary layers

Review the language in four layers:

• concepts
• operations
• states and transitions
• constraints

Weak domain language usually mixes these together until nothing is precise.

Concept checks

Extract the real nouns of the domain.

Look for:

• concepts that are present but unnamed
• one term covering several distinct things
• technical names standing in for business concepts
• data containers treated as if they were domain concepts

Prefer terms that describe meaning, not storage or transport.

Operation checks

Domain operations should describe what changes in the business world.

Weak signals:

• create
• update
• process
• manage
• handle

Stronger signals usually name the domain effect, such as:

• reserve
• approve
• reject
• expire
• settle
• reconcile

If an operation changes meaning, give it a meaningful verb.

State and transition checks

Review whether the language makes it obvious:

• which states exist
• what transitions are allowed
• which transitions are irreversible
• which conditions authorize the transition

Bad state language often hides behavior inside generic mutation.

Constraint checks

Treat business rules as part of the language, not implementation detail.

Look for:

• exclusivity rules
• temporal rules
• quantity limits
• authorization conditions
• consistency conditions

If a constraint is important to correctness, the domain language should help people talk about it directly.

Language smells

Technical leakage

The domain is being described in terms of DTOs, endpoints, tables, or framework artifacts.

Semantic compression

Several different ideas are being folded into one convenient word.

Hidden transition

State changes are happening, but the language has no explicit way to describe them.

Workflow-shaped vocabulary

Terms describe a process implementation rather than the business meaning of the step.

Generic action wording

The language names mechanics instead of intent.

Deep checks

Use this section when the initial review suggests that the domain vocabulary is too vague to support stable design decisions.

What to probe further

• whether state and operation words are being mixed together
• whether important constraints are invisible in the available vocabulary
• whether several business distinctions are being compressed into one convenient term
• whether technical artifacts are silently shaping the language of the domain

Strong warning signs

• many core verbs are generic and transport-like
• one status word carries timing, authorization, and validity at once
• teams can describe the flow but not the actual domain transitions
• the implementation can violate a business rule without the vocabulary making it obvious

Review prompts

• Which business distinction disappears if this term stays vague?
• What operation name would make the domain effect explicit?
• Which rule matters but currently has no clean language?
• What state transition is happening without being named?

Consistency checks

After proposing improved terms, verify that:

• the same term means the same thing inside one context
• different meanings are not forced under one shared label
• state names and operation names fit together
• constraints do not contradict the wording
• documentation, diagrams, and code can use the same core vocabulary

Recommendation rules

• Split terms when one word is hiding several meanings.
• Rename operations when the current verb hides business effect.
• Make states explicit when mutation currently conceals transitions.
• Keep technical labels out of the core domain vocabulary unless the technology is itself part of the domain.
• Prefer a smaller precise vocabulary over a larger vague one.

Output shape

Structure findings around:

• important terms and what is wrong with them
• missing distinctions that need names
• operations whose wording hides behavior
• states or constraints that should be made explicit

Acceptance checks

A strong review from this reference should:

• identify the domain concepts that matter
• expose hidden semantic distinctions
• improve how operations and states are described
• reduce technical leakage in domain wording
• make constraints easier to express and discuss

Maintainability Review

Purpose

Review how a design or code change affects future changeability, readability, and testability.

When to use

Use this reference primarily as a supporting lens when maintenance cost could change the overall design recommendation. Use it as a primary lens only when the task is explicitly about maintainability rather than architecture.

Primary questions

• Will future changes be local and understandable?
• Is the structure easier for another engineer to modify safely?
• Are side effects, boundaries, and responsibilities easier to see?
• Does the design improve or reduce testability?

Review procedure

1. Check how change would land in the new structure. 2. Review readability and consistency of abstraction. 3. Review side effects, dependencies, and test seams. 4. Identify maintenance costs introduced by the change. 5. State whether the maintainability impact should alter the broader recommendation.

Output cues

Produce a review that focuses on future maintenance cost, boundary clarity, and testability rather than formatting or personal style.

Review stance

This reference is about change cost, not correctness and not code style.

Ignore:

• formatting preferences
• language-war debates
• micro-optimizations without evidence
• purely personal conventions

Changeability checks

Look for:

• clear responsibility boundaries
• small and predictable edit surfaces
• minimal speculative abstraction
• stable APIs and constructors
• validation in consistent places

Worry when:

• one change will require edits in several unrelated places
• abstractions were added before repeated need exists
• responsibilities blur across layers

Readability checks

Look for:

• names that explain intent
• consistent abstraction level
• code that reveals its side effects
• explicit domain concepts

Worry when:

• one unit mixes several ideas
• names hide behavior
• generic wrappers conceal the important logic

Testability checks

Look for:

• replaceable dependencies
• isolated side effects
• predictable behavior
• clear seams for unit and integration testing

Worry when:

• the only way to validate behavior is through broad end-to-end flows
• invalid states can be assembled freely
• important logic is inseparable from infrastructure

Common maintenance traps

Premature abstraction

Indirection exists before repeated need.

Boundary leakage

Too much domain or infrastructure knowledge crosses layer boundaries.

Hidden side effects

The code does more than the structure admits.

Test-hostile structure

Important logic cannot be exercised without broad integration setup.

Deep checks

Use this section when the initial review suggests that future edits may be more expensive than the code currently appears.

What to probe further

• whether one likely follow-up change would touch several unrelated layers
• whether abstractions are hiding the real policy or real side effects
• whether tests can validate important behavior without broad environment setup
• whether readability problems are actually symptoms of responsibility confusion

Strong warning signs

• a small behavior change requires editing constructors, mappers, services, and tests together
• helper layers exist mainly to avoid naming the real responsibility
• side effects are easy to trigger but hard to notice from the structure
• the safest test is still an expensive end-to-end flow

Review prompts

• Where would the next likely edit land?
• Which unit is carrying more than one responsibility?
• What side effect is not obvious from the interface?
• What test seam is missing that would make this change safer next time?

Recommendation rules

• Collapse abstraction that does not yet earn its cost.
• Clarify responsibility when one unit is doing several jobs.
• Move side effects toward clearer boundaries.
• Prefer smaller honest structures over generic ones with unclear payoff.

Output shape

Structure findings around:

• the maintenance cost being introduced or removed
• where future edits will concentrate or scatter
• how readability or testability is affected
• whether this should change the larger design judgment

Acceptance checks

A strong review from this reference should:

• explain how future changes would land
• identify readability or boundary problems that matter
• evaluate testability as part of maintainability
• avoid collapsing into style-only commentary

Non-Functional Budget Governance

Purpose

Review whether a design fits explicit budgets for performance, capacity, reliability, and cost.

When to use

Use this reference when a proposal may be constrained by latency, throughput, concurrency, storage growth, compute cost, external API volume, or operational headroom.

Primary questions

• Which non-functional budget actually governs this decision?
• What load shape and growth assumptions matter?
• Where are the multiplicative cost or scale risks?
• What evidence is needed before claiming the design is safe?

Review procedure

1. Define the budget that matters. 2. Build a realistic load and growth model. 3. Identify the strongest budget breakers. 4. Review scaling, storage, cost, and operability consequences. 5. State what validation or redesign is required.

Output cues

Produce a review that names the dominant budget, the main assumptions, the biggest constraint risks, and the minimum validation needed for confidence.

Review stance

Treat non-functional requirements as design constraints, not later tuning tasks.

Be suspicious of:

• "it should scale"
• "we can optimize later"
• "cloud infrastructure will absorb it"

Budget framing checks

Define:

• critical user journeys
• critical workloads
• time horizon
• environments
• latency targets
• throughput or concurrency expectations
• storage or cost ceilings

Vague adjectives are not budgets.

Load model checks

Review:

• average load
• peak load
• burst behavior
• fan-out
• retries
• payload size
• retention and growth

Ranges are acceptable. Unnamed assumptions are not.

Budget breaker checks

Look for multiplicative risk in:

• repeated network calls
• joins and scans
• cache-miss-heavy paths
• queue backlogs
• large object movement
• repeated serialization
• lock contention
• hot partitions

Operability checks

Ask:

• how will budget violation be detected?
• what saturates first?
• what degrades under pressure?
• what recovery path exists?

A design that fits only in the happy path is not within budget.

Common non-functional traps

Adjective-based design

The proposal uses words like "fast" or "small-scale" instead of real limits.

Hidden multiplier

The design ignores fan-out, retries, bursts, or growth compounding.

Cost blind spot

The proposal can work technically, but no one has named the compute, storage, or external dependency bill.

Operability gap

The design cannot show when it is approaching failure.

Deep checks

Use this section when the initial review suggests that the proposal is relying on rough intuition instead of a credible budget model.

What to probe further

• whether the load model ignores burst behavior, retries, or fan-out
• whether cost is acceptable only under average traffic, not peak conditions
• whether the first saturation point is known
• whether observability exists for the specific budget that matters

Strong warning signs

• req/s is named, but burst duration or payload growth is not
• latency is discussed without downstream dependency behavior
• scaling claims assume cache hit rates or concurrency patterns with no evidence
• the design can fail slowly and expensively before anyone notices

Review prompts

• What is the strongest hidden multiplier in this path?
• What assumption would most damage the budget if it is wrong?
• What saturates first under peak load?
• How will the team know the design is approaching its limit?

Recommendation rules

• Define the budget before debating architecture shape.
• Narrow the design when the load model is still fiction.
• Add measurement or pressure testing before claiming budget fit.
• Simplify where performance complexity exists without a real budget need.
• Redesign where the dominant budget is being violated by structure, not implementation detail.

Output shape

Structure findings around:

• dominant budget
• key assumptions
• strongest budget breakers
• required validation or redesign

Acceptance checks

A strong review from this reference should:

• identify the real budget constraint
• expose hidden multipliers
• separate facts from assumptions
• include operability in the judgment
• recommend validation when evidence is weak

Relationship Modeling Review

Purpose

Review whether relationships between concepts, entities, aggregates, and contexts express real business meaning, clear ownership, and sustainable consistency boundaries.

When to use

Use this reference when the main issue is how concepts should relate, who owns consistency, where lifecycle dependency exists, or whether a modeled relationship is accidental rather than meaningful.

Primary questions

• Why does this relationship exist in business terms?
• Which side owns the invariant or pays the consistency cost?
• Does the relationship imply containment, coordination, reference, or merely lookup?
• Is navigation required, or is it being introduced for convenience?

Review procedure

1. Identify the meaningful concepts before connecting them. 2. Explain what each proposed relationship means. 3. Evaluate ownership, lifecycle dependency, and consistency implications. 4. Check whether navigation and containment are truly required. 5. Recommend the lightest relationship model that preserves business meaning.

Output cues

Produce a review that explains what each important relationship means, what boundary cost it creates, and what relationship shape best fits the domain.

Review stance

Do not start from:

• tables
• foreign keys
• screen navigation
• ORM convenience
• reporting shortcuts

Start from business meaning, then decide what structure is deserved.

Concept-first check

Before judging relationships, confirm that the underlying concepts are independently meaningful.

Weak relationship modeling often begins by connecting poorly understood concepts too early.

Ask:

• what exists on its own?
• what changes on its own?
• what has its own lifecycle?
• what is only meaningful through another concept?

Meaning check

For each relationship, state:

• what it means
• why it exists
• what rule or coordination need it reflects

If that cannot be explained without implementation language, the relationship may be accidental.

Ownership and lifecycle checks

Test:

• which side defines the invariant
• whether one side can exist without the other
• whether one side creates, retires, or governs the other
• whether the relation is stable or frequently changing

Ownership is about responsibility for correctness, not just where a pointer lives.

Consistency checks

Ask:

• must both sides update atomically?
• can the relationship be eventually consistent?
• is this relation inside one aggregate or across a boundary?
• who pays the coordination cost if the relation changes?

Do not turn every business association into one consistency boundary.

Navigation checks

Navigation is not free.

Ask:

• who genuinely needs traversal?
• is the traversal for business behavior or developer convenience?
• can identity or lookup be enough?

Many overgrown models come from assuming every relationship must be traversable in both directions.

Common modeling traps

Database-shaped relationship

The model copies storage structure instead of domain meaning.

Screen-driven relationship

The UI needs one combined view, so the domain model is forced to mirror the screen.

Ownership blur

The model relates two concepts but does not say who owns consistency.

Aggregate inflation

Concepts are pulled into the same boundary because they are related, not because they share invariants.

Reference as false containment

An external relationship is modeled as if one concept fully contains the other.

Bidirectional by default

Two-way navigation is introduced without a real need.

Deep checks

Use this section when the initial review suggests that related concepts are being connected too eagerly or at the wrong boundary.

What to probe further

• whether ownership and lifecycle are being inferred from storage rather than business meaning
• whether aggregate boundaries are absorbing coordination that could remain external
• whether navigation is being added for convenience instead of behavior
• whether one concept is falsely modeled as contained by another

Strong warning signs

• the model cannot explain who owns consistency
• many-to-many or bidirectional relationships appear before meaning is clarified
• the UI needs a combined view, so the domain model is forced to become a combined structure
• two concepts are grouped together mainly because they often appear on the same screen or request

Review prompts

• What invariant justifies this relationship shape?
• Could these concepts remain independent with reference or lookup?
• Who pays the consistency cost if the relationship changes?
• What relationship is being modeled here that the business itself does not describe?

Recommendation rules

• Keep relationships explicit only when they carry real business meaning.
• Use reference instead of containment when the concepts are independent.
• Keep ownership local to the side that protects the invariant.
• Avoid widening aggregate boundaries just because concepts collaborate.
• Prefer lookup or identifier relationships when full navigation adds cost without meaning.

Output shape

Structure findings around:

• the important relationship decisions
• what each relationship actually means
• ownership and lifecycle implications
• consistency consequences
• the recommended relationship shape

Acceptance checks

A strong review from this reference should:

• explain the meaning of the relationship in business terms
• identify who owns consistency
• distinguish containment from coordination
• avoid modeling convenience as domain truth
• recommend the smallest relationship shape that preserves meaning

Security / Authorization / Auditability Governance

Purpose

Review whether a design respects security constraints, authorization boundaries, trust boundaries, and auditability requirements before those concerns become expensive to retrofit.

When to use

Use this reference when a proposal changes who can do what, crosses tenant or trust boundaries, handles sensitive data, introduces privileged workflows, or affects logging and incident investigation.

Primary questions

• What assets and actions need protection?
• Where does trust change, and where must enforcement happen?
• What authorization, revocation, and audit behavior is required?
• Which hidden trust assumptions make the design unsafe?

Review procedure

1. Identify protected assets and high-impact actions. 2. Map trust boundaries and enforcement points. 3. Review authorization rules, revocation behavior, and sensitive data exposure. 4. Review auditability, failure behavior, and abuse paths. 5. State the design corrections required to satisfy the security constraints.

Output cues

Produce a review that names the violated constraint, the missing enforcement or traceability behavior, and the design correction needed.

Review stance

Do not reduce security review to checklist theater.

The important question is not "did we mention auth?" It is:

• where is trust being assumed?
• who can really do what?
• what cannot be reconstructed after the fact?

Protected-asset checks

Identify:

• sensitive data
• privileged actions
• irreversible operations
• tenant-crossing behavior
• regulated or high-trust workflows

If the design cannot name what must be protected, it is not ready for serious review.

Trust-boundary checks

Look for boundary changes such as:

• browser to backend
• public API to internal service
• one service to another
• tenant to tenant
• admin to user scope
• automation to privileged system behavior

Security problems often live at the place where trust silently changes.

Authorization checks

Ask:

• what rule decides permission?
• where is that rule enforced?
• can object-level access be bypassed?
• how is access revoked?

Hidden UI is not authorization. Internal network placement is not authorization.

Auditability checks

Review whether the system can reconstruct:

• who acted
• what changed
• when it happened
• why it happened
• whether the audit trail itself can be trusted

If the system cannot explain sensitive behavior, the design is incomplete.

Common security design traps

Frontend-only enforcement

The UI is doing more trust work than the server boundary.

Implicit internal trust

"Internal" is treated as equivalent to "safe."

Missing object-level authorization

The user can access a class of resource, but the design never checks whether they may access this resource.

Audit afterthought

Mutation is modeled, but traceability is bolted on later.

Revocation blind spot

The design can grant access but has no strong model for removing it.

Deep checks

Use this section when the initial review suggests that the design mentions security but may still be trusting the wrong boundary or missing failure cases.

What to probe further

• whether object-level authorization is explicit or merely assumed
• whether "internal" systems are being trusted without real enforcement
• whether revocation, suspension, or emergency access removal has a concrete path
• whether the audit trail can survive failure, tampering, or delayed ingestion

Strong warning signs

• the UI hides an action, so the team treats it as protected
• one service validates access but downstream services assume the result forever
• privileged actions are audited only after success, not around the full attempt
• tenant boundaries rely on conventions rather than enforceable checks

Review prompts

• Where does trust actually change in this flow?
• What action can the wrong actor still perform if one assumption breaks?
• How is access removed, not just granted?
• What important event would be hard to reconstruct after the fact?

Recommendation rules

• Move security-relevant checks to trusted boundaries.
• Make object-level authorization explicit when resource ownership matters.
• Add auditability as part of the design contract, not a logging afterthought.
• Treat revocation and failure behavior as core design requirements.
• Reject convenience when it violates a named security constraint.

Output shape

Structure findings around:

• protected assets and trust boundaries
• missing or weak enforcement points
• auditability or revocation gaps
• the required design corrections

Acceptance checks

A strong review from this reference should:

• identify protected assets and trust boundaries
• make authorization rules and enforcement points explicit
• include auditability and revocation in the judgment
• find hidden trust assumptions
• recommend concrete security design corrections

Software Coupling Review

Purpose

Review how tightly modules, services, schemas, events, and teams are tied together, and whether that coupling creates durable leverage or recurring change pain.

When to use

Use this reference when the main issue is boundary quality, synchronized change, shared schemas, multi-service friction, or uncertainty about whether a split or merge will improve the design.

Primary questions

• Which dependencies are expensive because they are strong, distant, or unstable?
• Where is semantic coupling hidden behind apparently clean interfaces?
• Which boundaries reduce coordination cost, and which ones merely move it around?
• Is the design concentrating change locally, or forcing change choreography across components?

Review procedure

1. Map the relevant boundaries. 2. Identify where semantics, runtime behavior, and operations are shared. 3. Separate healthy local coupling from painful distributed coupling. 4. Find the boundary stress points that drive synchronized change. 5. Recommend whether to merge, split, translate, or narrow the contract.

Output cues

Produce a review that identifies change-friction hotspots, explains why they are painful, and recommends boundary adjustments in terms of coordination cost.

Review stance

Do not treat all coupling as bad.

Strong coupling can be acceptable when it is:

• local
• conceptually honest
• owned by one team
• stable enough to change together

Coupling becomes expensive when dependency strength, distance, and volatility combine to force repeated coordination.

Boundary map

Start by locating:

• modules
• services
• databases
• event streams
• APIs
• shared libraries
• pipelines
• team ownership boundaries

The question is not "what connects?" but "what must change together?"

Coupling lenses

Review coupling through these lenses:

• semantic coupling
• runtime coupling
• development coupling
• operational coupling
• schema and contract coupling
• ownership coupling

Each lens can be mild or severe on its own. The painful cases are the ones that stack.

Semantic coupling checks

Look for shared concepts that appear identical across contexts but do not mean the same thing.

Signals:

• identical entity names across services
• shared enums with divergent business meaning
• one context forcing another to inherit its vocabulary
• downstream systems carrying attributes they do not truly need

Semantic coupling is often the most dangerous because it survives refactors and hides behind "clean" interfaces.

Runtime coupling checks

Look for dependencies that force components to behave as one runtime unit.

Signals:

• deep synchronous call chains
• startup ordering constraints
• cascading retries
• distributed transactions
• mandatory orchestration for common flows

Ask:

• can this component fail independently?
• can it degrade independently?
• can it recover without the other side?

Development coupling checks

Look for dependencies that force code change and release coordination.

Signals:

• simultaneous PRs across repositories
• lockstep schema changes
• shared DTO churn
• multi-team release sequencing
• shared CI or version upgrade bottlenecks

If one small domain change routinely needs several teams, the boundary is probably underperforming.

Operational coupling checks

Look for dependencies that tie scaling, availability, or operability together.

Signals:

• shared databases
• shared queues or caches
• shared failure domains
• assumptions that every service has the same observability
• one component's load profile dictating another's behavior

Operational coupling matters even when code ownership looks clean.

Boundary stress patterns

Shared storage as hidden coordination

The design appears decoupled in code, but coordination happens through tables, columns, caches, or files.

Contract drift without translation

Multiple contexts rely on the same shape while needing different meanings over time.

Distance without independence

The system is physically split, but still changes as if it were one module.

Transport-shaped design

Domain boundaries are being chosen to fit an API, DTO, or broker contract rather than the actual concepts.

Local split, global pain

A decomposition reduces local complexity but increases cross-boundary negotiation every time the domain changes.

What good coupling looks like

Prefer designs where:

• the strongest coupling stays close to the concept that changes
• shared meaning is minimized across distant boundaries
• translation happens at context edges
• failure domains are isolated
• team ownership lines match technical responsibility

Deep checks

Use this section when the initial review suggests that the boundary story is cleaner than the actual change behavior.

What to probe further

• whether the same business change repeatedly lands in several repos or services
• whether shared terms hide different semantics across contexts
• whether deployment independence is real or only nominal
• whether a proposed split reduces ownership clarity while claiming architectural purity

Strong warning signs

• the same concept requires synchronized PRs in several places
• contracts are stable syntactically but unstable semantically
• translation is avoided because teams want "one shared model"
• a design calls itself decoupled while operations still fail as one unit

Review prompts

• What must change together when this domain rule changes?
• Which dependency is cheapest locally but most expensive at distance?
• What boundary exists only on paper?
• Would merging these responsibilities reduce total coordination cost?

Recommendation rules

• Merge components when they always change together for the same business reason.
• Split components when shared deployment or ownership is masking truly different change pressures.
• Add translation layers when the same words are carrying different meanings across contexts.
• Narrow contracts when downstream consumers are inheriting upstream detail they do not need.
• Prefer local complexity over distributed coordination when the same team owns both sides.

Output shape

Structure findings around:

• key boundary stress points
• the type of coupling involved
• why the current shape creates coordination cost
• what change becomes easier after the recommendation

Acceptance checks

A strong review from this reference should:

• identify where change is forced to synchronize
• distinguish semantic, runtime, development, and operational coupling
• avoid treating all coupling as equally harmful
• explain whether the current boundary is helping or hurting
• recommend a concrete boundary move, not just "reduce coupling"

Ubiquitous Language & Naming Review

Purpose

Review whether the language used across code, docs, diagrams, and discussion expresses domain concepts honestly, consistently, and at the right level of abstraction.

When to use

Use this reference when the main issue is overloaded vocabulary, misleading terms, inconsistent naming across contexts, or implementation-shaped words that obscure real domain meaning.

Primary questions

• Which important concepts do not yet have stable names?
• Which current terms imply the wrong behavior or scope?
• Which words are carrying multiple meanings across contexts?
• Which names are technical artifacts rather than domain language?

Review procedure

1. Identify the bounded context and audience for the language. 2. Extract the important concepts, states, operations, and constraints. 3. Classify naming problems by missing, misleading, overloaded, or implementation-shaped terms. 4. Propose narrower, more honest replacements. 5. Check whether the new wording works consistently across code, docs, diagrams, and conversation.

Output cues

Produce a review that explains what is wrong with the current wording, what better language should replace it, and which boundaries that wording protects.

Review stance

Good naming is not decoration.

Names should help a reader answer:

• what exists here?
• what can happen?
• what distinguishes this concept from nearby ones?
• what should stay true?

Do not optimize for polish alone. Optimize for honest understanding.

Naming problem types

Missing term

A concept exists in behavior or rules, but no explicit name exists for it.

Signals:

• repeated logic with no shared label
• a long function or paragraph hiding a reusable concept
• multiple parameters always traveling together

Misleading term

A word suggests a meaning or behavior that is not actually true.

Signals:

• a method name promises one thing and does another
• a type sounds domain-level but is really technical
• a status name hides lifecycle timing or side effects

Overloaded term

One word is doing too much.

Signals:

• the same label means different things in different places
• a cross-context concept is being forced under one shared name
• discussions require repeated verbal clarification

Implementation-shaped term

The word describes how the system is built rather than what the concept means.

Signals:

• storage-driven names
• transport-driven names
• framework lifecycle names used as domain vocabulary

Rewrite strategy

When fixing a name:

1. decide what concept is actually being named 2. remove false implications 3. add the distinction that matters 4. check whether the new term still works in natural team conversation

Prefer names that are:

• honest
• specific enough to distinguish nearby concepts
• stable across implementation changes
• natural inside the bounded context

Context discipline

The same term does not need to mean the same thing everywhere.

Allow different contexts to use different words when:

• they protect different invariants
• they care about different attributes
• they operate at different abstraction levels

Unifying vocabulary across contexts is only good when the meaning is genuinely shared.

Common naming traps

Vocabulary drift

The same concept slowly acquires different names in code, docs, and discussions.

Premature elegance

The wording sounds polished but hides important behavior or limits.

Technical masquerade

A transport or storage term is treated as if it were the real domain concept.

Scope inflation

A broad label absorbs several smaller concepts because splitting them feels inconvenient.

Deep checks

Use this section when the initial review suggests that naming problems are causing model drift or review confusion.

What to probe further

• whether the same term changes meaning between code, docs, and conversation
• whether multiple concepts are being hidden behind a polished but overly broad label
• whether technical names are defining the domain by accident
• whether context differences are being flattened in the name of consistency

Strong warning signs

• reviewers repeatedly need verbal explanation for the same term
• one name is doing the work of concept, state, and workflow stage at the same time
• a rename sounds cleaner but still does not reveal the behavior
• the team shares one word across contexts because splitting it feels socially awkward

Review prompts

• What misunderstanding does this term invite?
• Which distinct concept deserves its own name?
• Does this word belong to the domain or to the implementation?
• Where should the same label stop being reused?

Recommendation rules

• Add names for concepts that are already present in behavior.
• Split terms that carry more than one business meaning.
• Rename terms that imply false behavior or scope.
• Keep technical implementation labels out of the core domain language unless the technology is itself the domain.
• Prefer context-qualified names over one misleading universal term.

Output shape

Structure findings around:

• current term
• naming problem type
• recommended term
• why the change improves understanding
• where the rename should apply

Acceptance checks

A strong review from this reference should:

• expose missing and overloaded concepts
• improve the honesty of the vocabulary
• reduce implementation-shaped naming
• preserve bounded-context distinctions
• produce naming recommendations people can actually use in conversation and code