kb-rebuild

name	kb-rebuild
description	Regenerate all wiki pages from raw sources — breaks slop accumulation. Uses staged rebuild with diff review. human_reviewed pages are preserved. Use when the user wants to rebuild or regenerate their KB wiki. Also triggers on "kb-rebuild" or "/kb-rebuild".

kb-rebuild

Regenerate all wiki pages from raw sources to break slop accumulation. Uses a staged rebuild process with diff review before applying changes. Pages with human_reviewed: true are always preserved.

This is a destructive operation. The staged approach ensures nothing is lost without user confirmation.

Step 1: Resolve KB

python3 ~/.config/kb/scripts/kb_resolve.py --mode mutating

Capture the KB root path. Abort if resolution fails.

Step 2: Safety Gate

Present a clear warning to the user:

WARNING: kb-rebuild will regenerate ALL wiki pages from raw sources.

- human_reviewed pages will be PRESERVED (not regenerated).
- All other pages will be regenerated from scratch.
- Changes are staged for your review before applying.
- A backup of the current wiki/ is created.

This is token-expensive and may take significant time.
Proceed? (yes/no)

Abort if the user declines.

Step 3: Collect Protected Pages

Scan all wiki pages and identify those with human_reviewed: true in frontmatter. Build the protected set:

1. Read every file in wiki/entities/, wiki/concepts/, wiki/summaries/, wiki/synthesis/.
2. Parse frontmatter for each file.
3. Collect paths where human_reviewed: true into a list.
4. Also collect paths where stability: permanent (treat as protected).

Print the protected set:

## Protected Pages (will not be regenerated)

- wiki/entities/important-entity.md (human_reviewed)
- wiki/concepts/core-concept.md (human_reviewed)
- wiki/concepts/established-fact.md (permanent stability)

Step 4: Backup Current Wiki

Create a timestamped backup:

cp -r "{{KB_ROOT}}/wiki" "{{KB_ROOT}}/.wiki-backup-$(date +%Y%m%d-%H%M%S)"

Confirm the backup was created and print its path.

Step 5: Regenerate into Staging Directory

Create a staging directory:

mkdir -p "{{KB_ROOT}}/.wiki-rebuild-staging"

Regenerate summaries

For each raw source in raw/:

1. Read the raw source content.
2. Generate a fresh summary page with full frontmatter.
3. Write to .wiki-rebuild-staging/summaries/<slug>.md.
4. Preserve the original created date from the existing page (if it exists).
5. Set last_verified to today.

Regenerate entities

1. Read all raw sources.
2. Extract entities across all sources.
3. Generate entity pages, merging information from all sources that mention each entity.
4. Write to .wiki-rebuild-staging/entities/<slug>.md.
5. Skip entities in the protected set — copy the existing page as-is into staging.

Regenerate concepts

1. Same approach as entities.
2. Write to .wiki-rebuild-staging/concepts/<slug>.md.
3. Skip protected set.

Regenerate synthesis

1. For synthesis pages NOT in the protected set: regenerate from the source pages they reference.
2. For protected synthesis pages: copy as-is into staging.
3. Write to .wiki-rebuild-staging/synthesis/<slug>.md.

Preserve contradictions

For each regenerated page, check if the corresponding existing page had contradictions entries. Carry those forward into the regenerated frontmatter. Do not silently drop contradiction records.

Step 6: Present Diff

Compare staging against current wiki:

1. For each file in staging, diff against the corresponding file in wiki/.
2. Categorize changes:
   • New pages: exist in staging but not in current wiki.
   • Modified pages: exist in both but content differs.
   • Removed pages: exist in current wiki but not in staging (and not protected).
3. Present a summary:

## Rebuild Diff

### New pages ({{N}})
- .wiki-rebuild-staging/entities/new-entity.md

### Modified pages ({{N}})
- wiki/summaries/source-summary.md — 15 lines changed

### Pages to remove ({{N}})
- wiki/entities/stale-entity.md — not generated from any current raw source

### Protected (unchanged) ({{N}})
- wiki/entities/important-entity.md

4. For modified pages with significant changes, show a brief diff summary (key additions/removals).

Ask the user: "Apply these changes? (yes/no/review-details)"

If "review-details": show full diffs for each modified page, then ask again.

Step 7: Apply Changes

If the user confirms:

1. For each file in the protected set: do nothing (leave current wiki page untouched).
2. For all other files: replace the current wiki file with the staging version.
3. For pages marked for removal: move to wiki/deprecated/ with a tombstone header.
4. Update inbound wikilinks for any removed/deprecated pages.

Step 8: Regenerate Index

python3 ~/.config/kb/scripts/kb_index.py "{{KB_ROOT}}"

Step 9: Append Log

Add a row to log.md:

| {{DATE}} | rebuild | Full rebuild from {{N}} raw sources → {{P}} pages regenerated, {{R}} protected, {{D}} deprecated |

Step 10: Cleanup

Remove the staging directory:

rm -rf "{{KB_ROOT}}/.wiki-rebuild-staging"

Print the backup path for reference: "Backup preserved at {{BACKUP_PATH}}. Delete manually when satisfied."

Final Output

Print:

• Total raw sources processed.
• Pages regenerated (count).
• Pages protected and preserved (count).
• Pages deprecated (count).
• Backup location.
• Suggestion: "Run kb-lint to verify the rebuilt KB. Delete the backup when satisfied."