Groundwork

Groundwork

Apply this method to every software task in this session: coding, debugging, research, review, or repair. It exists because agents fail in two ways — inventing facts, and declaring victory without proof. Every rule below closes one of those two holes.

The five non-negotiables

Follow these on every task. Everything else in this skill is machinery for meeting them.

1. Evidence or it didn't happen. Claim success only for what you ran or read in THIS session, quoting the actual command and its actual output. Say "verified: ran X, got Y" — the phrases "should work", "this likely fixes it", and success claims about code you never executed are banned, because unexecuted code fails at a high rate.
2. Read before you reference. Open the file, run the command, or fetch the doc before you cite it. If you have not read it this session, either go read it now, or write "UNKNOWN — here is how I'll find out" and then find out. Guessing dressed as knowledge is the failure this skill exists to kill.
3. Red before green. Reproduce a bug and watch the check FAIL before you fix it; watch the same check pass after. A fix without a previously-failing check is an unverified guess.
4. Root cause over symptom. State the cause and the evidence for it before writing a fix. Never make a symptom disappear by suppressing an error, weakening or deleting a test, or special-casing the reported input — that converts one visible bug into two hidden ones.
5. Leave the project smarter. Before finishing: update the project map (PROJECT-MAP.md) to match what you changed, and record any root-caused bug in the learnings log (LEARNINGS.md). The next session must inherit a current map, not archaeology.

Step zero — on first contact with any project (once per session)

1. Look for and obey local instruction files: AGENTS.md, CLAUDE.md, CONVENTIONS.md, .cursor/rules, CONTRIBUTING.md. The nearest file to the code you touch wins. They outrank this skill on project-specific matters (commands, style, workflow).
2. Verify the ground you'll stand on: run the project's test/build command once now, before changing anything, and record the baseline — which tests pass, which already fail. In a monorepo or huge repo, scope this to the package(s) you will touch, not the whole repo; if the smallest honest run exceeds ~10 minutes, run the scoped target and state in your report "full suite not run — scoped to X because of cost". Pre-existing failures are baseline, not yours to fix (unless they block the task or are the task); "done" later means no NEW failures relative to this baseline.
3. Look for PROJECT-MAP.md and LEARNINGS.md at the project root (in a monorepo: at the package root you are working in).
   • Both exist → read them first. Their contents are testimony from a prior session, not verification: a fact from the map/log/README stays ASSUMED until you observe it yourself (the baseline run in item 2 verifies the test command; other claims get checked when you rely on them).
   • Map missing → create it now following references/project-map-spec.md, using the item-2 baseline result. Skip map/log creation entirely when the task touches no repository (pure research or advice) — never create files nobody asked for outside a project.
   • Log missing → create an empty one per references/learnings-log-spec.md.

The Loop — run every task through it

Copy this checklist into your response at the start of every task and check items off as you complete them. Scale it: for a truly trivial task (the diff fits in one sentence AND changes no runtime behavior — the trivial tier in references/self-testing-loop.md), steps 3 and 6 may be one line each — but steps 2, 5, and 7 are never skipped.

Task loop:
- [ ] 1 Orient — what does the code actually say?
- [ ] 2 Define done — which commands/observations will prove success?
- [ ] 3 Plan — smallest change that hits the root cause
- [ ] 4 Build — small steps, check syntax after each edit
- [ ] 5 Verify — run the step-2 commands, paste real output
- [ ] 6 Hostile review — attack your own work
- [ ] 7 Record — update map + log, report with evidence

1 Orient. Read the README and the specific files you will change — in full, before designing. Check LEARNINGS.md for this exact problem: a logged problem is never re-solved from scratch. For anything unfamiliar (library, API, tool), follow references/research-protocol.md.

2 Define done. Write down, before building, the exact commands or observations that will prove the task worked (test command, CLI invocation, expected output/exit code). The criteria must include (a) the user's reported scenario or the real entry point exercising the requested behavior, and (b) at least one check that would FAIL if the requested change were absent — name which check that is. Criteria that a reverted change would still pass are invalid. If no such check exists yet, creating one IS the first part of the task. Once written, the criteria list is append-only: weakening or dropping a criterion needs evidence (docs/tests/user intent) and a "CRITERIA CHANGED" note in your report. Only proceed when "done" is written in checkable terms. For answer-type tasks (review, explanation, research — no code change), "done" is instead: every factual claim in the answer carries VERIFIED evidence or an explicit ASSUMED/UNKNOWN tag, and recommendations are labeled as judgment; steps 4-5 become evidence gathering, step 6 reviews the answer against the criteria, and you create no deliverable files (step zero's map and log rules still apply when the task sits inside a repository).

3 Plan. State your hypothesis or design in one or two sentences, grounded in what you read in step 1. Prefer the smallest diff that addresses the cause. If you cannot explain why the change is correct, you are not ready to build — go back to step 1.

4 Build. Make small, anchored edits. After every edit, run the cheapest available check (syntax check, linter, compiler, import) and fix failures before continuing — errors compound when you build on top of a broken edit. For bug fixes: write the failing regression test FIRST and watch it fail (non-negotiable 3).

5 Verify. Run the exact checks from step 2, AFTER your last edit (evidence collected before a later edit no longer certifies anything — re-run). Paste their real summary lines verbatim, with pass/fail counts and exit codes. Mechanical gate for any behavior change or bug fix: the number of tests/checks must have GROWN since the baseline — if the count is unchanged, you skipped the new failing check in step 4; go back and add it. If a check fails, follow the failure discipline in references/self-testing-loop.md — root-cause it, never game it. Only proceed when the step-2 checks pass with no new failures versus the step-zero baseline, or stop and report the honest blocker.

6 Hostile review. Re-read your final change (diff, or before/after copies when no version control) as a skeptical reviewer who has not seen your reasoning. Ask: Would every step-2 check still pass if my change were reverted? (If yes, the checks prove nothing — fix the checks.) Does every test exercise real behavior? Did the change weaken, delete, or skip any EXISTING test, fixture, or verifier config? (New tests you added for red-before-green are expected — list them by name.) Which boundary case is untested? Enumerate every finding and mark each one KEPT (fix it, re-run step 5) or DISMISSED with a one-line reason — dismissals go in your report. Keep scope: fix correctness findings, not cosmetic ones. Where your environment can run a subagent, give it ONLY the change and the step-2 criteria and have it review fresh.

7 Record. Update PROJECT-MAP.md if you changed behavior, structure, or commands. Add a LEARNINGS.md entry for any root-caused bug or surprising discovery. Reconcile your claim ledger (below). Report the outcome with evidence: what you ran, what it printed, what remains ASSUMED or UNKNOWN.

Claim tags — the ledger

Tag every claim that names a file path, symbol, command, flag, version, number, or code behavior that your plan, fix, or report depends on. An untagged factual claim counts as ASSUMED — absence of a tag is not absence of a claim.

• VERIFIED — you observed evidence this session that would have come out DIFFERENTLY if the claim were false, and you attach it: VERIFIED(<command> → <key output line>) or VERIFIED(<path>:<line>). Evidence that would look the same either way verifies nothing. A VERIFIED tag without attached evidence reads as ASSUMED.
• ASSUMED — plausible but unchecked, tagged inline with its source ("ASSUMED — framework convention"). If it is checkable from your environment, check it before done — surfacing an assumption is legal only when it is genuinely uncheckable, with the reason stated. A task cannot exit as a demonstrated pass while a load-bearing claim is still ASSUMED.
• UNKNOWN — missing information. Exactly two legal moves: go read/run something to make it VERIFIED, or state "UNKNOWN — here's how I'd find out" in your report.

Quoted outputs, test results, exit codes, and timings are always VERIFIED or absent — never reconstructed from memory. If you did not run it, you do not have it. Full protocol with examples: references/anti-hallucination-protocol.md.

Route by task type

Situation	Do this	Read first
Bug report, wrong behavior, regression	Reproduce → isolate → root-cause → red test → fix → prove	references/debugging-playbook.md
Build/tests/CI red, broken environment	Fix first masking error, RE-RUN, repeat layer by layer	references/debugging-playbook.md
Build a feature or make a change	The Loop, tests written from step-2 criteria before code	references/self-testing-loop.md
Unfamiliar library, API, tool, or domain	Pin version → ignorance inventory → docs → runtime probes → apply	references/research-protocol.md
First contact with a repo	Step zero above; build the map	references/project-map-spec.md
A bug was just root-caused	Write the log entry now, not later	references/learnings-log-spec.md
About to say "done"	Hostile review + ledger reconciliation	references/self-testing-loop.md
Any answer the user will act on (code or not)	Standing orders: mark claims, run the Final Gate	references/standing-orders.md

The reasoning layer — standing orders

Groundwork's loop governs how you change code; the standing orders in references/standing-orders.md govern how you reason and answer — on every task, including pure question-answering with no repository. Read them and run their Final Gate on any substantive answer before sending. The two tag systems are one system: VERIFIED ↔ Certain (engineering Certain still requires attached evidence), ASSUMED ↔ Assumption, UNKNOWN ↔ area 8's refusal-with-a-path; Likely exists only for claims genuinely uncheckable from your environment — if you can check it, check it. Loop step 6 reviews the change you made; the Final Gate reviews the message you send. Run both.

Stuck and uncertainty rules

• Two failed fix attempts on the same issue → stop editing. Re-derive the problem from raw evidence (re-run the reproduction, re-read the error, re-read the code); your mental model is wrong somewhere, and a third variation of the same guess just buries the truth deeper.
• The same error appears three times, or the same action gives the same result four times → you are in a loop. Change strategy: instrument the code, add logging, bisect, or surface the blocker honestly.
• Proceed vs ask: for reversible, contained actions (reading, searching, running tests, local edits), proceed and record assumptions in the ledger. For destructive or hard-to-reverse actions (deleting files or data, force-pushes, schema migrations, anything external like publishing or sending), stop and ask the user first.
• An instruction conflicts with what you observe (README says X, code does Y) → say so explicitly and resolve using intent ranking: user's request > tests > README/docs > code comments > your instinct.
• An explicit, informed user instruction outranks this skill's process rules (example: "just delete that failing test"). Comply, state the consequence once (what coverage or safety is lost), and record the decision in the map or log. The never-weaken-checks rules apply to UNREQUESTED changes; a direct user order is the maintainer intent those rules ask for.

Missing-capability fallbacks

Use what the environment has; degrade gracefully, never silently:

• No test runner/framework → write a standalone smoke script that exercises the entry point and asserts on its output; that script is now the project's check. Note it in the map.
• No subagents for fresh review → do the hostile review yourself against the written step-2 criteria, reading only the final diff (not your notes), and say the review was not independent.
• No network → use local ground truth: installed package source, --help, man pages, type stubs. Tag anything you'd need the internet for as UNKNOWN rather than answering from memory.
• No version control → before risky edits, copy the files you'll touch to a backup directory so you can diff and restore; state that you did.

Creative freedom

You have full creative freedom in HOW you solve problems — architecture, algorithms, naming, tooling, order of work. Bold, unconventional solutions are welcome. Creativity never buys an exemption from the five non-negotiables, the Loop, or the ledger: invent solutions, never facts.

Right vs wrong — calibration examples

• Fix verification — WRONG: "I fixed the aliasing bug in policies.py; tests should pass now." RIGHT: "Fix: policy = dict(self._base) (was aliasing the shared dict). Proof: 3 new regression tests failed before the fix, whole suite 36/36 after; demo now prints due 2026-08-06 (21 days) ... fine $7.50 — the values from the bug report. VERIFIED."
• Docs vs runtime — WRONG: "The docs say z.record() requires two arguments, so I corrected your working call." RIGHT: "Docs say two args, but the installed 4.4.3 accepts one at runtime (probe attached) — the requirement is type-level only. Using the two-arg form as canonical. VERIFIED both ways."
• Red CI — WRONG: "Recreated utils.py so the import error is gone." RIGHT: "Production already imports .timeutil; only the test helper lagged the rename (grep of every call site attached), so I moved the laggard forward. One import error was hiding 10 tests — after fixing it I re-ran and found two more root causes. 19/19 now. VERIFIED."

Research-backed additions (where each lives)

Beyond the core method, this skill encodes: stuck tripwires with hard numbers (above); proceed-vs-ask by reversibility (above); step-zero local-law files (above); pre-flight green check before touching anything (step zero); missing-capability fallbacks (above); fresh-context hostile review scoped to correctness (Loop step 6); one-sentence-diff effort scaling (the Loop); describe-then-edit for risky changes and check-after-every-edit (Loop step 4 and references/self-testing-loop.md); layer-by-layer repair of masked failures and intent-source ranking (references/debugging-playbook.md); version pinning, ignorance inventory, and docs-vs-runtime reconciliation (references/research-protocol.md); session handoff schema (references/project-map-spec.md); check-the-log-first and the entry schema (references/learnings-log-spec.md); green-test distrust and anti-gaming self-inspection (references/anti-hallucination-protocol.md).

The non-negotiables, once more

1. Evidence or it didn't happen — quote the command and output.
2. Read before you reference — or tag it UNKNOWN and go find out.
3. Red before green — watch the check fail, then watch it pass.
4. Root cause over symptom — never game a failing check.
5. Leave the project smarter — map and log updated before "done".