Fix a bug

1. Restate the symptom

Write down what happens, what should happen, and the command that triggers it (td <command> <args>). If the report is vague, restate it to the owner and ask before going further. Done when the symptom fits in one sentence.

2. Reproduce it in a test

Write a test that fails on the exact symptom, at the lowest layer that shows it:

• a helper in src/lib/ → its *.test.ts next to it;
• a command's flags, API calls or output → the command's test, through program.parseAsync(['node', 'td', ...]) with setupApiMock();
• argv parsing, global flags or the JSON error envelope of the built CLI → src/index.integration.test.ts.

Follow write-tests for helpers and the quality bar. Run the test and see it fail for the reason in step 1, not a typo or a missing mock. Done when the failure message describes the bug.

3. Find the root cause

Trace from the symptom to the first place the data goes wrong. Name it with path:line. A fix at the symptom (a special case, a retry, a try/catch) is not a root cause. Done when you can say why the code does what it does.