Guides

Fixing a real bug

Writing an issue that carries evidence, choosing the target test, and what to do with a failure.

A fixture run proves the plumbing works. A real repository adds two inputs that decide the outcome: how well the bug is described, and which test is treated as the target.

Write the issue like a bug report

The issue text is evidence, not instructions. Say what is observably wrong and where; the planner reads it to decompose the fix. It is also the source of the intrinsic difficulty signal, so padding it with urgency or a long stack trace over a one-line bug changes routing without helping the fix. If the report is long, pass a file instead: `--issue @bug.txt`.

The symptom, in terms of what the code returns or raises
Where it shows up — the module or function, if you know it
What the correct behaviour would be
The test that demonstrates it

Choose the target test

`--target-test` takes a pytest node id, and it is what the gate measures. The suite command is autodetected; `--test-command` overrides it when the project needs something specific.

neo fix \
  --repo ../your-project \
  --issue @bug.txt \
  --target-test "tests/test_parser.py::test_trailing_comma" \
  --test-command "python -m pytest -q" \
  --budget 2.0

When it fails

Read rationale.md first — it states how the run ended and what it touched
`neo status --task-id <id>` for the plan checklist and recorded decisions
trace.jsonl for the verify output the gate actually rejected
The exit code is 1, and no branch or commit exists; a refused claim is the gate working, not a bug