| name | neuro-surgery |
| description | HITL-driven repair of the knowledge base, operating on the latest /neuro-scan report. Use this whenever the user says /neuro-surgery, asks to fix failures, resolve ontology inconsistencies, re-synthesize stale wiki pages, coordinate recursive-self-improvement execution, or review deep-reasoning proposals. Also trigger when the user says "fix the scan report", "clean up the failures", "audit contradictions", or wants to work through the backlog interactively. Every single write to 02-KB-main/ or 03-Ontology-main/ requires explicit user approval per-change — never batch approvals, never apply silently. Skilled at diffs: shows before/after side-by-side, waits for thumb up, then applies via schema-aware tools (nlr_wiki_update / reasoning-ontology — never bare Write or tv_edit_note on schema-bound paths). |
/neuro-surgery
Interactive repair skill. Pulls from the latest /neuro-scan report in 06-Recursive/daily.md and walks through fixable findings with the user one at a time. Every knowledge-artifact edit is thumbs-up gated.
Design principle: the surgery is slow on purpose. The brain's quality depends on humans trusting that 02-KB-main/ and 03-Ontology-main/ aren't silently mutating. A per-change approval protocol trades speed for trust.
Operating modes
The user invokes this skill after /neuro-scan has produced a report. The skill reads that report and offers options:
Scan report from YYYY-MM-DD HH:MM. What do you want to repair?
1. Failures (N recurring, M new)
2. Knowledge gaps (N stale hubs, N isolated clusters, N ontology contradictions)
3. Stale wikis (top 10)
4. Approved self-improvement proposals (N awaiting execution)
5. Upstream doc drift (N repos)
6. Deep-reasoning proposals (N awaiting review)
Type numbers (e.g., "1 3 5") or "all".
Work through selected sections one item at a time. Never batch-process.
Per-item protocol
For each item, follow this exact loop:
Step 1 — Diagnose
Read the item. Read related context (cited log entries, affected wiki pages, referenced ontology nodes). Form a hypothesis of what's wrong and why.
Step 2 — Propose
Tell the user:
- What: one-sentence diagnosis
- Why: causal story (grounded in citations, not speculation)
- Fix: the exact change you'd make, as a diff
- Risk: low | medium | high + reasoning
- Rollback: how to undo if it makes things worse
Step 3 — Wait for decision
The user types apply, skip, modify <instruction>, or stop. Honor whichever one they picked:
apply — execute via schema-aware tool (next step)skip — record as skipped in surgery log, move onmodify X — update the proposal per X, re-show, loop back to step 3stop — exit the surgery session cleanly
Step 4 — Execute (apply only)
Route to the right executor:
| Target | Executor |
|---|
02-KB-main/*.md content | nlr_wiki_update (preserves schema frontmatter) |
02-KB-main/*.md frontmatter only | nlr_wiki_update with --frontmatter-only |
03-Ontology-main/**/*.md | /reasoning-ontology update <path> |
| Broken wikilink in content | tv_edit_note with SEARCH/REPLACE block (safe: only touches link text) |
Task spec in 00-neuro-link/tasks/ | direct Edit (these have no schema) |
Config in config/*.md frontmatter | direct Edit, frontmatter only |
Never use Write or tv_write_note to replace a 02-KB-main/ or 03-Ontology-main/ file wholesale — that's how frontmatter gets silently dropped.
Step 5 — Verify
After the write, re-read the target. Confirm:
- Frontmatter schema intact (for
02-KB-main/)
- Wikilinks still resolve (run
tv_get_broken_links scoped to the edited path)
- No accidental deletion (diff byte count vs pre-edit)
If any check fails, roll back using the rollback command from the proposal and report to the user.
Step 6 — Log
Append to 06-Recursive/daily.md under today's "Surgery log" subsection:
- HH:MM <item> — applied | skipped | rolled-back
- Target: <path>
- Change: <one-line diff summary>
- Rollback: <command>
Deep-reasoning proposals
When /neuro-scan flags topics where 3+ sources disagree, it produces a deep-reasoning task. Surgery doesn't fix these in-place — they require genuine thought. Instead:
- Present the contradiction clearly (cite each source)
- Ask the user if they want to commission a research task
- If yes, draft a task spec in
00-neuro-link/tasks/ with type: deep-reasoning and dispatch to /scientific-critical-thinking or /hypothesis-generation (choose based on whether the question is about evidence quality or mechanism)
- The eventual output lands in
05-insights-HITL/, not 02-KB-main/ — because it's a reasoning artifact, not consensus knowledge
See references/resynthesis-guide.md for how to frame contradiction reports and when to escalate to a commission vs resolve in-place.
Approved self-improvement proposals
For items from /recursive-self-improvement with status: approved, the surgery step is usually trivial — the proposal already has a diff and rollback. Verify the diff still applies cleanly (base file hasn't changed since approval), then apply. If the base has drifted, route back to /recursive-self-improvement review to re-examine.
HITL protocol — non-negotiable rules
These are absolute. If the user presses to bypass, refuse and explain why.
- Every edit to
02-KB-main/ or 03-Ontology-main/ requires explicit per-change approval. Not batch. Not "all low-risk". One at a time.
- Never use
Write on a schema-bound file. Always route through the schema-aware tool. If the schema-aware tool refuses, the fix needs re-proposal, not bypass.
- Always write a rollback command before applying. If you can't write one, the change isn't safe enough to apply.
- Log every surgery action, even skips. Without a log, the brain can't grade itself tomorrow.
References
references/hitl-protocol.md — full protocol with examples of correct and incorrect handlingreferences/resynthesis-guide.md — when to re-synthesize vs surface-patch vs commission deep reasoningreferences/rollback-patterns.md — writing rollback commands for each target type
Scripts
scripts/verify_frontmatter.sh — post-edit schema checkscripts/write_surgery_log.sh — append a log entry in the canonical format
