Backend Review

Backend Review

Make new complexity prove its necessity. Review production behavior and ownership boundaries rather than maximizing the number of findings.

Operating contract

• Problem: backend review often produces generic risk lists or defensive complexity without proving the real caller, owner, contract, writer, or side-effect boundary.
• Use when: the user requests backend review or a change touches the high-risk production surfaces named in the description.
• Do not use when: the work is mechanical, documentation-only, or test-only without a production-path change.
• Produce: a mode-appropriate decision with admitted findings, ablation of new concepts, targeted verification, and the first meaningful unresolved risk.

Modes

• quick: inspect a concrete diff for unnecessary complexity and the smallest safe implementation. Stay read-only.
• plan: review an implementation plan before editing. Read references/plan-review.md.
• deep: review a completed or nearly completed diff using independent lenses. Read references/deep-review.md.
• No explicit mode: during an authorized high-risk implementation, apply only the compact gate below. Do not silently start a multi-agent review.

Review is read-only unless the user explicitly asks to fix or apply findings. Commit, push, PR publication, external messages, and production changes always require separate authorization.

Resolve the review target

Before judging the work, establish:

• repository, base, head, staged and unstaged changes;
• requested behavior and acceptance criteria;
• applicable repository instructions and public contracts;
• the current owner, valid callers, sibling writers, and direct consumers;
• verification already performed and the first meaningful unverified surface.

Ask one concise question only when an undiscoverable decision would materially change correctness, ownership, public behavior, or risk.

Compact gate

Before implementation

Fix these six facts internally:

1. acceptance criterion;
2. existing owner and canonical path;
3. allowed files and public surfaces;
4. out-of-scope work;
5. acceptable residual risk;
6. a complexity budget for new branches, helpers, types, settings, and flags.

Search the repository before claiming that a pattern, helper, owner, or invariant exists.

After implementation

1. Inspect the complete branch diff from the real merge base, including staged, unstaged, and relevant untracked files.

2. For Python changes, run scripts/complexity_inventory.py --base <ref>. Treat its output as candidates, never as findings.

3. Apply this ablation question to every new concept:

   If this code is removed, do the acceptance criteria, repository requirements, invariants, public contracts, valid production paths, and side effects remain unchanged?

4. Classify each candidate:

   • keep: required by an acceptance criterion, invariant, trust boundary, or reproduced failure;
   • narrow: the problem is real but belongs in a smaller owner, type, or call site;
   • remove: deletion is behaviorally neutral or the branch is speculative;
   • blocked: a material product or contract decision is missing.

5. Remove or narrow accepted candidates only when the user authorized changes, then rerun targeted verification.

6. Cold-read the final diff. Do not report completion while a validated blocking issue or unresolved public-behavior decision remains.

Conditional review surfaces

Open only the references needed by the diff:

• ORM, evaluation, query shape, state writers, or migrations: references/django-orm-review.md
• API, permission, transaction, side effects, or migration risk: references/risk-gates.md
• aggregate authority, snapshots, ledgers, or model boundaries: references/domain-model-review.md

Finding admission

Admit a finding only when it contains:

• the concrete location and production entry path;
• repository, contract, data, test, or runtime evidence;
• likelihood, reach, and impact;
• whether the current change creates or worsens the problem;
• the smallest safe action.

Classify evidence as one of:

• observed-production;
• normal-path-reproduced;
• code-proven-required-invariant;
• crafted-only;
• hypothetical.

Report only:

• P1/P2 fix-required: a consequential defect introduced or worsened by the current change;
• decision-required: a product or public-contract choice blocks a correct judgment;
• measure: realistic measurement would materially change a performance decision.

Do not surface P3 style preferences, generic hardening, impossible mocks, or speculative edge cases unless the user explicitly asks for every observation.

Output

For quick and the automatic compact gate, use:

Verdict: CLEAN | TRIM | BLOCKED
Scope: <base, head, working tree, and intended outcome>
Findings: <location, evidence, and smallest action, or none>
Ablation: <removed concepts and retained complexity with reasons>
Verification: <performed checks and meaningful gaps>

Use the output contracts in the plan and deep references for those modes. Keep the final answer decision-oriented and omit internal candidate inventories.