wiki-refactor

wiki-refactor — conductor

Full-wiki refactor: eliminate duplication, improve IA, elevate prose quality. HARD gate with 3 PRD checkpoints and a human checkpoint after Phase 4. Wrong skill? Single-page edit → wiki-orchestrator · Content coherence → wiki-content-coherence · Link check → link-verification. Background: rationale.md.

When to Use

• When asked to do a full-wiki refactor: eliminate duplication, improve information architecture, or elevate prose quality across many pages
• Triggered by: refactor wiki, wiki overhaul, reorganize wiki pages, wiki:refactor, reorganize all wiki pages
• Wrong skill? Single-page edit → wiki-orchestrator · Page-level coherence → wiki-content-coherence

🔴 PRD protection (non-negotiable)

Detect PRD pages (case-insensitive): filename/title contains PRD; body H1/H2 exactly PRD; body header Product Requirements Document; or operator include list. Detection → HALT. Operator must re-invoke with PRDs scoped out.

Checkpoint	When	Action
PRD-1	After Phase 1 inventory	Quarantine matches in prd-quarantine-list
PRD-2	Before every Phase 5 write	Match quarantine → HALT
PRD-3	After Phase 7 diff	Any PRD in changeset → HALT

Pre-flight

: "${WIKI_SEED_URL:?}"
git checkout -b "feat/wiki-refactor-$(date +%F)"
mkdir -p wiki-refactor-artifacts

Phases (each references the detailed runbook)

#	Phase	Runbook	Output
1	Discovery — crawl descendants, snapshot content	phase-1-discovery.md	wiki-inventory.md
2	Deduplication — analyze duplication patterns	phase-2-deduplication.md	dedup-analysis.md
3	Information Architecture — new structure	phase-3-information-architecture.md	new-wiki-structure.md
4	Writing plan — source→target page map	phase-4-writing-plan.md	wiki-writing-plan.md
5	Rewrite + 3-round progressive review	phase-5-rewrite-and-review.md	refactored-wiki/*.md
6	Quality metrics	phase-6-quality-metrics.md	wiki-refactor-report.md
7	Safe delivery — branch, migration guide, final checks	phase-7-safe-delivery.md	Ready-to-merge branch

Phase 1 scope cap

100 pages OR >50k words → warn operator + require confirmation. Zero pages → abort with "wiki unreachable or empty." PRD-1 runs on the full inventory.

⏸️ Human checkpoint (after Phase 4)

Present wiki-writing-plan.md (pages to rewrite / merge / delete / create, word-count delta, PRD quarantine list). Do not proceed to Phase 5 without explicit operator approval.

Phase 5 write loop

For each target page, before invoking tools/wiki-write.sh:

1. PRD-2 check against quarantine list
2. 3-round progressive review (use progressive-harsh-review)
3. Stage 5.5 structure gate (node tools/wiki-markdown-validate.js)
4. tools/wiki-write.sh update --doc $ID --content page.md (exit 0 or halt)

Phase 7 delivery

1. Package refactored pages into wiki/ on the feature branch
2. Emit migration guide (old-slug → new-slug)
3. Diff Phase-1 snapshot vs current wiki → on drift, present overwrite / merge / abort
4. Run use-skill link-verification (exit 0 required) and use-skill wiki-secret-audit (empty findings)
5. PRD-3 check: final diff contains zero PRD files

Failure modes

Symptom	Cause	Response
PRD checkpoint fires	PRD in rewrite scope	HALT — no recovery path
Phase 1 returns zero pages	Bad URL, auth, empty wiki	Abort with diagnostic
Phase 2 zero duplicates	No duplication	Continue; Phase 3 may still apply
Scope cap exceeded	>100 pages or >50k words	Warn operator; narrow scope
Phase 7 snapshot drift	Wiki edited during refactor	Present diff; operator picks overwrite/merge/abort
3-round review won't converge	Quality blocker	Escalate page to human

Success criteria and PRD-protection rationale: rationale.md.