Add drawn reference notes and a debt lens
Interactive review returns a reference note after the contributor submits, and it was plain text: a call path or a design tradeoff had to be read out of prose, and nothing asked who would know the reasons later. The note can now carry a flow diagram, a comparison table and quoted code, and the review gains a step that looks at the change as three kinds of debt.
Every citation in a drawn note must be a line of the pinned diff, and quoted code is taken from the diff, never typed. A solid arrow needs a citation; a link the diff cannot support is drawn dashed and labeled as an inference. When a drawn note cites something the diff does not hold, the reviewer is sent back once with the problem named; if it still does not read, the note is stored as written and shown as plain text.
The debt step gives observations and questions, never a score, and writes nothing for the contributor. A removed check opens at its old line, and the contributor can write a short intent record in their own words and copy it into the PR body. The record is kept for one snapshot, is not part of the answers or the signed record, and is never given to the reviewing agent.
The page also guides the work now. A rail of four steps (Read, Explain, Compare, Keep the why) stays at the top and marks where the contributor is; feedback that arrives is announced and marked on it without taking focus, and is shown beside the explanation exactly as it was sent, so the self-assessment is made with both in view. The intent record is a disclosure that opens once one exists, and Ctrl or Cmd with Enter sends the answer or saves the record.
The feedback schema, digest, head binding and completion record are unchanged. The runtime is still the Python standard library and Git, and the new Python modules parse on Python 3.8.
Verified with the review unit suites, the browser suites for the workbench and the flow layout (including a randomized layout property test), scripts/test-interactive-review.sh, and a pass in light, dark and phone widths under the page's CSP.
Demo video:
https://github.com/user-attachments/assets/ca250e47-94e9-453e-8081-9a45f45dfc8d
Summary by cubic
Interactive review now returns a drawn reference note instead of plain prose, and the review ends with a debt lens step that reads the change as technical, cognitive, and intent debt. A rail of four steps stays at the top and marks where the contributor is.
Draw the reference note
- Every citation is a line of the pinned diff; quoted code comes from the diff, never typed.
- Solid arrows cite the diff; inferred arrows are dashed and labeled.
- Clicking a citation opens its line in the diff.
- The managed worker draws a flow by default; a note the diff cannot hold is sent back once, then stored and shown as text.
Debt lens and step rail
- Shows observations and questions only, never a score.
- Removed and added assertions count the same, so a moved assertion no longer hides a lost one.
- A removed check opens at its old line, and the contributor writes a short intent record to copy into the PR body.
- The record is kept for one snapshot, stays out of the answers and signed record, is never given to the reviewing agent, and finishing refuses unsaved edits; a record that only chooses where the why will live counts as saved.
- Feedback is announced and marked on the rail without taking focus, and shown beside the explanation exactly as sent.
- Ctrl or Cmd with Enter sends the answer or saves the record from the answer box or a focused diff; a new reply is noticed by its digest, so a second tab between two identical replies still announces it.