| name | terminal-investigation |
| description | Ground yourself in an unfamiliar terminal task before writing any code. Read the instruction twice, map the repo, and locate the verifier so your first edit is informed rather than a guess. |
Terminal Investigation
You are dropped into a repository at /app (or wherever the task mounts it) with an
instruction.md-style brief and a hidden verifier. Before you touch any source file,
do the five things below. Every one of them is cheap, and skipping them is the single
most common reason agents waste a turn budget.
1. Read the task twice
Read instruction.md (or the equivalent brief) end-to-end. Then read it again. Write
down in your working message:
- The single user-visible outcome the task wants (one sentence).
- Every concrete artifact the task mentions (file names, ports, commands, output
formats).
- Any "do not" / "must not" clauses — missing these is what turns a plausible fix
into a failing verifier.
2. Map the repo
Before editing anything, run a single compact survey:
ls -la && find . -maxdepth 3 -type f \
\( -name '*.md' -o -name 'Makefile' -o -name '*.toml' -o -name '*.yaml' \
-o -name '*.yml' -o -name 'Dockerfile' -o -name 'package.json' \
-o -name 'pyproject.toml' -o -name 'requirements*.txt' \) 2>/dev/null
Then skim the files that showed up. One pass. Do not read everything.
3. Find the verifier and read it
There is almost always a tests/, test.sh, test_state.py, or verify* script.
Open it. The verifier's code is the truest spec of the task — more trustworthy
than prose, because the verifier is what grades you. Note:
- What exit code / output string it checks for.
- What files or services it pokes at.
- Any test fixtures it depends on.
If the verifier imports modules or expects files at specific paths, those paths are
contractual. Do not move them.
4. Reproduce the current failure
Run the verifier once before changing anything. Capture the actual error. This gives
you a concrete baseline to compare against and stops you from "fixing" a problem
that isn't the one the verifier cares about.
5. State your plan in one short paragraph
Before the first edit, write a 2–4 sentence plan: the root cause you suspect, the
file(s) you'll touch, and how you'll verify. If you cannot write this paragraph, you
are not ready to edit — read more.
Anti-patterns (stop yourself if you catch any of these)
- Editing a file whose path you have not verified with
ls or a read.
- Running
find / or grep -r / at repo root — you will swamp the turn budget.
- "Fixing" something by catching the exception and swallowing it.
- Adding new files when the task clearly edits existing ones (or vice versa).
- Assuming the verifier runs
pytest — many tasks use bash test.sh or a custom
Python checker. Look, don't guess.
