Skip to content

Find code by asking what it does. A CLI for coding agents that uses Jev to discover relevant files and source context.

skills: rename audit-choices to audit-decisions; the ledger is decisions.md

David Zhang9971e04061e4
diff --git a/.agents/skills/audit-choices/SKILL.md b/.agents/skills/audit-decisions/SKILL.md
similarity index 64%
rename from .agents/skills/audit-choices/SKILL.md
rename to .agents/skills/audit-decisions/SKILL.md
index 7730263..a4c27d6 100644
--- a/.agents/skills/audit-choices/SKILL.md
+++ b/.agents/skills/audit-decisions/SKILL.md
@@ -1,15 +1,15 @@
---
-name: audit-choices
-description: Audit the choices an implementing agent made, not its diff — a pure decision audit that traces the session's history into a choices ledger, changes no code, and never blocks an unsupervised run. Working code still embeds architecture the user never chose; surface it because future work inherits it. Use when the user wants to review the decisions the AI made on their behalf, before merging or committing AI-implemented work, when integrating a delegated subagent's pass, or when a fix "works" but might be a point fix.
+name: audit-decisions
+description: Audit the decisions an implementing agent made, not its diff — a pure audit that traces the session's history into a decisions ledger, changes no code, and never blocks an unsupervised run. Working code still embeds architecture the user never chose; surface it because future work inherits it. Use when the user wants to review the decisions the AI made on their behalf, before merging or committing AI-implemented work, when integrating a delegated subagent's pass, or when a fix "works" but might be a point fix.
---
-# Audit Choices
+# Audit Decisions
Given a good decision, an agent implements it faithfully; wherever the task is
underspecified, it makes the decision itself — silently, and the diff won't
flag it. Reviewing thousands of changed lines doesn't scale, and it inspects
the execution, which was probably fine. The audit that scales is of the
-**choices**: surface every decision the implementer made on its own, judge
+**decisions**: surface every one the implementer made on its own, judge
that list, and record the verdicts.
This is about architecture more than bugs. An implementation can work
@@ -18,14 +18,14 @@ storage location, a dependency, an API contract, a tradeoff of memory for
speed — and every one of them is load-bearing for future work. The user needs
to know them not because they're wrong, but because they now own them.
-This is purely a decision audit — it is not about modifying code, and it can
+This is purely an audit — it is not about modifying code, and it can
be called at any time. The job is to **trace back**: walk every step this
session has taken, and every step each subagent took (a live implementer
traces its own; otherwise reconstruct from its reports, transcripts, and
diffs), and surface every single decision that was made on the user's behalf
that was not in the original spec or prompt. The ledger of those decisions
replaces reading the code as the user's review surface — that is the whole
-point. Acting on the verdicts (redoing an unsound choice, applying a
+point. Acting on the verdicts (redoing an unsound decision, applying a
provisional call) belongs to the caller: the implementing workflow mid-run,
or the user after reading the report.
@@ -41,8 +41,8 @@ Two ways in, same audit:
## Workflow
1. **Elicit and trace back.** When an implementer reports done, ask: *"While
- working on this, which choices did you make that you're not confident of?
- List all."* — but treat the self-report as a starting point, not the
+ working on this, which decisions did you make that you're not confident
+ of? List all."* — but treat the self-report as a starting point, not the
boundary: agents under-report. Trace the history yourself — the session's
steps, subagent reports, diffs, commits — and collect every decision that
is in the work but not in the original spec or prompt. Sweep the
@@ -50,24 +50,25 @@ Two ways in, same audit:
formats, storage and naming schemes, API contracts and their error
behavior, dependencies added, concurrency/perf tradeoffs, scope
interpretations, patterns future code will imitate. Auditing your own
- session, trace your own steps the same way. Choices the plan explicitly
+ session, trace your own steps the same way. Decisions the plan explicitly
delegated to the implementer are discretion, not audit items.
-2. **Triage each choice on evidence.** Forced by the plan, or invented?
+2. **Triage each decision on evidence.** Forced by the plan, or invented?
Invented ones get the scrutiny: is this the general solution, or a fix
- shaped to the one failing case? Verdict per choice: **sound**, **unsound**,
- or **needs-user** — and alongside the verdict, a **confidence**: how sure
- the audit is that the user would have made this same call. Confidence is
- what ranks the report. Reserve needs-user for genuinely user-only calls
- (taste, product direction, external cost); every needs-user entry records a
- recommended provisional call that is reversible, so an unsupervised caller
- can proceed without waiting. The audit never stalls a run: each entry is a
- judgment handed over for action or review, not a question that halts.
+ shaped to the one failing case? Verdict per decision: **sound**,
+ **unsound**, or **needs-user** — and alongside the verdict, a
+ **confidence**: how sure the audit is that the user would have made this
+ same call. Confidence is what ranks the report. Reserve needs-user for
+ genuinely user-only calls (taste, product direction, external cost); every
+ needs-user entry records a recommended provisional call that is
+ reversible, so an unsupervised caller can proceed without waiting. The
+ audit never stalls a run: each entry is a judgment handed over for action
+ or review, not a question that halts.
3. **State the corrected decision, don't sketch a patch.** For each unsound
- choice, the entry names the decision the work should be redone from — the
- property that must hold in general — not an edit to layer on top. A patch
- on top of a bad decision preserves the decision; the redo itself is the
- caller's, after the ledger is reviewed.
-4. **Bank every choice in the ledger** (below), and promote load-bearing
+ decision, the entry names the corrected one the work should be redone from
+ — the property that must hold in general — not an edit to layer on top. A
+ patch on top of a bad decision preserves the decision; the redo itself is
+ the caller's, after the ledger is reviewed.
+4. **Bank every decision in the ledger** (below), and promote load-bearing
sound ones into the plan's handoff so later passes inherit them as givens
instead of re-deciding.
5. **Present the ledger: grouped by verdict, ranked by confidence.** The
@@ -75,9 +76,9 @@ Two ways in, same audit:
calling workflow mid-run, the user at run's end. Each verdict group maps
to an action — needs-user (decide, with the provisional calls), unsound
(redo, with the corrected decisions), sound (acknowledge: the
- architecture the user now owns) — and within each group choices are
+ architecture the user now owns) — and within each group decisions are
ranked by confidence, least confident first. When the ledger is long,
- open the report with the two or three least-confident choices overall,
+ open the report with the two or three least-confident decisions overall,
whatever their group: the "review these first" line. Sound is not
skippable. Only trivial discretion (internal naming, cosmetic calls)
compresses to a one-line count.
@@ -87,20 +88,20 @@ Two ways in, same audit:
[eli5](../eli5/SKILL.md) register — a concrete scenario walked end to
end (the triggering event, what the work does today, what the unbuilt
alternative would do), every term of art defined at first use, and
- pseudocode at the level of the decision when the choice is about control
- flow, ordering, or timing. "A gated ask is dropped, not deferred" is a
+ pseudocode at the level of the decision when it is about control flow,
+ ordering, or timing. "A gated ask is dropped, not deferred" is a
headline, not an entry. A compressed entry that makes the user ask
"explain this one" has failed; the ledger must stand alone without the
diff, the spec, or the transcript.
-## The Choices Ledger
+## The Decisions Ledger
-A dedicated file that outlives every pass: `choices.md` beside the plan
-(`specs/<feature>/choices.md` when a spec owns the work). One entry per
-audited choice:
+A dedicated file that outlives every pass: `decisions.md` beside the plan
+(`specs/<feature>/decisions.md` when a spec owns the work). One entry per
+audited decision:
- **When** — pass or commit it landed in.
-- **The choice** — a one-line headline, then the ELI5 scenario: the
+- **The decision** — a one-line headline, then the ELI5 scenario: the
triggering event, what the work does today, what the unbuilt alternative
would do, with terms of art defined in place.
- **The gap** — what the plan left unspecified that forced it.
@@ -114,11 +115,11 @@ audited choice:
Rules of the ledger:
-- Banked is settled: a choice already in the ledger (or promoted into the
+- Banked is settled: a decision already in the ledger (or promoted into the
plan) is a given for later passes — never re-listed, never re-decided.
- The ledger is a plan-quality signal. Entries clustering around one slice or
area mean the plan is foggy there — reslice or send that part back through
- the spec rather than triaging the same class of choice forever.
+ the spec rather than triaging the same class of decision forever.
- **ELI5 survives every rewrite.** The entry format above — headline plus the
walked scenario with terms defined in place — is the *storage* format, not
presentation polish. When entries are consolidated, merged, re-audited at
@@ -129,7 +130,7 @@ Rules of the ledger:
loads rows in mailbox order and rejects the list when a later reference
has an earlier createdAt" reads as settled, but only the walked version
(two sessions, per-session sequence numbers that can't be compared, the
- shared insert-timestamp clock) lets a reader actually judge the choice. A
+ shared insert-timestamp clock) lets a reader actually judge the decision. A
consolidation that drops scenarios has failed even if every fact survives —
and so has one that keeps the scenario but leans on labels the build
invented ("the retry envelope", "the evidence seam") without defining them
@@ -137,30 +138,30 @@ Rules of the ledger:
## Rules
-- **"It works" is not a verdict on the choice.** The recurring smell is the
+- **"It works" is not a verdict on the decision.** The recurring smell is the
coincidental fix: a resized buffer, bumped timeout, or special case whose
magnitude happens to cover the failing input while the underlying cause
stays dormant. Ask what property *guarantees* the fix in general; if the
- answer is "this case passes," the choice is unsound even though the code is
- green.
+ answer is "this case passes," the decision is unsound even though the code
+ is green.
- Declared success is the point of maximum risk — the implementer's confidence
- is highest exactly when its unexamined choices are about to be merged. Never
- skip the audit because the result looks clean.
+ is highest exactly when its unexamined decisions are about to be merged.
+ Never skip the audit because the result looks clean.
- An empty list on nontrivial work is a red flag, not a pass. Probe: what did
the task leave unspecified? Something filled those gaps.
-- The audit changes no code, tests, or build state. Finding an unsound choice
- is the deliverable, not a license to fix it — record the corrected decision
- and leave the tree exactly as audited, so the ledger and the tree agree on
- what the caller is deciding about. Evidence-gathering is fair game: read
- anything, run the existing tests, write transient probes — but remove every
- probe before handback.
+- The audit changes no code, tests, or build state. Finding an unsound
+ decision is the deliverable, not a license to fix it — record the corrected
+ decision and leave the tree exactly as audited, so the ledger and the tree
+ agree on what the caller is deciding about. Evidence-gathering is fair game:
+ read anything, run the existing tests, write transient probes — but remove
+ every probe before handback.
## Done
-The audit is done when every invented choice in the pass has a ledger entry
+The audit is done when every invented decision in the pass has a ledger entry
with a verdict, every unsound entry names the corrected decision to redo
from, every needs-user entry carries a reversible provisional call, and the
ledger has been presented — grouped by verdict, least-confident-first within
each group, every entry readable ELI5 without follow-up questions — to
whoever acts next, with the tree untouched. A handback that shows the diff
-instead of the choices, or a "fix" applied during the audit, is not done.
+instead of the decisions, or a "fix" applied during the audit, is not done.
diff --git a/.agents/skills/explore-unknowns/SKILL.md b/.agents/skills/explore-unknowns/SKILL.md
index 4ea5dbc..e9da36d 100644
--- a/.agents/skills/explore-unknowns/SKILL.md
+++ b/.agents/skills/explore-unknowns/SKILL.md
@@ -102,7 +102,7 @@ decision ledger.
territory answered.
- Close items as decisions, not discussions. Each resolved unknown ends as a
one-line decision plus its why, phrased so the spec can carry it verbatim as
- a given. Every choice a builder later invents unsupervised is an unknown
+ a given. Every decision a builder later invents unsupervised is an unknown
this walk missed — a map that leaves the implementer deciding is incomplete.
- Claims about the territory cite real files actually read; invented data is
labeled as such. A fabricated specific destroys the map's authority.
diff --git a/.agents/skills/implement-spec/SKILL.md b/.agents/skills/implement-spec/SKILL.md
index c6e101a..0e098f9 100644
--- a/.agents/skills/implement-spec/SKILL.md
+++ b/.agents/skills/implement-spec/SKILL.md
@@ -68,12 +68,12 @@ depends on prior work.
concepts, parallel abstractions, and compatibility wrappers it introduced
collapse into the clean contract with one owner, so the code reads as designed
today, not tacked on. Last, run
- [audit-choices](../audit-choices/SKILL.md) on the cleaned pass — a pure
+ [audit-decisions](../audit-decisions/SKILL.md) on the cleaned pass — a pure
audit that appends every decision made where the spec was silent (your own,
- and each delegated subagent's when integrating) to the spec's choices
- ledger (`specs/<feature>/choices.md`) with verdicts, changing no code
- itself. You act on its findings: redo unsound choices from their corrected
- decisions, adopt the recorded provisional call on any user-only entry — the
+ and each delegated subagent's when integrating) to the spec's decisions
+ ledger (`specs/<feature>/decisions.md`) with verdicts, changing no code
+ itself. You act on its findings: redo unsound decisions from the corrected
+ ones it records, adopt the recorded provisional call on any user-only entry — the
audit never blocks the run. Rerun the affected checks, then commit only the
focused changes from this pass.
7. Update the spec README's "Next Agent Prompt": status, completed work, next
@@ -83,7 +83,7 @@ depends on prior work.
Trigger it after a red pass, after every two or three slice commits, after a
rebase/resume/compaction, before changing feature areas, when evidence
invalidates the plan, when the handoff contradicts the TODO/graph, when the
- choices ledger's entries cluster around one slice, or when the
+ decisions ledger's entries cluster around one slice, or when the
active prompt grows hard to scan. Long specs bloat repeatedly; cleanup is a
normal pass, not a cosmetic chore.
@@ -115,19 +115,19 @@ depends on prior work.
that only reads wrong once every slice has landed, and docs that describe
increments instead of the feature are visible at all. Apply the fixes, rerun
the gates, commit.
-11. **Consolidate the choices ledger, then close.** When the last slice lands, the
- `choices.md` you've been appending to per pass is build-order sediment: entries
+11. **Consolidate the decisions ledger, then close.** When the last slice lands, the
+ `decisions.md` you've been appending to per pass is build-order sediment: entries
banked early carry "provisional — revisit in slice N" verdicts that a later pass
silently resolved, entries a later pass reverted still sit there, and the same
- choice may appear twice. The per-pass rule "banked is settled, never re-listed"
+ decision may appear twice. The per-pass rule "banked is settled, never re-listed"
is what let that drift accumulate — so the final consolidation is its deliberate
- exception. Before archiving, **rewrite `choices.md` from scratch** as the final
- ledger: re-audit every banked choice against the **final shipped code** (not the
+ exception. Before archiving, **rewrite `decisions.md` from scratch** as the final
+ ledger: re-audit every banked decision against the **final shipped code** (not the
pass it landed in), collapse each provisional/needs-later entry to its actual
end state, drop anything a later pass superseded or reverted, and merge
- duplicates. Keep it **choices only** — no gate results, e2e evidence, or
+ duplicates. Keep it **decisions only** — no gate results, e2e evidence, or
review-finding narration; those are reported elsewhere and are not decisions the
- user now owns. Present it per [audit-choices](../audit-choices/SKILL.md): grouped
+ user now owns. Present it per [audit-decisions](../audit-decisions/SKILL.md): grouped
by verdict, ranked least-confident-first, every entry ELI5 and standalone.
*Then* close the spec with [close-spec](../close-spec/SKILL.md).
@@ -211,11 +211,11 @@ fixes have landed, the handoff shows nothing left to pick up, and the spec has
been archived with [close-spec](../close-spec/SKILL.md).
Anything short of that is mid-implementation: keep going.
-The final handback presents the choices ledger, not the diff, per
-[audit-choices](../audit-choices/SKILL.md) — a days-long unsupervised run
+The final handback presents the decisions ledger, not the diff, per
+[audit-decisions](../audit-decisions/SKILL.md) — a days-long unsupervised run
earns its merge through this ledger; it is the user's review surface for
everything decided without them. Hand over the **consolidated** ledger from
-step 11 (final state, verified against shipped code, choices only), never the
+step 11 (final state, verified against shipped code, decisions only), never the
raw per-pass append — a ledger still carrying "will be done in a later slice"
verdicts tells the user you never went back to confirm it was.
diff --git a/.agents/skills/write-spec/SKILL.md b/.agents/skills/write-spec/SKILL.md
index 64a0f04..0657be3 100644
--- a/.agents/skills/write-spec/SKILL.md
+++ b/.agents/skills/write-spec/SKILL.md
@@ -177,7 +177,7 @@ whole feature is done.
iterate on quickly. Keep the README's "Next Agent Prompt" written as the
handoff text a future agent should read and follow.
10. **Reslice when the work says so:** if implementation hits a snag and the slice
- starts changing unrelated variables — or the choices ledger keeps filling
+ starts changing unrelated variables — or the decisions ledger keeps filling
from one slice — stop broadening the patch. Update the spec
first: split the slice into smaller contracts, name the frozen inputs, move the
extra visual variables to later slices, and rewrite the Next Agent Prompt to
@@ -256,8 +256,8 @@ Each slice file answers:
- What decisions are delegated to the implementer? Name the freedoms
deliberately left open (internal structure, naming, reversible cosmetic
calls). Everything else must be resolved by the slice: an unlisted decision
- the implementer has to invent is a spec gap that lands in the choices ledger
- ([audit-choices](../audit-choices/SKILL.md)), not implementer discretion.
+ the implementer has to invent is a spec gap that lands in the decisions ledger
+ ([audit-decisions](../audit-decisions/SKILL.md)), not implementer discretion.
- What must stay green?
- What feedback from the human would change this slice?
- If the slice has a human review checkpoint, the slice file must frame it as