Leave comments while reading

Principles in play: Track records.TRACETrack records

A comment you leave while reading is direction, as a prompt is. The trace record keeps its original words, its speaker and its source before your agent acts on it.

Steps

1. Leave a REVIEW marker beside the passage, with what you want changed. Any file the repository tracks is read.

2. Ask your agent to capture the comments.

   Say to your agent

   Collect my review comments and capture them in the trace record before you resolve any of them.

3. Read what was captured, then have it done.

   Say to your agent

   Now make the changes the comments ask for, and remove each marker once its comment is captured.

Things to know

• The inbox stays on your machine. The generated ai/review-inbox.md holds raw comments, so it is ignored and local-only.
• Captured before resolved. A comment goes into the record before it is acted on or its marker deleted.
• Your comment can make you a default owner. The people whose prompts or comments direct a change are its default owners.
• A comment that finds an error opens a defect. When your comment says something in the work is wrong, rather than asking for a change, the agent captures it, opens a row in the defect ledger in your name quoting the marked text, and the commit that resolves it says it fixes that row.

What the agent runs

python3 scripts/review_inbox.py collect --json > <ignored packet>     # gather the markers
python3 scripts/trace_record.py comments <staging-record> \
    --input <ignored packet>                                         # capture them in the draft record