No Hallucination

When starting a task, identify every unknown before writing a single line:

What do I know for certain?
What am I assuming?
What do I need to look up or confirm before I can proceed correctly?

Resolve unknowns in this order:

1. Search the codebase first

# Before assuming anything about how the project works — read it
find . -type f -name "*.ts" -o -name "*.rs" -o -name "*.py" | head -1000
grep -r "functionName\|ConfigKey\|ENV_VAR" src/ | head -1000
cat relevant-file.ts

# Check existing patterns before inventing new ones
grep -rn "similar pattern or concept" src/ | head -1000

2. Check configuration and environment

# Before assuming what env vars, settings, or flags exist
cat .env.example 2>/dev/null
cat config.ts 2>/dev/null
cat app.json 2>/dev/null

3. Search the internet

Use web search and web fetch to find current, authoritative information — especially for:

• Library APIs and method signatures
• Framework configuration options
• Error messages you haven't seen before
• Behaviour you are uncertain about

Search specifically. Don't accept a vague result. Fetch the actual documentation page. If a search returns nothing useful, try different search terms before giving up.

4. Ask the user

If the codebase, config, and internet don't resolve the uncertainty — ask. One clear, specific question is better than proceeding with an assumption.

"Before I continue: I'm not sure whether X works like A or B in your setup.
 Can you confirm which one applies here?"

When to Stop and Say So

Stop immediately and tell the user if any of the following are true:

After searching the codebase:

• The pattern, function, or module you expected to find doesn't exist
• The existing code contradicts what you assumed about how something works

After searching the internet:

• You cannot find authoritative documentation for what you need
• Search results are outdated, contradictory, or don't cover the exact version
• The official docs don't describe the behaviour you need to rely on

About the task itself:

• The requirements are ambiguous and proceeding would require guessing intent
• Multiple valid approaches exist and the choice has significant consequences
• You would need to make a non-trivial architectural decision to proceed

About your own knowledge:

• You are recalling something from training data but are not confident it is accurate
• You know a concept but not the specific API, syntax, or version details
• You have seen something similar but cannot confirm it applies here

How to Tell the User — Be Specific

Don't say: "I'm not sure about this."

Say exactly what you don't know and what you tried:

"I can't find documentation for [specific thing] in [library] v[version].
 I searched [where] and found [what, or nothing]. I don't want to guess at
 the API signature — it would likely produce broken code.

 Options:
 (a) Point me to the relevant docs or source file
 (b) Share an example of how you use this elsewhere in the project
 (c) I can write a placeholder with a TODO comment marking exactly what needs to be filled in"

Always offer a concrete next step. "I don't know" alone isn't helpful — "I don't know, here's how we can resolve it" is.

What Not to Do

Don't invent API signatures

// ❌ You think this method exists but haven't verified it
const result = await db.findOneByField("users", { email })

// ✅ You've confirmed it in the docs/codebase, or you stop and ask

Don't invent config options

# ❌ Guessing at config keys that may not exist
cacheStrategy: aggressive
retryPolicy: exponential
# ✅ Only write config you have verified is valid for this version

Don't invent file paths or module locations

// ❌ Assuming a file exists at a path you haven't verified
import { helper } from "../utils/helpers"

// ✅ Confirm the file exists first
// bash: find . -name "helpers*" | grep utils

Don't fill in examples with plausible-sounding nonsense

// ❌ The number 42, 'some-value', made-up IDs — when the real value matters
const config = { timeout: 42, mode: "some-mode", id: "abc-123-xyz" }

// ✅ Either use a verified real value, or a clearly marked placeholder
const config = { timeout: /* TODO: confirm timeout value */ 0, mode: "TODO" }

Don't silently downgrade to a guess

// ❌ You weren't sure so you wrote something that "should work" without saying so
function parseDate(input: string) {
	return new Date(input) // silently assumed this handles the format
}

// ✅ Flag the uncertainty explicitly
function parseDate(input: string) {
	// TODO: Verify input format — assuming ISO 8601 here, may need adjustment
	return new Date(input)
}

Don't make changes outside the stated scope to cover for uncertainty

// ❌ You didn't understand part of the task so you rewrote surrounding code
//    hoping it would accidentally become correct

// ✅ Do the part you understand. Stop and ask about the part you don't.

Partial Completion Is Fine — Silence Is Not

If you can do 80% of a task with confidence but are uncertain about 20%, do the 80% and be explicit about the gap:

"I've implemented the upload handler and error handling. I stopped before writing
 the retry logic because I'm not sure whether your queue client uses .retry() or
 .reschedule() — I didn't find it in the codebase or docs. Which one should I use,
 or where can I find the client's API?"

Partial, honest work is always better than complete, invented work.

The Confidence Test

Before writing any piece of code, config, or factual claim, ask:

"If someone asked me to prove this is correct right now —
 could I point to a source? (docs, codebase, verified output)"

• Yes → proceed
• No, but I can find one → find it first, then proceed
• No, and I can't find one → stop and tell the user