From Generated Code to Owned Code

This optional bridge session is for a class that completed Project A but does not yet feel able to explain or safely change what the agent produced. It does not replace Project B. It gives you another way to spend a morning before moving on.

The goal is not to understand every line. By the end, each pair should be able to:

• trace one input from the CLI boundary to output;
• predict one success and one failure before running them;
• connect a requirement to code and a defending test;
• explain one ownership, error-policy, or architecture decision;
• make one small change safely; and
• separate an agent’s explanation from claims verified in the repository.

Working agreement

Work in the Project A repository you produced. Create a checkpoint before the session and keep the tests green between activities.

For every investigation:

1. Humans predict first.
2. The agent may explain second.
3. Every explanation claim gets a file and symbol, a test, or the label unverified assumption.
4. The person who did not drive that part of Project A gives the final explanation.

Do not ask the agent for a general tour of the repository. Ask a question with an observable boundary.

Suggested 160-minute session

1. Draw the architecture

Draw boxes for the executable boundary, reusable domain code, parser, policy, aggregation, and output formatting. Add arrows for calls and important data. Mark where untrusted text first becomes a typed value and where data becomes owned.

Your map must answer:

• Can a new subcommand reuse the parser without changing it?
• Does any frame borrow from the input buffer? If so, how long can it live?
• Where does the malformed-line policy live?
• Which module knows about CLI arguments?
• Which operation could grow with the size of the input file?

The map is a hypothesis until code and tests support it.

2. Trace a vertical slice

Use one known valid line:

(1712345678.123456) can0 18FF0102#DEADBEEF11223344

Before running the program, predict the parsed fields, the command output, and the ownership transitions. Then trace the actual symbols in order. Record only the shortest chain that explains the behavior.

Repeat for one malformed line from medium.log. This time include:

• the function that recognizes the failure;
• the error type or policy decision;
• the exit status and diagnostic boundary; and
• whether any output can already have escaped.

3. Build claim/evidence cards

Complete at least three rows:

It is acceptable for a row to expose missing evidence. That is a finding, not a failed exercise.

4. Test archaeology

Pick one test that matters. Explain the production behavior it protects, then name the smallest mutation that should make it fail. Examples:

• replace a checked parse with unwrap();
• accept an invalid CAN identifier width;
• collect all input lines before processing;
• emit a matching line before the full input is validated;
• divide by a zero capture duration; or
• silently change a JSON field name.

Make the mutation on a disposable branch if it is safe to do so. If the test does not fail, improve the test before restoring the implementation.

An especially useful bridge to Project C is a property test asserting that arbitrary external input never makes the parser panic.

5. Make one small change

Choose a change that crosses at least two modules but fits in 25 minutes. Write the test first and predict which symbols will change. Afterward, compare the actual diff with the prediction.

Good-sized changes include:

• define behavior for --limit 0;
• make a malformed-line policy observable in summary;
• cover zero-duration captures explicitly;
• add a parser property for arbitrary input; or
• make one JSON compatibility rule executable as a test.

The change is complete only when the pair can explain why unrelated behavior did not change.

6. Audit an agent explanation

Now ask the agent:

Explain this vertical slice as a sequence of concrete claims. For each claim, identify the file, symbol, and test that supports it. Mark anything you cannot prove from the repository as an assumption.

Annotate the answer. Verify, correct, or reject every claim. Do not reward a fluent explanation that points at the wrong code.

7. Teach it to another pair

The visiting pair gets five minutes to read, then presents the architecture back to its owners. The owners may answer questions only with a code location, test, command result, or explicit assumption.

Finish with four statements:

1. One thing we can now explain.
2. One behavior a test genuinely protects.
3. One part we still do not understand.
4. One change we now believe we could make safely.

Bridge to Project C

Project C changes the domain and the shape of evidence, not the ownership obligation:

Carry the claim/evidence-card format into SAFETY-NOTES.md.