Fix Hallucinated Code + Cleanup Source

When to use

An agent changed code based on something it read that was wrong or outdated. The code change needs to be undone, AND the thing that misled the agent needs to be found and fixed so it never happens again.

Phase 1: Identify the hallucinated code

Read the commit diff. For each change, ask: does this look like it's reversing something intentional? Signs:

• Commit message says "restore", "revert", "fix regression"
• The diff puts BACK old values that were explicitly removed
• Comments in the old code say "removed", "deprecated", "disabled" — and the agent re-enabled it
• Test expectations changed to match old behavior instead of new behavior

Phase 2: Predict intent, confirm with admin

For each hallucinated change, state what it looks like the human intentionally did, in plain language. No jargon. No variable names. Describe what the user of the product experiences.

Format: "Looks like you intentionally [what changed in UX terms]. An agent reversed it. Right?"

Do NOT proceed until the person you're working with confirms.

Phase 3: Fix the code

• Revert the agent's hallucinated commits or manually restore the correct state
• Add @intent: [slug] — [plain language why] comments near each restored setting
• Commit with: fix: restore [what] — agent incorrectly reverted [what was reverted]

Phase 4: Trace the source with /hallucination

For each hallucinated change, find the EXACT thing that misled the agent:

• Old TDD test asserting wrong behavior → file:line, test name
• Dead feature flag with misleading name/value → file:line
• Stale comment describing removed feature → file:line
• Wrong entry in a memory file, intent tracker, or session note → file/ID
• Stale compaction or session summary making a false assertion → compaction ID
• Misleading variable name → file:line
• CLAUDE.md rule describing old architecture → line number

Search sources, in order of what's actually available:

1. Always available — search what's already on the machine:

   # Project instructions and rules
   grep -rn "[search term]" CLAUDE.md ~/.claude/CLAUDE.md 2>/dev/null
   
   # Any memory files the harness or the person keeps
   grep -rln "[search term]" ~/.claude/projects/*/memory/*.md 2>/dev/null
   
   # Past session transcripts (this is where a misleading instruction is often recorded word for word)
   grep -l "[search term]" ~/.claude/projects/*/*.jsonl 2>/dev/null
   
   # git history — when and why the "correct" behavior was introduced
   git log -S "[search term]" --oneline
   

2. If a memory/institutional search tool is configured (see /alignment-harness:harness-setup — this is optional and most people won't have one): run it with the search term and treat its hits the same as the local sources above.
3. If a local intent tracker or compaction store is configured (alignment-harness records intent / alignment-harness records compactions — see harness-setup): search those folders for the term instead of a live database.

If none of these turn anything up, say so plainly rather than guessing — an unfound source is not the same as a confirmed absence of one.

Phase 5: Clean up the source

For each source found:

• Wrong TDD test: Update to assert correct behavior, or delete if the test no longer applies
• Dead feature flag: Remove entirely. No tombstone. No "set to true to re-enable."
• Stale comment: Delete it
• Wrong memory-file or intent-tracker entry: Report it to the person for deletion (do NOT delete autonomously)
• Stale compaction or session summary: Report it to the person (do NOT delete autonomously)
• Misleading variable name: Rename to reflect current truth
• Wrong CLAUDE.md rule: Update to reflect current architecture

Commit source cleanup separately: fix: cleanup hallucination sources — [what was stale]

Rules

• Do NOT remove "unused" code — it may be WIP
• Do NOT delete shared memory, intent-tracker entries, or compactions — report them for the person's review
• Do NOT change anything unrelated to the hallucination being fixed
• git add ONLY specific files — NEVER git add -A
• Do NOT push
• Sign the commit as whatever model is actually running this session, e.g. Co-Authored-By: <model name> <person@example.com>