zero-hallucination-coder

---
name: zero-hallucination-coder
description: Use when a coding task is high-stakes or complex, or touches existing code (auth, databases, migrations, multi-file features), or the user asks to plan carefully and avoid hallucinated code.
category: Engineering
version: 1.0.0
tools: []
---

# Zero-Hallucination Coder

Disciplined, senior-engineering-partner approach for code that is correct, grounded, and complete — zero invented APIs, zero skipped steps, zero hallucinated behavior.

## When to Invoke (opt-in discipline)

This is a deliberate, opt-in pipeline, not the default for every edit. Reach for it when:
- The task is high-stakes or hard to undo (migrations, schema/auth changes, deployments).
- It spans existing code across multiple files, or touches external APIs, auth, databases, or state.
- The user explicitly asks to "plan carefully," "avoid hallucinated code," or "do this rigorously."

For a typo, a reformat, or a throwaway script, skip the loop — the ceremony costs more than it saves. The seven Anti-Hallucination Rules below still apply everywhere, but the five-phase loop is reserved for work that earns it.

## Foundations

Four ideas power this loop: a PRD-driven atomic coding loop that implements one story at a time in fresh context and commits only when quality checks pass (the Ralph pattern); a Discuss → Plan → Execute → Verify → Ship discipline using structured memory to prevent "context rot" (the GSD Core pattern); explicit KNOWN/INFERRED/UNKNOWN tagging of codebase relationships so reasoning stays grounded in real structure, not guesses (the Graphify pattern); and a lazy-senior-dev hierarchy that checks whether code needs to exist at all before writing it, typically producing 80-94% less code (the Ponytail pattern).

## Before Starting

Check for context first: if the project's context has already been established in this conversation, or can be found via knowledge_base_search, use it and only ask about the gaps.

## Modes

- **Build from scratch** — no existing codebase. Run all five phases.
- **Extend existing code** — the relevant code must be shared before Phase 2 (Map) can run. Ask only for the files that matter, not the whole codebase.
- **Debug or refactor** — abbreviated loop: Discuss → Map (read the broken code) → Execute (targeted fix) → Verify.

## The Five-Phase Loop

Every session runs all five phases in order. Skipping phases is the primary cause of hallucinated, broken, or incomplete code.

### Phase 1: Discuss
Capture what is actually being built before any planning happens. Ask and fully resolve, in a single message:
1. What is the end state? Describe the working thing, not the steps to get there.
2. What tech stack, language, and major libraries are in use? (Do not assume.)
3. Does existing code exist that this touches? If yes, ask for it.
4. What are the hard constraints? (Must run on X, must use Y, must not break Z.)
5. What does "done" look like — how will we know this works?

Don't start planning until questions 1, 2, and 5 are answered. If the user says "just write the code," explain briefly why skipping Discuss produces broken output and ask once more; if they insist, proceed with explicit UNKNOWN tags everywhere. Output: a one-paragraph Situation Summary the user confirms before moving forward.

### Phase 2: Map
Build a codebase map before writing a single line of code (the Graphify principle). For existing code, tag every relationship [KNOWN] (confirmed by the user), [INFERRED] (assumed from naming or convention, not confirmed), or [UNKNOWN] (not verified — must be resolved). For greenfield projects, sketch the proposed architecture as a dependency map with the same tagging: every external library or API is [KNOWN] (version confirmed) or [ASSUMED] (library known, version/API unconfirmed).

Hard rule: never write code that depends on an [UNKNOWN]. Resolve all UNKNOWN flags before Phase 3. Output: a written codebase map with no unresolved UNKNOWN flags.

### Phase 3: Decompose
Break the task into atomic stories, each small enough to fit in one response (the Ralph principle). For each story, capture: what gets built, the acceptance criteria, its dependencies, its risk, and a complexity rating (LOW/MED/HIGH).

Right-sizing rule: split a story if it needs more than 300 lines, touches more than 3 files, or has more than 2 acceptance criteria. "Build the authentication system" is too big; "Add `validateToken(token: string): boolean` to AuthService" is right-sized. Output: a numbered story list the user confirms or adjusts before execution begins.

### Phase 3.5: Ponytail Check (before every story)
The best code is the code you never wrote (the Ponytail principle). Before implementing any story, work down this six-rung ladder and stop at the first rung that holds:
1. Does this code need to exist at all? YAGNI test — required by an acceptance criterion, or speculative? If speculative, kill it.
2. Does the stdlib/language already do this? (array methods, datetime, pathlib, json, re…) If yes, use it.
3. Does a native platform/runtime feature do this? (fetch, localStorage, fs, crypto, stream…) If yes, use it.
4. Does an already-confirmed [KNOWN] dependency do this? If yes, use it.
5. Can this be a trivial one-liner? If yes, write it inline — no abstraction yet.
6. Write the minimum that works: no premature abstraction, no config system for one hardcoded value, no base class for one subclass, no defensive layers for hypothetical futures.

Never on the chopping block: input validation at trust boundaries, error handling for data loss, security checks, accessibility in UI code, data integrity constraints. Output: a brief note on which rung stopped the search; any shortcut gets an inline comment naming the reason and the upgrade path, so deferred debt stays visible.

### Phase 4: Execute
Implement exactly one story at a time with no hallucinated dependencies (Ralph + GSD Core).
- **Pre-check:** confirm every dependency from the story list, mark every API/method this code calls as KNOWN, ASSUMED, or UNKNOWN, and list the files touched. Stop and resolve any UNKNOWN before writing code.
- **Write the code:** complete, runnable implementation — no placeholders, no TODOs, no "...rest of implementation." Every function is fully implemented or explicitly out of scope with a written reason. Imports must be real — never invent package names. If a method's existence is uncertain, mark it "ASSUMED: verify this method exists in your version."
- **Self-review:** does this do exactly what the story specifies? Any invented method names or APIs? Any assumed behavior depending on unseen code? Does it break anything in the codebase map? Are the acceptance criteria met? Verdict: ready to test, or needs revision (with reason).
- **Handoff note:** one sentence on what was built, exact steps to test it (not "it should work"), edge cases or fragile assumptions to watch, and the next story.

Don't proceed to the next story until the user confirms the current one passes.

### Phase 5: Verify
Before declaring done, walk through what was built vs what was planned (GSD Core). Restate the original end state from Phase 1, then for each story compare the planned acceptance criteria to the actual behavior and record any gap. List outstanding issues. If any story has a gap, write a micro-story to close it and run Phase 4 again for that gap only.

## Anti-Hallucination Rules (always on, even when short-circuiting)

1. No invented APIs — if uncertain a method exists in the stated library version, ask, or mark it "ASSUMED: verify this method exists."
2. No assumed imports — every import must correspond to a package the user has confirmed exists in their project.
3. No placeholder code — TODOs, `pass`, or "not implemented" stubs are forbidden unless explicitly scoped out as a new story.
4. No skipping to the end — stories are sequential; no final integration before individual components work.
5. No silent assumptions — every assumption is written down and tagged ASSUMED or UNKNOWN.
6. One story per turn — don't batch multiple stories into one response unless they are trivially small (under 20 lines each, no shared dependencies).
7. Fresh reasoning per story — re-read the codebase map and previous handoff note before each new story; don't rely on memory of what was written two stories ago.

## Context Engineering Rules

Prevents "context rot" — the silent quality degradation as the context window fills:
- After each story, update the codebase map with what was added.
- At the start of each story, restate the end state from Phase 1 in one sentence to prevent drift.
- Ask "is this the current version?" if several turns have passed since code was shared.
- If accuracy may be degrading due to conversation length, say so explicitly and ask for the relevant file to be reshared.

## When to Short-Circuit

- **Full loop required:** touches existing code across multiple files; involves external APIs, auth, databases, or state; more than 3 acceptance criteria; mistakes would be hard to undo.
- **Abbreviated loop (Discuss + Execute + Verify):** standalone utility with no external deps; clearly scoped bug fix in shown code; data transformation with no side effects.
- **Just execute:** fixing a typo, reformatting, linting, adding a docstring.

## Proactive Triggers

Surface these without being asked when noticed:
- Context rot warning — conversation very long → flag it and offer to have the state reshared.
- UNKNOWN bleed — a referenced dependency isn't yet mapped → pause and tag it.
- Story too large — a requested story would touch more than 3 files → split it before coding.
- Ponytail kill — an entire story can be eliminated by stdlib/native/an already-confirmed dependency → report it before writing anything.

## Output Artifacts

A new feature gets a Situation Summary → Codebase Map → Story List → story-by-story code with self-review and handoff → Verification Report. A bug fix gets a map of the broken code → a targeted micro-story → a fix with minimal diff → verification. A code review gets codebase-map annotations (KNOWN/INFERRED/UNKNOWN) plus a gap list and prioritized fix stories. An architecture plan gets a decomposed story list with dependency order, complexity ratings, and Ponytail elimination notes.