| name | wiki-maintenance |
| description | Comprehensive wiki maintenance: daily structural health checks (index reconciliation, log separator fixes, pipeline watchdog alerts), comparison page updates (adding items to multi-section comparison tables), and page relocation (moving/renaming pages while maintaining link integrity). |
| category | wiki |
| tags | ["wiki","maintenance","index","comparison","relocation","watchdog"] |
| triggers | ["wiki maintenance","wiki structural health","wiki watchdog","wiki auto-fix","update comparison page","add to comparison table","move wiki page","rename wiki page","relocate wiki page","wiki directory restructuring"] |
Wiki Maintenance
Comprehensive wiki maintenance covering three domains: daily structural health, content updates, and structural reorganization.
Quick Reference
| Task | Trigger | Section |
|---|
| Daily structural health | Watchdog cron / broken links | §1 Daily Structural Health |
| Add item to comparison | "Add X to pricing page" | §2 Comparison Page Updates |
| Move/rename pages | "Move wiki page" | §3 Page Relocation |
Common Constraints
execute_code Blocked in Cron
execute_code is blocked in cron mode. Use patch() and terminal() (shell commands) instead.
Git Commit Conventions
cd ~/ai-topics && git add wiki/ && git commit -m "wiki: <summary>" && git push
Shell variable trap: If the commit message contains $ (e.g., $10/$50), use single quotes or escape: \$10/\$50.
Index.md Maintenance
- Section headers use filesystem count (including
_index.md)
- Summary line
Indexed entries: uses index entry count (all - [[...]] lines)
- Always verify both after any index modification
- Concepts section drifts the most — always check first
NEVER use write_file for log.md
write_file overwrites the entire file. log.md is append-only — always use terminal("cat >> wiki/log.md") or patch().
1. Daily Structural Health (Watchdog)
When to Use
- Daily watchdog cron job (
wiki_watchdog_fix_context.py) at 17:35 UTC
- User reports of broken links or index inconsistencies
- Any task involving wiki structure health checks
Auto-Fixable Issues
Index.md Corruption:
- Pipe table corruption:
|- [[ → - [[
- Line number prefix corruption:
\d+| patterns
- Duplicate entries: exact duplicate
- [[...]] lines
- Header count mismatch: section headers vs filesystem
Log.md Missing Separators:
Consecutive ## [YYYY-MM-DD] headers without ---. Pre-flight: verify ALL ## lines are date-stamped before bulk fixing.
Orphan Page Handling:
- Ghost entry detection (index.md → file existence)
- Orphan addition (file existence → index.md)
- Alphabetical insertion within correct section
- Max 20 orphans per run; filter stubs (<30 lines, TODO marker)
Pitfalls
rstrip(".md") is a character set, not substring — use re.sub(r'\.md$', '', target)- Schedule inversion: watchdog runs BEFORE health-fix (17:35 vs 17:50 UTC)
wiki_snapshot counts may be stale — verify against filesystem- Summary line
Indexed entries: must count ALL - [[...]] lines, not just one section
- Tag taxonomy: Pre-commit validates tags against SCHEMA.md. Common misses:
exploration, interview, llm-training, rl (use reinforcement-learning). Verify with grep -o "tagname" wiki/SCHEMA.md.
- Language enforcement: Non-raw pages must be in English. Japanese content blocks commit — translate before committing.
- Symlink + git add: Changes made through
~/wiki symlink may not stage with git add wiki/. Use git add -A wiki/ and verify with git show --stat HEAD.
→ Full detail: references/daily-structural-health.md
→ Scripts: scripts/build-orphan-sed.py, scripts/misplaced-entries-detection.py
→ Reference: references/misplaced-stub-cleanup.md
2. Comparison Page Updates
When to Use
- Adding a new item (model, provider, tool) to an existing multi-section comparison page
- "Add X to the pricing/comparison page"
- "Update comparison table with new model"
Workflow
- Read the FULL comparison page first
- Identify ALL sections to update (typically 8+)
- Gather all pricing/spec data before editing
- Edit with
patch tool
- Verify no duplicate frontmatter fields
- Update index.md and log.md
- Commit and push
Sections Typically Updated (8 total)
- Main table — new row with tier classification
- Cache pricing section
- Batch pricing section
- Tier analysis section
- Cost comparison section (chat + code gen workloads)
- Key Trends — if significant market shift
- Changelog — always add entry
- Related Pages — wikilink to entity/concept page
Key Pitfalls
- Duplicate frontmatter: Always read lines 1-10 before patching
- Non-unique patch context: Include surrounding lines for uniqueness
- Section numbering cascade: Renumber ALL subsequent sections when inserting
- execute_code blocked in cron: Use
terminal + sed for bulk edits
→ Price verification: references/llm-api-pricing-verification.md
→ Case study: references/llm-api-pricing-fable5-update.md
→ Full detail: references/comparison-page-updates.md
→ Case study: references/llm-api-pricing-fable5-update.md
3. Page Relocation & Restructuring
When to Use
- Moving a page to a new directory
- Renaming a page
- Reorganizing directory structure
- Merging directories or splitting pages
Workflow
- Verify target and backlinks (
search_files)
- Create target directory if needed
- Copy and transform
- Remove original
- Update backlinks (small:
patch per file; bulk: Python regex script)
- Update index.md
- Update log.md
- Commit and push
Link Update Patterns
[[concepts/old/page]][[concepts/old/page|Display Text]][[concepts/old/_index]][[old/page]] (relative links)
Decision Matrix: Subdirectory vs MOC Page
| Signal | Subdirectory | MOC Page |
|---|
| Pages share a concrete prefix (≥5) | ✅ | — |
| Pages form a coherent domain by tag (≥5) | ✅ | — |
| Theme is cross-cutting / universal | ❌ | ✅ |
| ≤4 pages in cluster | ❌ | ✅ or skip |
Universal themes (too generic for subdirs): agent-*, agentic-*, llm-*, open-*, multi-*, software-*
Directory Restructuring Patterns
_index.md to descriptive name- Creating new hierarchy
- Merging directories
- Semantic classification move (by tags)
- Directory rename
- Product tool split (model vs tool pages)
- Prefix restoration
Pitfalls
- Double-prefix display bug: Ensure display name doesn't duplicate slug prefix
- Missing relative links: Search for and update relative links too
- Prefix stripping: User preference — keep prefix in filenames even inside subdirectories
- Overlapping concepts: Keep separate, add disambiguation blockquotes
- Prefix suffix capture for directory renames: Use
(?old-name(/?[^\\\\]|]*?)(?:\\\\|([^\\\\]]+))?\\\\]\\\\] pattern
- Symlink + git add:
git add wiki/ from repo root may not stage changes made through ~/wiki symlink. Use git add -A wiki/ and verify with git show --stat HEAD.
- Double-nesting in bulk sed: If
post-training is in the moved pages list AND the sed replaces concepts/post-training → concepts/post-training/post-training, you get triple-nesting. Always verify: grep -rli "double-pattern/" after bulk sed.
- Tag taxonomy violations: Pre-commit blocks unknown tags. Verify tags exist in SCHEMA.md before committing. Common misses:
exploration, interview, llm-training, rl.
- Language enforcement: Non-raw pages must be in English. Japanese content blocks commit.
- Scope estimation: For N moved pages, expect ~2-3N files needing reference updates.
→ Batch reorg checklist + pitfalls: references/batch-directory-reorganization-pitfalls.md
→ Full detail: references/page-relocation.md
→ Batch reorg pitfalls: references/batch-directory-reorganization-pitfalls.md (symlink+git trap, double-nesting, tag validation, scope estimation)
Support Files
References
| File | Source | Content |
|---|
references/daily-structural-health.md | wiki-watchdog-auto-fix | Full watchdog workflow with all auto-fix patterns |
references/comparison-page-updates.md | wiki-comparison-page-update | Full comparison page update workflow |
references/page-relocation.md | wiki-page-relocation | Full page relocation workflow with all patterns |
references/misplaced-stub-cleanup.md | wiki-watchdog-auto-fix | Detection heuristics for misplaced concept stubs |
references/llm-api-pricing-fable5-update.md | wiki-comparison-page-update | Case study: adding Fable5 to LLM API pricing |
references/llm-api-pricing-verification.md | wiki-maintenance | SPA price verification via OpenRouter API, ~ removal workflow, model name change detection |
references/agent-semantic-classification-migration.md | wiki-page-relocation | Semantic classification of 47 agent pages |
references/batch-hierarchy-reorganization.md | wiki-page-relocation | Multiple sequential directory reorganizations |
references/context-engineering-hierarchy-migration.md | wiki-page-relocation | 16 pages into subdirectory, prefix restoration |
references/death-of-browser-relocation-example.md | wiki-page-relocation | Real-world page relocation example |
references/directory-rename-and-product-split.md | wiki-page-relocation | Directory rename patterns and product splits |
references/evaluation-safety-benchmarks-separation.md | wiki-page-relocation | Three-way taxonomy separation |
references/orphan-page-deletion-example.md | wiki-page-relocation | Orphan page detection and deletion |
references/post-relocation-enrichment-pattern.md | wiki-page-relocation | Enriching relocated pages from past sessions |
references/batch-directory-reorganization-pitfalls.md | wiki-maintenance | Symlink+git trap, double-nesting, tag validation, scope estimation, checklist |
Scripts
| File | Source | Content |
|---|
scripts/build-orphan-sed.py | wiki-watchdog-auto-fix | Build sed script for orphan insertion |
scripts/misplaced-entries-detection.py | wiki-watchdog-auto-fix | Detect misplaced entries between sections |
