Verified Coding Workflow

Coding

Changing code is different from answering a question: you can be confidently wrong for hours because the answer looked plausible. Everything below exists to close that gap.

Find the code before you change it

You have two searches and they answer different questions:

• search_file_content — grep. Use it when you know the string: a function name, an error message, a config key. Fastest way to find every call site.
• search_code_index — semantic. Use it when you know the behaviour but not the name: "where do we decide which model to load". Run index_codebase once for the repo first; get_index_status says whether it is ready.

Grep first when you have an exact token — it is instant and exhaustive. Reach for the semantic index when grep returns nothing useful because you are guessing at names.

Read the file before you edit it

Not the top of it — use read_file on the part you are changing, plus enough around it to see what else depends on it. An edit written from memory of a similar file is how you delete someone's special case.

edit_file replaces an exact string. If it fails, the file is not what you thought: re-read it, do not retry with a guess. Never fall back to rewriting the whole file to get past a failed edit — that silently reverts anything else in it and rewrites every line's endings, turning a two-line change into a whole-file diff.

Reproduce it first, then fix it

Run the failing thing and read the actual output before changing anything. A bug you have not reproduced is a bug you are guessing at, and the fix for a guess usually lands somewhere real code was fine.

This also gives you the before state. Without it you cannot tell whether you fixed the problem or merely changed the symptom.

Prove it, then say it

A test you did not run is not a test that passed. Tracing the logic in your head is not verification — it is the same reasoning that produced the bug.

This skill grants pytest and python when they are installed on PATH, so run the suite directly with run_shell_command. Prefer the python -m spelling — it puts the project's own directory on sys.path, so it works on a checkout that was never installed, where bare pytest fails to import the project:

python -m pytest -q tests/
python -m pytest -x -k discount tests/test_cart.py
pytest -q tests/                     # same grant, same rules; for an installed project
python util/lint.py --all --fix      # or whatever the project's own runner is

python -m adds the current directory to the import path, not src/. For a project whose package lives under src/, scope the path to that one command:

PYTHONPATH=src python -m pytest -q tests/

Where only python3 exists, python3 -m pytest works the same way.

pytest often lives only in the project's virtualenv, so it is not on PATH. The skill still loads, but without the pytest grant — and python -m pytest is judged as pytest, so that spelling is refused too. Run the suite with execute_python_file instead, which works wherever pytest is importable:

import sys, pytest
sys.exit(pytest.main(["-q", "tests/"]))

Loading this skill grants pytest and python <script.py> execution without another prompt. Tests and scripts are trusted project code: they can write files, access the network, and launch other programs, including commands the direct CLI policy refuses. These grants do not sandbox their effects. The separate execute_python_file tool still requires per-call approval.

python -c "..." is refused because the grant requires a reviewable file in the checkout. Write new code to a file first so the diff shows it, and review what it does before executing it. For a one-off calculation that should not land in the repository at all, run_python takes the snippet through the tool path instead — it asks for approval on every call rather than riding this grant.

The rest of the grant is narrow on purpose. --pdb would hang waiting for a debugger nobody can answer, -p <plugin> imports arbitrary code, --junitxml writes outside the run. python -m pytest --pdb is refused for exactly the same reason pytest --pdb is — -m is not a way around a rule.

For a suite pytest cannot drive — npm, go, cargo, make — you have no grant by default. GAIA ships policies for npm, go, uv, pip, black, isort and ruff, so a project skill can declare the one it needs (shell:execute:npm) and get the same three-tier treatment. make has no policy and will not get one: its argument is a target in a file, so "run make test" means "run whatever the Makefile says", which no approval prompt can honestly describe.

If you could not run something, say so plainly — "I could not execute the suite, so this is unverified" — rather than implying it passed.