# Principles

pr-shepherd is opinionated on purpose. Each principle below is a constraint the codebase
actually enforces — not aspirational language. Where that's checkable from the outside
(a decision table, a finite trigger list, a fixed exit-code map), the page says so.

<div class="card-grid">

- [**Full context over streaming**](/pr-shepherd/principles/full-context-over-streaming/) — one
  batched poll replaces a tool-call fan-out, and beats CI-only waiters that hide review
  comments until checks finish.
- [**Deterministic orchestration, agentic judgment**](/pr-shepherd/principles/deterministic-over-agentic/)
  — a split, not a hierarchy. Shepherd decides the next state; the agent decides what to
  change.
- [**Surface data, don't classify it**](/pr-shepherd/principles/surface-data-dont-classify/) — ship raw
  fields, not a one-liner enum over them, whenever the agent would otherwise re-fetch the
  same thing.
- [**Never mutate git**](/pr-shepherd/principles/never-mutate-git/) — Shepherd emits commands; the
  calling agent runs them, because it already owns the git lifecycle.
- [**Every item surfaces at least once**](/pr-shepherd/principles/every-item-surfaces-once/) — outdated,
  resolved, and minimized review items are never silently dropped.
- [**A portable state machine, not a hosted agent**](/pr-shepherd/principles/portable-not-hosted/) — the
  same action model over CLI, MCP, and the programmatic API, with no durable state that
  can't be deleted.

</div>


## Canonical spec

- [Architecture — design rationale](https://github.com/jonathanong/pr-shepherd/blob/main/docs/architecture.md)
- [CLAUDE.md — contributor-facing principles](https://github.com/jonathanong/pr-shepherd/blob/main/CLAUDE.md)