correction-pipeline

# Correction Pipeline > **Convention:** see [conventions/brain-first.md](../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](../_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 ```bash 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: ```bash 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): ```bash 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 ```bash 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 ```bash 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 | 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, 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: ```bash 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: ```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` + `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. ```bash 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 | 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. ```bash gbrain 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`/`remember` for 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. ## When it fails Follow the [agent operator protocol](../conventions/agent-operator-protocol.md) for any gbrain error `code`, exit code, `[AGENT]` block or notice block. Specific to this skill: - `forget <fact-id>` / `remember` returns `fact_not_found` or `fact_already_expired`: re-run `recall` to get the current fact id; never forget by guessing an id. - A page fix returns `revision_conflict`: re-read the page, apply the correction to the current text, and save with the new revision. - `write_pending` (exit 10): the correction is accepted but not committed; poll `gbrain write-request <request_id>` before telling the user it is fixed. ## 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.