/cad-why: read the corpus back at a file and line #192

New issue

Closed

opened 2026-08-16 15:41:12 +00:00 by john · 1 comment

john commented

2026-08-16 15:41:12 +00:00

Owner

The problem

The .planning/ corpus can already answer "why is this code like this" and
nothing surfaces it.

Everything needed is on disk: the phase SUMMARY names what shipped and its
commits, the plan names the task, CONTEXT names the numbered decision behind it,
the deviation record names where the plan was wrong, the review artifacts name
what an adversarial pass objected to, and trace.jsonl names what it all cost.
A file path plus a commit is enough to walk all of it, and there is no command
that does.

That is the product's single best answer to its own value claim, sitting unread.

The proposal

A reader, not a writer:

/cad-why <path>[:<line>]

Resolves through git log for the commits touching that path, then joins each to
its phase, its plan task, the D-NN that decided it, any deviation that refuted
that decision, and any review finding that survived triage against it.

Output is a short chain, newest first, with the record's own words. No model
judgment, no summarization pass. It is a join, and it should be a deterministic
seam script for exactly that reason.

Why this is worth building before anything else on the list

It is the only item here that is a demo. Cadence currently has no artifact that
produces a win in the first ten minutes, and the README has to argue the value
instead of showing it. "Point at any line and it tells you which decision put it
there, and which later phase proved that decision wrong" is thirty seconds and
needs no argument.

It also has a second-order effect: it is the first thing that makes the corpus
READ, which surfaces immediately whether the write-side care has been worth it.

Cost

Low relative to the others. It writes nothing, gates nothing, and can fail
gracefully on any phase whose record is incomplete. The hard part is the join
across renamed and pruned phases, and the honest answer there is to report the
gap rather than guess.

## The problem The `.planning/` corpus can already answer "why is this code like this" and nothing surfaces it. Everything needed is on disk: the phase SUMMARY names what shipped and its commits, the plan names the task, CONTEXT names the numbered decision behind it, the deviation record names where the plan was wrong, the review artifacts name what an adversarial pass objected to, and `trace.jsonl` names what it all cost. A file path plus a commit is enough to walk all of it, and there is no command that does. That is the product's single best answer to its own value claim, sitting unread. ## The proposal A reader, not a writer: ``` /cad-why <path>[:<line>] ``` Resolves through `git log` for the commits touching that path, then joins each to its phase, its plan task, the `D-NN` that decided it, any deviation that refuted that decision, and any review finding that survived triage against it. Output is a short chain, newest first, with the record's own words. No model judgment, no summarization pass. It is a join, and it should be a deterministic seam script for exactly that reason. ## Why this is worth building before anything else on the list It is the only item here that is a demo. Cadence currently has no artifact that produces a win in the first ten minutes, and the README has to argue the value instead of showing it. "Point at any line and it tells you which decision put it there, and which later phase proved that decision wrong" is thirty seconds and needs no argument. It also has a second-order effect: it is the first thing that makes the corpus READ, which surfaces immediately whether the write-side care has been worth it. ## Cost Low relative to the others. It writes nothing, gates nothing, and can fail gracefully on any phase whose record is incomplete. The hard part is the join across renamed and pruned phases, and the honest answer there is to report the gap rather than guess.

john added the

enhancement

proposal

labels

2026-08-16 15:41:12 +00:00

john referenced this issue

2026-08-23 18:24:20 +00:00

v3.6.0 - reading the corpus back #239

john commented

2026-08-23 18:34:09 +00:00

Author

Owner

Shipped in v3.6.0 as WHY-01.

/cad-why [:] resolves the commits touching a path and joins each to six record edges: phase, plan task, the D-NN that decided it, the deviation that refuted that decision, the review finding that survived triage, and the declaring task. Deterministic seam, no model judgment, no summarization pass.

The hard part this issue named, the join across renamed and pruned phases, answers rather than guesses. Run against lib/why-corpus.mjs right after the v3.6.0 close pruned phase 3, the chain still resolves it: 'phase: v3.6.0 phase 3 (recovered from a40f7fcf:.planning/phases/3)'. Where no tier answers, it names the gap in words instead of returning an empty chain.

Three limits are named in the CHANGELOG rather than hidden, and are v3.6.1's scope: the bare-path arm inherits git's default history simplification (7 of 10 commits measured on lib/release-decision.mjs), the renderer's entry cap of 10 carries a byte reason measured false at 15,637 B, and closeOver compares timestamps as strings.

Shipped in v3.6.0 as WHY-01. /cad-why <path>[:<line>] resolves the commits touching a path and joins each to six record edges: phase, plan task, the D-NN that decided it, the deviation that refuted that decision, the review finding that survived triage, and the declaring task. Deterministic seam, no model judgment, no summarization pass. The hard part this issue named, the join across renamed and pruned phases, answers rather than guesses. Run against lib/why-corpus.mjs right after the v3.6.0 close pruned phase 3, the chain still resolves it: 'phase: v3.6.0 phase 3 (recovered from a40f7fcf:.planning/phases/3)'. Where no tier answers, it names the gap in words instead of returning an empty chain. Three limits are named in the CHANGELOG rather than hidden, and are v3.6.1's scope: the bare-path arm inherits git's default history simplification (7 of 10 commits measured on lib/release-decision.mjs), the renderer's entry cap of 10 carries a byte reason measured false at 15,637 B, and closeOver compares timestamps as strings.

john closed this issue

2026-08-23 18:34:13 +00:00

john added this to the v3.6.0 milestone

2026-08-23 20:50:27 +00:00