Doc Refactor

---
name: doc-refactor
description: Structurally refactor wiki pages — split a page into multiple, merge two or more into one, rename a slug across all references. Handles cross-reference updates automatically. Invoked when the user says "split this page", "merge these pages", "rename this slug", or "refactor the wiki".
triggers:
  - "split this page"
  - "merge these pages"
  - "rename this slug"
  - "refactor the wiki"
allowed-tools: Read, Write, Edit, Grep, Glob, Bash
---

# Refactor wiki pages

Three supported operations. Confirm the operation with the user before executing — structural edits are high-blast-radius.

## Split a page

Inputs: source page path, the new slug(s) + what-belongs-where guidance from the user.

1. Read the source page in full
2. Confirm with the user which sections go into which new page
3. Create each new page with full frontmatter (inheriting `owner:`, `status:`, `type:` from the source where sensible)
4. Rewrite the source page as a stub linking to the new pages, OR delete it if the user prefers
5. Find all inbound links to the source (`Grep` across ops root) — update each to point at the new page(s) they most logically reference. When ambiguous, ask the user
6. Update `index.md`
7. Append `log.md` with `event: refactor-split | <source-slug>`

## Merge pages

Inputs: two or more source pages + the target slug + the user's guidance on ordering / deduplication.

1. Read each source page
2. Draft the merged page: combine bodies, deduplicate claims, preserve the union of cross-references, keep a merged `## Changelog` if sources had one
3. Frontmatter: new `created:` = earliest of the sources; `updated:` = today; merge `owner:` manually if different
4. Write the target page
5. Replace each source page with a stub `# Moved → [new-slug](new-slug.md)` that is deleted after outbound link updates (or delete sources immediately — user's choice)
6. Update inbound links to sources → point at the target
7. Update `index.md` (remove old entries, add new)
8. Append `log.md` with `event: refactor-merge | <target-slug> (from <n> sources)`

## Rename a slug

Inputs: old slug, new slug.

1. Validate that the new slug is kebab-case and unique
2. Rename the file/folder on disk
3. Update the page's frontmatter `slug:` field
4. `Grep` all `[link](path)` and `[[slug]]` references across the ops root — update each
5. Update `index.md`
6. Append `log.md` with `event: refactor-rename | <old> → <new>`

## Guardrails

- Never execute a refactor without confirming the scope with the user
- Always bump `updated:` on every touched page
- If a referencing page has a `## Changelog`, append a note: `renamed <old> → <new>` on YYYY-MM-DD
- If the user hasn't committed recent changes, warn them before starting — refactors have wide blast radius
- If the wiki is large (>50 pages) prefer running as the `memex-linter` subagent in worktree isolation so the main session doesn't inherit the churn
- If `memex-docsite serve` is running, refactored URLs may break readers' open tabs — call out renames in the user-facing summary so they can refresh