Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Decision file format

One YAML file per decision, decisions/D-0001.yml, reviewed like code:

id: D-0001
decision: Billing code calls the payments client, never raw fetch.
reason: the client adds idempotency keys
rejected:
- a shared fetch wrapper per module
scope:
- src/billing/**          # path globs, or symbol / module names like `apiClient`
category: convention      # convention | constraint | api_change | architecture | scope
status: accepted          # accepted | superseded (proposals live in decisions/pending/)
checks:                   # optional; without checks a decision is shown, not enforced
  forbid_imports: [axios]
  forbid_deps: [redis]    # package.json, pyproject.toml, requirements*.txt, Cargo.toml, go.mod
  forbid_patterns:
  - language: TypeScript
    pattern: fetch($$$A)  # ast-grep pattern
sources:
- https://github.com/acme/app/pull/214
FieldMeaning
idD-NNNN once accepted; proposals in decisions/pending/ use P-… ids
decisionThe rule, as one sentence
reasonWhy; shown to the agent next to the decision
rejectedAlternatives considered and turned down
scopePath globs, or symbol / module names. No scope, or **, is repo-wide
categoryconvention, constraint, api_change, architecture or scope
statusaccepted or superseded
checksOptional. Without checks a decision is shown, not enforced
sourcesWhere the decision came from (PRs, docs, commits)

Agents never edit these files. They propose with ingrain decisions add --propose or ingrain decisions supersede, and a person accepts with ingrain decisions review.