Correction Pipeline
Convention: see conventions/brain-first.md — Step 1 of the root-cause chain IS the brain-first lookup chain (
searchfor exact tokens,queryfor 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
- Acknowledge the error. Don't defend. Don't explain. Just: "You're right. I got that wrong."
- Quote the specific wrong claim so the user can see you know exactly what was wrong.
- 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
bashgbrain 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:
bashBRAIN_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):
bashgrep -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
bashgrep -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
bashgbrain 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
| Classification | Description | Fix surface |
|---|---|---|
| BRAIN_ERROR | Wrong fact exists in a brain page | Edit the page in the brain repo, commit, re-sync |
| MEMORY_ERROR | Wrong fact exists in memory files | Fix the memory file |
| SOUL_USER_ERROR | Misleading passage in SOUL.md or USER.md | Fix the ANSWER BANK, re-render — never the rendered file |
| FACTS_TABLE_ERROR | Wrong fact in the gbrain facts table | recall → forget <fact-id> → remember the correction |
| HALLUCINATION | No source — LLM confabulated from partial signals | Name the contamination vector (what partial signals led to it), write a guard fact |
| STALE_DATA | Fact was once true but is no longer | Update the source with current truth; supersede the stale fact |
| CROSS_CONTAMINATION | Correct fact about person A attributed to person B | Fix attribution in the source — on BOTH entities |
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, thengbrain syncso 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:
The full interview discipline (read-back ritual, verbatim answers, backup behavior) lives inbashgbrain 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 fileskills/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:
bash
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:
bash
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+rememberwith 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.
bashgrep -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
| Tier | Description | Action |
|---|---|---|
| S1 — Identity error | Wrong facts about the user's family, heritage, history, core identity | Fix immediately. These contaminate EVERYTHING — every synthesis, every book mirror, every conversation. |
| S2 — Entity error | Wrong facts about a person, company, deal in the brain | Fix brain page, check propagation |
| S3 — Context error | Wrong inference about the user's current state, feelings, situation | Guard fact via remember. Usually hallucination. |
| S4 — Minor factual | Wrong date, wrong number, wrong detail | Fix source, no propagation check needed |
Recurring Error Patterns to Watch
| Pattern | Example | Guard |
|---|---|---|
| Projecting therapeutic narratives | "You've been avoiding the hard conversation with your cofounder" (no evidence) | Check calendar/behavior data before making claims about the user's actions or state |
| Autocorrecting names to famous people | A contact named alice-example Cho silently becomes the similarly-named celebrity | The user's people outrank world-famous people — resolve against people/ first |
| Confusing takes with facts | Dumping takes-table beliefs into facts | Takes = other people's beliefs. Facts = the user's personal knowledge. |
| Enumerative claims from session context only | "You've worked at two companies" — missing the one only recorded in the brain | NEVER make enumerative claims ("all your X," "every Y," "the three times you Z") without searching the brain first. Session context is always incomplete. |
| Missing data in always-loaded files | A core fact lives only in a brain page, not in USER.md/MEMORY.md, so every session re-derives it wrong | When a correction reveals a gap in an always-loaded file, ADD the missing data through the proper surface (answer bank for rendered files, direct edit for memory files) so it's in every future context window |
Complement: the contradictions probe
This skill is REACTIVE — it fires when the user catches an error. The shipped contradictions probe is the PROACTIVE side of the same discipline: it finds intra-brain conflicts before the user does.
bashgbrain eval suspected-contradictions # run the probe gbrain find-contradictions # read the latest run's findings
If a correction reveals a class of conflict (e.g. two pages disagreeing about a date), run the probe afterward — the same contamination pattern may exist elsewhere in the brain.
Contract
This skill guarantees:
- Every factual error gets root-caused, not just noted
- Source fixes land at the REAL fix surface for the error class (page edit +
commit + re-sync;
forget/rememberfor facts rows; answer bank + re-render for SOUL/USER — never a direct edit to a rendered file) - Propagation is checked (whole-brain grep +
gbrain search) - The user gets a clear report of what was wrong, why, and what was fixed
- Routing matches the canonical triggers in the frontmatter
- Privacy contract preserved: no real names, no fork-specific filesystem path literals, no upstream-fork references
Output Format
The skill's output is the Step 8 root-cause report delivered inline during the conversation, plus all source fixes applied (brain-repo edits committed and re-synced; facts rows expired/superseded; identity files re-rendered from the answer bank).
Dedup (sharp boundaries)
skills/maintain/SKILL.md— PROACTIVE brain health (stale pages, orphans, citations, doctor). This skill is REACTIVE: a specific user correction gets traced to its contamination source. If nobody said "that's wrong," it's maintain's territory.- The contradictions probe (
gbrain eval suspected-contradictions/gbrain find-contradictions) — PROACTIVE intra-brain conflict detection. Complementary, not overlapping: the probe finds conflicts between two brain sources; this skill starts from a correction supplied by the user. skills/soul-audit/SKILL.md— the full identity re-interview surface. This skill DELEGATES to it for SOUL_USER_ERROR fixes; it never re-implements the interview or render flow.skills/citation-fixer/SKILL.md— citation FORMAT compliance. Correcting a claim's truth is this skill; fixing how a true claim is cited is citation-fixer.- frontmatter-guard (host-side) — structural page validation (YAML shape), not claim truth.
Anti-Patterns
- "Noted, I'll remember that." NO. Trace the source. Fix the source.
- Fixing only memory without checking the brain. The brain is the persistent store. Memory gets flushed.
- Editing SOUL.md / USER.md directly. They're rendered from the answer bank; the hand edit dies on the next render and the error comes back. Fix the answer, re-render.
- Editing the brain-repo file without re-syncing (or the DB row without committing). The two stores drift and the next sync resurrects the error.
- Fixing one instance without checking propagation. Wrong facts spread.
- Blaming the hallucination without identifying the partial signal. Every hallucination has a seed — find it.
- Defensive response. Never explain why you got it wrong before acknowledging it's wrong.
