Skip to content
Hands-on Coding Assistants

Part 1 — Start from a Repository Chapter 5

Debugging, Refactoring & Iteration with AI

In this chapter

Start at the first incorrect observation

The registration spec says that rejecting a request leaves the next ID available. Yet the first valid request after a rejection can return ID "2". Both status codes look right. You need the sequence to see the failure.

Use the lab-debugging tag, which starts from a working registration change and reintroduces the bug. Commit any previous exercise first. In a clean checkout, run the starter suite and the contract separately.

git switch -c debug-registration lab-debugging
npm test
npm run test:registration
PORT=3100 npm start

The base suite passes. In the registration contract, the normalization test passes and the other test expects ID "1" after 14 rejections. It gets "15". Try just one rejection and one success against the same fresh server. Run both commands in a second terminal.

curl -sSi http://127.0.0.1:3100/registrations \
  -H 'Content-Type: application/json' \
  -d '{"name":42,"email":"ada@example.test"}'
curl -sSi http://127.0.0.1:3100/registrations \
  -H 'Content-Type: application/json' \
  -d '{"name":"Ada","email":"ada@example.test"}'

Expect 400 and {"error":"invalid_registration"}, then 201 and {"id":"2","name":"Ada","email":"ada@example.test"}. Restart the server when you need to try the sequence from ID "1". Stop it when you’re done.

Test the explanation before asking for an edit

Give Plan your observed responses and one question it can trace.

On a fresh server a numeric name gets HTTP 400. The following valid
registration gets HTTP 201 with id "2". Read specs/registration-validation.md,
contracts/registration.test.ts and src/app.ts. Trace both requests.
Check these possible causes against the code and evidence: an incorrect
initial value, an extra stored registration, or allocation on rejection.
Cite the relevant statements and tell me what you can rule out.
Return findings for review before proposing an edit.

On another fresh instance, try a valid request first. It gets ID "1", which rules out an incorrect initial value. The rejected request returns before the array push. Inspect the statement that advances the counter and see whether execution reaches it before that return. You can make the fix as small as the cause.

Prove the failure in a focused test

Ask Build to add a test first. In test/registration-regression.test.ts, use startApp(t) and jsonRequest() from test/client.ts. Send exactly the two inputs you used with curl. Assert 400 and the error body for the first response, followed by 201 and ID "1" for the second. Leave the handler unchanged until you’ve seen that assertion fail.

node --test test/registration-regression.test.ts

Read the failure. A test that only sees 400 would pass this broken implementation. Once you can reproduce the "2" result with the new test, move ID allocation past validation. Inspect the diff and rerun the test and both suites.

node --test test/registration-regression.test.ts
npm test
npm run test:registration
git diff --check
git status --short

Expect all tests to pass. Check the changed handler and read the new file as well. Git does not include an untracked test in git diff until you stage it.

Make the handoff about facts

Write notes/registration-fix.md with the symptom, shortest request sequence, cause, patch and observed verification results. Record the base tag and cite the regression test. Commit the fix and test together so someone can compare the result against the fixture.

git add src/app.ts test/registration-regression.test.ts notes/registration-fix.md
git diff --cached --check
git diff --cached --stat
git commit -m "Preserve the next registration ID after rejection"

Refactor after you have a green baseline

With the fix committed, you can try extracting a validation function in a separate branch. Keep status codes, ID allocation and storage in the route. Rerun the focused test and the contract after the extraction. Leave the function inline if extracting it makes the order harder to see. The verified fix commit is the one to use when you document the API.

References

  • Node.js contributors. Test runner. Node.js API reference.
  • Git maintainers. git-diff. Git reference manual.
  • OpenCode maintainers. Agents. OpenCode 2 documentation.