Collect evidence about changed behavior and affected callers
Application background
A reading-list API and its export command both use a helper that interprets a requested result limit. A change alters what a limit of zero means. The commit message calls it a small UI adjustment, so a reviewer could easily overlook the export behavior.
You will build a small command that collects the actual code changes, likely callers and relevant existing checks. Its job is to help the reviewer locate evidence, including places where a search cannot establish coverage.
Example walkthrough
| Action | Expected behavior |
|---|---|
The helper parseLimit changes |
Report the changed function and its locations. |
| The API and export command call that helper | List both callers. |
| One caller is registered dynamically and a simple search misses it | Record that limitation when comparing the report with the actual application. |
A diff is the code difference between two revisions. Static search inspects code without running it, so it can suggest affected callers without proving it found every runtime path.
Your assignment
Deliver: Build a review-evidence command that reads a diff, names affected callers and reports uncertainty rather than inventing coverage.
This is a constructed development-workflow exercise. Your output is the artifact named above and the observed comparison, rather than a production platform.
Get the starting application and prepare your workspace
The repository includes a small reading-list HTTP API with SQLite storage. Follow the setup and request walkthrough to save a URL and read it back before changing anything. The API has no tag endpoint, browser UI or production authentication yet.
git clone https://github.com/Soulful-Iris/junior-to-staff.git
cd junior-to-staff
python3 examples/reading-list-starter/app.py --db /tmp/reading-list.sqlite3
Leave the server running while sending the documented requests in a second terminal. Use a separate working copy for the exercise. Any helper, specification, review command or Git branches named below are artifacts you create, not hidden supplied solutions.
Complete the exercise
-
In your work directory create a small
parseLimitfunction with API-list and export callers, or select equivalent real code. Keep a before revision and a revision changing how limit zero is handled. These example names are fixtures you create, not supplied files. -
Write a command that accepts those two revisions, collects the diff and searches direct call sites and existing checks. Include file locations and report
NONEwhen no relevant existing check is found. -
Add a dynamically registered caller that static name search misses. Manually compare the report with actual calls and record the tool's limits. A generated review summary is evidence for a reviewer, not approval.
Demonstrate the result
01 · Small example
- Input / starting state
- Diff changes
parseLimit. Callers are API list and export. Only API list hastest_limit_zero. - Expected result
- Report both callers. Name that test for API list and
NONEfor the uncovered export behavior.
02 · Boundary / failure
- Input / starting state
- A caller is registered dynamically and absent from simple text search.
- Expected result
- Mark search limits and inspect runtime registration. Do not claim complete call-graph coverage.
03 · Scope
- Input / starting state
- Ten recorded diffs. Collector supplies evidence, never an approval verdict.
- Expected result
- Explain any additional assumption before implementing it.
Keep the exact input, observed output and before/after artifact in your exercise README. Label constructed fixtures as fixtures. A fresh reader should be able to repeat the comparison without your conversation history.
Deployment scope
This assignment concerns local development evidence and workflow. AWS deployment is not required and no cloud resources are supplied or created. CI-policy exercises belong in a disposable repository. They do not change this guide's publish-on-main behavior. For a later application deployment, the starter's local-to-AWS mapping explains the missing adapters.
Additional reasoning and harder requirements
Study the failure, follow-up requirements and implementation prompts
The message describes intent. Risk follows actual dependency edges. A named nearby test is not proof until it detects the proposed accident.
Reveal the approach and decisions
Collect changed symbols, references, and tests, then identify the semantic risk. The invariant is that every claimed protection names a test demonstrated to fail on that accident. Preserve NONE and uncertainty rather than manufacturing a reassuring match.
Follow-up 1 · Prove a named test
The tool says test_limit_zero catches an inverted condition. How do you verify that statement?
Worked design and implementation
Introduce that condition on an isolated branch and run the named test. Capture the failure and restore the tree. A passing mutant disproves the coverage claim.
Verify the exact protection claim. In the exercise checkout, introduce the named inverted condition and run only test_limit_zero first. Capture its failing assertion and then restore the original source. If it passes, the tool's claim is unsupported even if another case fails in the full suite.
Hand over the changed line, named case and observed result. Keep the experiment isolated from shared main. This is the subject of the lesson, not an instruction to create new tests for the curriculum edit.
Follow-up 2 · The change crosses a service
The parser determines an outbound payload used by an independently deployed consumer. What evidence is missing?
Worked design and implementation
Add the consumer contract and a provider negative fixture. Local references cannot enumerate deployed clients. Identify a contract owner and document unknown consumers.
Add evidence beyond local references. A parser may emit a payload read by a separately deployed service. Local code search cannot enumerate that consumer's behavior. Obtain its versioned wire contract, representative input/output and owner, then track which versions are still deployed.
Change a field from milliseconds to seconds while preserving its numeric type. Show the old consumer interpreting the value incorrectly. Deliver a producer/consumer compatibility matrix and identify unknown consumers. The larger boundary is independent deployment, not merely another directory in the repository.
Record the evidence and limitations
Build in three stops: reproduce the small case and baseline failure. Implement the protected boundary. Then replay both changed requirements with captured outputs. Record commands, fixtures, and observed results in your implementation README. A diagram is a prediction until those checks run.
Reproduce one real coverage gap and disprove one mistaken protection claim. Additional lead scope: Assign cross-service contract ownership and characterize collector blind spots. Completion demonstrates practice evidence. It does not establish interview readiness or multi-team delivery experience.
Detailed implementation and AI-assisted prompts
You end up with a repeatable interrogation for any diff, and one number from ten real ones: how often nothing would have caught an accidental change.
Build
A written procedure plus a small script that collects evidence and answers three questions of any diff: what behaviour changed, what could have changed accidentally, which existing test would catch the accident. Run it on ten real diffs from your history and tally how often the third answer is "none".
The thought process
A harness is not for replacing your reading. It is for making your tenth review of the day as good as your first. Attention degrades invisibly, and a procedure carries quality through fatigue — the reason experienced pilots still run the checklist. The commit message describes the intended change. The accidental one lives in the blast radius — every caller of a changed function, every other user of a touched helper or config key. That is greppable, so the script fetches evidence and holds no opinions.
The third question must end in a test's name or the word "none" — never "probably the auth tests". Both answers are checkable: break the behaviour and the named test must fail. Plant the accident and a true "none" leaves the suite green. If all ten diffs come back covered, ask what the answers would look like if coverage were bad — the same, and the harness is agreeing with you, not reviewing.
How to organise the prompts
1 — design the procedure against real diffs.
Here are three recent diffs from this repository. Draft the
procedure for interrogating any diff: for each of the three
questions, the mechanical evidence that answers it — commands, not
judgment. The third answer must be a test name or the word NONE.
The procedure must name commands you can run. Any step beginning "consider whether" is judgment smuggled in as evidence, so send it back.
2 — build the collector.
Write the evidence collector: given a diff, list the changed
functions, their callers, every other file using a helper or config
key this diff touches, and the tests exercising any of those.
Output file:line lists only. No prose, no conclusions.
Run it on a diff whose blast radius you already know — it must find the caller you know about, or it will never surface the ones you do not.
3 — the ten runs.
Here is diff 4 of 10 and the collector's output. Answer the three
questions; every claim must cite file:line from the evidence. If no
existing test would catch the accidental change, write NONE — not
the nearest test.
Spot-verify two NONEs by making the accidental change for real: a green suite means the NONE was true and the tally is data.
On AWS
It can run where the diff lives: GitHub Actions, on every pull request. Estimate runner usage for the current repository plan. AWS enters only if the harness calls a model per diff — then route it through Bedrock with invocation logging on, so each review has a visible cost in CloudWatch. A review bot nobody meters gets quietly expensive. And whatever runs it gets read-only credentials: it comments, it never merges.
What productionising it means
The tally is the real product: a none-rate over time, saying whether the suite grows with the code or falls behind it. The failure mode is ritual — people reading the harness instead of the diff — so it cites evidence and asks questions, never concludes "looks good". Alarm on the none-rate rising. That is the trend it exists to catch.
The learning
The dangerous part of a change is the part the message never mentions, and "none" is the most informative answer a review can produce — untooled reviews almost never do. Ten diffs teach you your real safety margin as no coverage percentage has.
How you would know it is wrong
- Plant an in-passing edit to a shared helper in a test diff. If question two does not list it, the blast-radius logic is decorative.
- Verify a named test the way you verify a NONE: break the behaviour. That test, specifically, must fail.
- Run the harness twice on one diff. Materially different answers mean a rumour generator. Pin every claim to collector output.
- Ten out of ten covered. In my own record, answers shaped that much like good news have usually been the instrument — check it before you believe it.