Skip to content
SHRINESHRINE

Reviewable Output

Ratified

Review cost is set by the shape of the output, not only by its quality.

The Pattern

Section titled “The Pattern”
  • Ask for output in a shape that is cheap to review
  • Machines check syntax, style, and tests first; the human reviews intent and design
  • Large work arrives in stages, each a smaller review than the whole

When to Use

Section titled “When to Use”
  • Delegation fits, but review of the result is the slow step
  • Diffs that touch several concerns at once
  • Changes a reviewer must read against a repo convention

When Not to Use

Section titled “When Not to Use”
  • One-line or throwaway changes
  • Exploration spikes that will be discarded
  • Output a deterministic check fully covers, with no design decision in it

Shape

Section titled “Shape”
  • Small diffs: one concern each (Delegation Fit)
  • Evidence attached: the command run and its output, not a claim of success (Verification Loops)
  • Review note: decisions made, deviations from the brief, places it was unsure
  • Known pattern: name the existing code it mirrors, so review is a diff against a known shape (Consistency as Leverage)

Staged Checkpoints

Section titled “Staged Checkpoints”
  • Approve the plan, then the interface or schema, then the implementation
  • Each stage is a smaller review than the whole
  • A rejected plan costs minutes; a rejected implementation costs the run
  • Plan stage: Spec, Then Build
  • Each stage presented as a Decision Card

Review Order

Section titled “Review Order”
  1. Deterministic checks: compile, lint, typecheck, tests
  2. Machine review against the brief (Adversarial Review)
  3. Human review of intent and design

Worked Example

Section titled “Worked Example”
  • Illustrative case (composite, not a transcript)
  • Change: move session storage from in-process memory to the shared cache

Delivered as one diff

  • 31 files: interface change, two backends, config, call-site updates, tests
  • No note; the reviewer reads every file to find the design decisions

Delivered staged

  1. Plan: three bullets and one open question (TTL on logout); approved with one change
  2. Interface: one file, the new SessionStore contract; approved as is
  3. Implementation: the rest, with test output and a review note
    • Decision: sessions written through, read from cache first
    • Deviation: kept the in-process store for tests, not removed as briefed
    • Unsure: eviction behavior under memory pressure
  • The reviewer reads the note, checks the one deviation, and spends the time on the eviction question

Anti-patterns

Section titled “Anti-patterns”
  • One diff that mixes a refactor with a behavior change
  • “Tests pass” with no command or output
  • Human review spent on formatting that a linter owns
  • Reviewing the implementation before anyone approved the plan
Section titled “Related”