agentleFS
Sign inStart free
bordenetbordenet/superpowers-plus/skills/wiki/wiki-refactor/skill.md

wiki-refactor

Skill8 starsChanged 6 months agoMITView on GitHub

Conductor skill for full wiki refactoring. Orchestrates a 7-phase pipeline — discovery, deduplication, information architecture, writing plan, progressive rewrite + review, quality metrics, and safe delivery. Enforces PRD protection (hard gate), human checkpoint after planning, scope caps, and content snapshot/drift detection.

1 other project uses a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    When asked to do a full-wiki refactor: eliminate duplication, improve information architecture, or elevate prose quality across many pages

    line 33
  2. Very specific:

    Run use-skill link-verification (exit 0 required) and use-skill wiki-secret-audit (empty findings)

    line 93

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
skill.md

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.

CheckpointWhenAction
PRD-1After Phase 1 inventoryQuarantine matches in prd-quarantine-list
PRD-2Before every Phase 5 writeMatch quarantine → HALT
PRD-3After Phase 7 diffAny 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)

#PhaseRunbookOutput
1Discovery — crawl descendants, snapshot contentphase-1-discovery.mdwiki-inventory.md
2Deduplication — analyze duplication patternsphase-2-deduplication.mddedup-analysis.md
3Information Architecture — new structurephase-3-information-architecture.mdnew-wiki-structure.md
4Writing plan — source→target page mapphase-4-writing-plan.mdwiki-writing-plan.md
5Rewrite + 3-round progressive reviewphase-5-rewrite-and-review.mdrefactored-wiki/*.md
6Quality metricsphase-6-quality-metrics.mdwiki-refactor-report.md
7Safe delivery — branch, migration guide, final checksphase-7-safe-delivery.mdReady-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

SymptomCauseResponse
PRD checkpoint firesPRD in rewrite scopeHALT — no recovery path
Phase 1 returns zero pagesBad URL, auth, empty wikiAbort with diagnostic
Phase 2 zero duplicatesNo duplicationContinue; Phase 3 may still apply
Scope cap exceeded>100 pages or >50k wordsWarn operator; narrow scope
Phase 7 snapshot driftWiki edited during refactorPresent diff; operator picks overwrite/merge/abort
3-round review won't convergeQuality blockerEscalate page to human

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

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free