decision-ledger — the gate and ledger at accept moments

North star: an accepted decision means the acceptor understood its core content and is ready to be accountable for it. Today "Approve" and "yes" are clicks, not evidence of understanding — the understand-step happens invisibly, or not at all. This skill makes that step explicit, structured, and recorded.

The core behavior, defined once, independent of surface:

only just before a decision takes effect          ← rare and selective (final gates)
  1) put the decider in front of the evidence     ← real diff · real comment · real target
  2) ask the premise, not the conclusion          ← "did you check what this rests on?"
  3) require a reason for risky transitions       ← missing → ask back and hold. never fabricate
  4) record the decision with its reason          ← who · what · why · on which evidence

Positioning: a comprehension-and-accountability layer, not a reviewer. It generates zero review comments and needs zero cooperation from review tools — it consumes what already exists. Cross-tool protocol adoption is explicitly NOT a goal. Related work: CFF (Buçinca 2021) for the gate; ADR for the record; SARIF is adjacent (finding interchange — may someday be consumed, never reinvented).

Configuration — output language

• OUTPUT_LANG: en <!-- render human-facing gate/ledger text in this language; default: en -->

The machine record stays language-neutral (stable ids/enums). Only human-facing text is localized. Resolution: explicit request > OUTPUT_LANG > project CLAUDE.md language > en.

When it fires (selectivity — break this and the gate trains people to click through it)

Final gates only, never mid-work or per suggestion:

• Just before opening or merging a PR; just before a push.
• Just before an irreversible/outbound action the agent proposed (destructive command, mass edit, deploy).
• A final review the user declares ("final review", "최종 리뷰하자").
• Explicit request ("gate this", "결정 정리해줘").

When gated, state in one line which final gate triggered it.

Surfaces (one behavior, three accept moments)

Agent conversation — decisions made in session

"Let's open the PR", just before push, a risky command approval. Open the real target — which repo/branch receives what, the actual diff summary, what a command actually touches — never a summarized option card. Confirm the premise ("this is an X-kind action; did you check Y?"), collect reasons for risk-accepts, record, then proceed. Undecided ledger issues from the local and GitHub surfaces resurface here at the final moment.

Local final review — before a PR exists

Consume findings from local reviews (self-review, fresh-eye, cross-model), run the same gate, store the ledger as .decisions/<branch>.yaml (slashes in branch names sanitized to -), same record format. A local ledger can later be pushed into a PR body unchanged.

GitHub PR — the gh wrapper

Consume every review comment (inline + top-level; humans are first-class sources):

gh api repos/<owner>/<repo>/pulls/<n>/comments --paginate --jq '.[] | {id, user: .user.login, path, line, body}'
gh api repos/<owner>/<repo>/issues/<n>/comments --paginate --jq '.[] | {id, user: .user.login, body}'

Cluster duplicates across reviewers into one issue each (Codex #12 + CodeRabbit #8 → one issue), keep deep links to every source comment as evidence. Gate, then persist to the PR body via gh pr edit <n> --body-file — see store format below.

Planned (v0.2, post-MVP): a scribe GitHub Action for teammates without an agent session — records only decisions humans actually stated in plain PR comments, asks back when a reason is missing; never produces/completes/upgrades a decision. Measured: review-comment checkbox events do NOT fire Actions → design as a reconcile loop (re-read all comments + ledger on any trigger, recompute idempotently), not an event chase.

Flow (local & GitHub surfaces)

1. Consume — gather findings from all reviewers (see surface sections).
2. Cluster — merge duplicate findings into issues; collect evidence[] pointers and sources[] (tool names or human:<login>).
3. Recommend + evidence — draft a suggested status + reason per issue; mark confidence honestly (high = traced/reproduced, speculative = pattern-matched only); surface speculative first. Do not decide.
4. Gate — put the human in front of the evidence (the real diff and the real comment — on the PR screen, or the actual code shown locally; NEVER a detached summary picker), then capture the decision with minimal keystrokes: the human states it in natural language ("retry-002 accepted_risk: idempotent, internal") and the machinery writes the ledger. Friction belongs on judgment, never on data entry. Enforce: accepted_risk/dismissed require a reason — a bare "lgtm" is rejected with an ask-back; reasons are never fabricated.
5. Persist — machine-written, human-read. Idempotent: re-read the hidden JSON, update in place, never duplicate. Nobody hand-edits ledger markdown.

Decision Record (schema v0, emergent)

Minimal on purpose — grow it only when the skill actually needs a field.

{
  "id": "sec-001",
  "title": "retry() leaks token on 3rd attempt",
  "status": "unreviewed",
  "reason": "",
  "confidence": "speculative",
  "evidence": ["github://comment/3559386973", "local://fresh-eye-review#3"],
  "sources": ["codex", "coderabbit", "human:jihoon"],
  "decided_by": null,
  "recommendation": "needs_human"
}

status enum: unreviewed · requires_fix · accepted_risk · dismissed (false positive) · resolved (was requires_fix, now fixed). reason required for accepted_risk / dismissed.

Store format

PR surface: the PR body holds the human checklist + the machine record together (no second store to drift). Keep headings modest — a PR body has no page title, so #/## render huge; use ### + bold lines:

### Review Decisions <!-- decision-ledger -->

Decided **2/4** · `accepted_risk` / `dismissed` require a reason.

**retry-001 · retry() discards success/failure · `requires_fix` — decided by jihoon**
- [x] requires_fix — sources: Codex, CodeRabbit · evidence: [Codex](#discussion_r…) · [CodeRabbit](#discussion_r…)

**retry-004 · naming nit · `unreviewed` — bare "lgtm" rejected, reason requested**
- [ ] sources: human:jihoon · evidence: [comment](#issuecomment-…)

<!-- decision-ledger:data
[{"id":"retry-001","status":"requires_fix", …}]
-->

The checklist is the human view; the decision-ledger:data block is the source of truth other interfaces read. Local surface: the same data array in .decisions/<branch>.yaml. Conversation surface: decisions recorded into whichever ledger exists for the branch/PR (create the local one if none).

Boundaries (DO NOT)

• DO NOT generate review comments — consume only.
• DO NOT decide for the user, or set a status without shown reason + evidence.
• DO NOT fire outside final gates (mid-work, per-suggestion) — selectivity is the mechanism.
• DO NOT use generic "are you sure?" — always the concrete premise this decision rests on.
• DO NOT collect decisions through a summarized option list detached from the evidence.
• DO NOT fabricate or complete reasons; a bare "ok/lgtm" stays unreviewed with an ask-back.
• DO NOT dress up unverified findings as high confidence.
• DO NOT touch anything outside the ledger (PR-body section / .decisions/ file).
• DO NOT depend on review tools emitting structured output — parse existing comments.

Relationships

• Pairs with whatever produces the findings — AI reviewers (CodeRabbit, Codex, Claude), local review skills or subagents, or human notes. They review; this gates and records the decisions.
• The README in this repo is the user-facing overview; this file is the artifact a Claude Code session actually loads. If you already run a similar always-on gate of your own, retire or thin it when adopting this one — two gates firing on the same moment train click-through.