Correction Root-Cause Pipeline

Correction Pipeline

Convention: see conventions/brain-first.md — Step 1 of the root-cause chain IS the brain-first lookup chain (search for exact tokens, query for concept-shaped questions) before anything else.

Convention: see _brain-filing-rules.md — corrections edit pages in place; the page stays filed by primary subject.

Trigger

ANY factual error the user identifies. No exceptions. No "I'll note that."

(Routing here is a harness convention, not a mechanical guarantee — but once this skill is in play, the no-exceptions contract above is the discipline.)

Immediate Response

1. Acknowledge the error. Don't defend. Don't explain. Just: "You're right. I got that wrong."
2. Quote the specific wrong claim so the user can see you know exactly what was wrong.
3. State the correct fact as the user gave it.

Root Cause Analysis (do THIS, not just a memory note)

Run these steps IN ORDER. Report findings to the user.

Step 1: Search the brain

gbrain search "<relevant terms>" --limit 10

For concept-shaped or synonym-phrased claims, escalate to gbrain query "<question>" (LLM expansion recovers phrasings search misses). Also grep the brain repo checkout directly — resolve it once from config:

BRAIN_DIR=$(gbrain config get sync.repo_path)
grep -ri "<wrong claim terms>" "$BRAIN_DIR/people/" "$BRAIN_DIR/companies/" "$BRAIN_DIR/concepts/" 2>/dev/null

Question: Is the wrong fact IN the brain? If yes → the brain is the contamination source. Fix the brain page (Step 6).

Step 2: Search memory files

Grep the harness's always-loaded memory files (e.g. the workspace MEMORY.md and any memory/*.md companions — the exact location depends on your harness):

grep -ri "<wrong claim terms>" <memory files> 2>/dev/null

Question: Is the wrong fact in memory? If yes → memory is the contamination source. Fix the memory file.

Step 3: Check SOUL.md and USER.md

grep -i "<relevant terms>" <workspace>/SOUL.md <workspace>/USER.md 2>/dev/null

Question: Is there a misleading passage that could have led to the wrong inference? SOUL.md and USER.md are in every context window — a vague or ambiguous line here propagates into every session.

Important: on gbrain installs these files are RENDERED from the bootstrap answer bank (state/interview.json). Note the finding here; the fix goes through the answer bank in Step 6, never through a direct edit.

Step 4: Check the facts table

gbrain recall <entity-slug>            # facts about the subject, newest first
gbrain recall --grep "<claim terms>"   # substring filter when the entity is unclear

Is there a wrong fact with high confidence? Note its fact id.

Step 5: Classify the error

Step 6: Fix the source

• BRAIN_ERROR: Edit the page file in the brain repo. Include [Source: user correction, YYYY-MM-DD] on the corrected line. Commit, then gbrain sync so the DB reflects the fix. (Editing the DB row without the repo file — or vice versa — leaves the two out of agreement until the next sync overwrites one of them.)
• MEMORY_ERROR: Edit the memory file. Add a correction note with date.
• SOUL_USER_ERROR: NEVER edit SOUL.md / USER.md directly — they are rendered files, and a hand edit is silently lost on the next render. Fix the underlying answer in the shared bootstrap answer bank, then re-render:

  gbrain bootstrap interview --set KEY "corrected value"   # verbatim, user's words
  gbrain bootstrap interview --show                        # read back
  gbrain bootstrap interview --status                      # get the confirm hash
  gbrain bootstrap interview --confirm <hash>
  gbrain bootstrap render --only SOUL.md --force           # repeat per affected file

  The full interview discipline (read-back ritual, verbatim answers, backup behavior) lives in skills/soul-audit/SKILL.md — route through it for anything beyond a single-key fix.
• FACTS_TABLE_ERROR: Expire the wrong row and write the correction with provenance:

  gbrain recall <entity-slug>                                  # find the fact id
  gbrain forget <fact-id>                                      # expire the wrong fact
  gbrain remember "<correct fact>" \
    --provenance "user correction, YYYY-MM-DD" --entity <entity-slug>

• HALLUCINATION: There is no source to fix. Identify the partial signal that seeded the confabulation, then write a guard so it can't reseed:

  gbrain remember "WRONG: <what was said>. RIGHT: <what is true>. Guard: <instruction to prevent recurrence>" \
    --provenance "user correction, YYYY-MM-DD (hallucination guard)" --entity <entity-slug>

• STALE_DATA: Update the source page with current truth (BRAIN_ERROR flow), and supersede any stale facts rows (forget + remember with the current truth and fresh provenance).
• CROSS_CONTAMINATION: Fix the attribution at the source, then check BOTH entities: person A's page and facts (does the fact now live where it belongs?) and person B's page and facts (is every trace of the misattribution gone?).

Step 7: Check for propagation

The wrong fact may have propagated into OTHER brain pages, synthesis output, or memory files.

grep -ri "<wrong claim terms>" "$BRAIN_DIR" 2>/dev/null | grep -v ".git"
gbrain search "<wrong claim terms>" --limit 20

Fix ALL instances, not just the first one found. Re-sync after repo edits.

Step 8: Report to the user

Short report:

**Error:** [what was wrong]
**Root cause:** [BRAIN_ERROR | HALLUCINATION | etc.]
**Source:** [specific file/line or fact id, or "no source — confabulated from X"]
**Fixed:** [what was changed, where]
**Propagation:** [other files fixed, or "no propagation found"]

Severity Tiers