Task file: tasks/issue-77-executor-notes.md
Problem
The friction log is pure telemetry: events, verdicts, commits, timings. There is no field where the executor can explain why something happened — why a red-first violation occurred, why an undeclared file was touched, what made a cycle hard, what the plan got wrong. In a review of ~30 machine-generated logs, every judgement call had to be reverse-engineered from event lines and git archaeology; the executor's reasoning, which existed at the time, was simply discarded.
The flip side of a prose-free log: neither hand-waving nor legitimate qualitative friction ("the plan's fixture assumption was wrong", "this API doesn't exist") can be expressed, so the log under-serves exactly the retrospective it exists for.
Proposal
- Add an executor-notes channel: a
tdd note "<text>" command (scoped to the current cycle/phase) and/or a structured prompt at run close asking the executor for a short narrative — hardest cycle and why, plan inaccuracies encountered, deviations taken.
- Render notes inline in the friction log next to the cycle they annotate, visually distinct from telemetry (they are claims, not measurements).
- Optionally prompt for a note automatically when specific events fire (
red_first_violation, undeclared_file_touched, blocker resolutions) — the moments where the "why" has the most value and is otherwise lost.
Notes are free text and unverified by design; the value is capturing intent at the moment it exists, so a later audit compares claims against reality instead of guessing at both. (Distinct from #58, which is authored-at-plan-time metadata — this is authored-at-run-time narrative.)
Task file:
tasks/issue-77-executor-notes.mdProblem
The friction log is pure telemetry: events, verdicts, commits, timings. There is no field where the executor can explain why something happened — why a red-first violation occurred, why an undeclared file was touched, what made a cycle hard, what the plan got wrong. In a review of ~30 machine-generated logs, every judgement call had to be reverse-engineered from event lines and git archaeology; the executor's reasoning, which existed at the time, was simply discarded.
The flip side of a prose-free log: neither hand-waving nor legitimate qualitative friction ("the plan's fixture assumption was wrong", "this API doesn't exist") can be expressed, so the log under-serves exactly the retrospective it exists for.
Proposal
tdd note "<text>"command (scoped to the current cycle/phase) and/or a structured prompt at run close asking the executor for a short narrative — hardest cycle and why, plan inaccuracies encountered, deviations taken.red_first_violation,undeclared_file_touched, blocker resolutions) — the moments where the "why" has the most value and is otherwise lost.Notes are free text and unverified by design; the value is capturing intent at the moment it exists, so a later audit compares claims against reality instead of guessing at both. (Distinct from #58, which is authored-at-plan-time metadata — this is authored-at-run-time narrative.)