Code review that reads your system

AI agents can produce convincing diffs quickly. The hard part for a team is deciding whether the change matches the intent and whether it is safe for the system it touches.

Here is a concrete example: an engineer asks an agent to update SSO callback handling for a new identity-provider response shape. The agent opens a clean-looking PR. The tests pass. The risky part is not syntax. It is whether the change accidentally changes session lifetime behavior.

Diff review asks whether the patch looks right. Production-aware review asks whether the patch matches intent and survives the system it touches.

1. Capture intent before code hardens

Before the PR exists, Spinal records what the developer and coding agent intend to build. For this change, the captured intent might look like this:

Goal: accept the new IdP callback payload and preserve existing login behavior.
Non-goal: do not change session lifetime, refresh behavior, or logout semantics.
Expected validation: active sessions remain valid for the existing 30-minute idle timeout.

This matters because reviewers should not have to infer product intent from the diff. The plan gives the later review a contract to check against.

2. Run a local review before push

The developer can run Spinal locally from the CLI before opening a PR. This pass does not need production access to be useful. It compares the branch against the captured intent, repo rules, and local diff.

In this example, local review flags a specific concern: the refactor moved timeout calculation from the session-refresh path to the callback path. That may turn an idle timeout into a fixed lifetime.

Local finding
Risk: session expiry may no longer refresh on activity.
Why: auth/session.ts now derives expires_at from issued_at during callback handling.
Intent conflict: captured non-goal says session lifetime must not change.

The developer now has a chance to fix the branch before the PR, or push with the risk explicitly carried forward.

3. Review the PR with broader context

When the PR opens, Spinal reviews again with more context: the full diff, captured intent, repo instructions, CI status, previous auth feedback, and source-control metadata.

The useful output is not a generic comment like “check auth edge cases.” It is a finding tied to the PR: this change appears to alter session timeout semantics, despite the stated non-goal.

4. Ground the risk in observability

Next, Spinal uses production signals to decide whether the suspected risk maps to real behavior. For this PR, useful evidence might include login traces, session-refresh logs, error rates around callback handling, and the SLO that defines acceptable login/session behavior.

Evidence pack
Trace sample: /auth/callback -> /session/refresh -> /me
Metric: auth_session_refresh_count by client_version
Log pattern: session.refresh.extend_expires_at
SLO: 99.9% of active sessions should not require re-auth within idle timeout

This is the difference between “the model thinks this is risky” and “the system shows this path matters, and here is the evidence.”

5. Generate a PR-specific validation

For risky changes, Spinal writes a focused validation test. The test is shaped by the PR and by production evidence, not by a generic checklist.

Validation scenario
1. Create a session through the new callback payload.
2. Simulate activity at minute 20 using the observed refresh path.
3. Assert expires_at extends to preserve the 30-minute idle timeout.
4. Assert no forced re-auth occurs before the expected idle window.

The validation can run in the customer CI/CD pipeline or in a dedicated sandbox. Either way, the result feeds back into the review agent.

6. Return a final review signal

The developer should not get a vague final answer. They should get a merge-relevant signal:

Final review
Status: needs changes
Finding: session idle timeout changed from sliding to fixed.
Evidence: validation reproduced early re-auth at minute 30 after activity at minute 20.
Suggested fix: keep callback payload parsing separate from session refresh semantics.
Saved memory: auth callback changes must preserve refresh-based expiry extension.

If the validation passes, the signal changes: risk rejected, evidence attached, merge confidence higher. The point is that the final review is backed by execution and production context.

What a reader should take away

Production-aware code review is not “an LLM comments on a PR.” It is a loop: capture intent, review locally, review at PR time, pull production evidence, validate the risky part, and preserve the result as memory.

That loop matters more as agents write more code. The faster teams create diffs, the more they need a durable way to prove that a change is intentional, correct, and safe to merge.