| name | splitting-and-verifying-docs |
| description | Use when top-level project docs (AGENTS.md, CLAUDE.md, README.md) have grown bloated with detailed architecture content, or when documentation claims (API counts, file paths, symbol names, version numbers) may be out of sync with the actual codebase |
Splitting and Verifying Docs
Overview
Core principle: Documentation drift is silent. Counts, paths, and symbol names in prose rot while the code moves on. Use static analysis (CodeGraph) to verify every concrete claim, and extract detail-heavy sections into dedicated files so top-level docs stay scannable.
This is doc refactoring with verification, not just rewriting — information moves between files but is also checked against the codebase and corrected where wrong.
When to Use
Use this skill when ANY of these are true:
- A top-level doc (AGENTS.md / CLAUDE.md / README.md) exceeds ~300 lines or mixes "quick reference" with "deep architecture"
- The doc contains concrete, verifiable claims (route counts, component counts, file lists, version numbers) that haven't been checked against source recently
- The project has multiple overlapping docs describing the same thing at different levels of detail (e.g.,
AGENTS.md + docs/architecture.html + CLAUDE.md all describing architecture)
- A new team member would struggle to find the authoritative source for architecture questions
- You're about to create or restructure architecture documentation
Do NOT use for:
- Adding new content that didn't exist before (that's writing, not refactoring)
- One-file fixes (just edit the file)
- Projects without CodeGraph indexed (
.codegraph/ absent) — fall back to manual grep/list_dir verification, which is slower
Core Workflow
flowchart LR
A[1. Survey<br/>existing docs] --> B[2. Verify<br/>with CodeGraph]
B --> C[3. Extract<br/>to docs/]
C --> D[4. Slim<br/>top-level docs]
D --> E[5. Fix<br/>stale claims]
E --> F[6. Validate<br/>links & lint]
Phase 1 · Survey existing docs
Read every top-level and docs/ doc in parallel. Build a mental table:
| Doc | Length | Scope | Problem |
|---|
AGENTS.md | ? lines | dev quick-start + architecture | bloat? detail-heavy? |
CLAUDE.md | ? lines | Claude guide | overlaps with AGENTS.md? |
README.md | ? lines | public intro | product-focused? |
docs/*.html / *.md | ? | visual / deep dive | stale numbers? wrong title? |
Identify: which sections are "quick reference" (keep inline) vs "deep content" (extract to docs/).
Phase 2 · Verify concrete claims with CodeGraph
This is the heart of the skill. For every number, path, and name the docs assert, cross-check against the actual codebase. Don't trust the docs.
| Claim type | How to verify |
|---|
| "N API routes" | Get-ChildItem -Recurse -Filter "route.ts" | Measure-Object (PowerShell) or find . -name route.ts | wc -l |
| "N components" | list_dir components/ + codegraph_search "kind:component" |
| "N hooks" | list_dir hooks/ (don't forget subdirectories like agent-session/) |
| File path exists | list_dir on the parent directory |
| Symbol still exists | codegraph_search "SymbolName" |
| Version number | read_file package.json |
| Component responsibilities | codegraph_explore "ComponentName what it does" |
Common drift patterns to look for:
- Counts that were accurate at one version but never updated (e.g., "14 components" when there are now 17)
- Renamed directories or files (docs still reference old names)
- New subdirectories the docs don't mention (e.g.,
electron/ missing from file map)
- Upstream dependency version bumps not reflected (e.g., doc says
^0.75.5, actual is ^0.78.0)
- Project rename (e.g., doc title says "Pi Web" but package is now "pi-agent-desktop")
Phase 3 · Extract detailed content to dedicated docs
For each "deep content" section identified in Phase 1:
- Create
docs/<TOPIC>.md (e.g., docs/ARCHITECTURE.md)
- Move the content verbatim — don't rewrite, just relocate (easier to review diffs)
- Apply Phase 2 corrections to the moved content
- Add structure — table of contents, Mermaid diagrams, tables where lists were vague
- Mark as authoritative — add a header note like "本文档是项目的权威架构参考"
Naming convention: docs/ARCHITECTURE.md, docs/CONTRIBUTING.md, docs/DEPLOYMENT.md — UPPERCASE for top-level project docs (matches GitHub convention and sorts above lowercase files).
Phase 4 · Slim top-level docs
Replace the extracted sections in AGENTS.md / CLAUDE.md with:
- A 3-5 line "cheat sheet" of the most frequently looked-up info
- A link to the dedicated doc with anchor (e.g.,
[docs/ARCHITECTURE.md §14](docs/ARCHITECTURE.md#14-关键设计决策与陷阱))
What to keep inline in top-level docs:
- Commands developers run daily (
npm run dev, npm test)
- The 3-5 most common pitfalls (with link to full list)
- Directory-purpose table (one row per top-level dir)
What to extract:
- ASCII architecture diagrams
- Full file maps
- Complete API route listings
- Detailed design decision explanations
- Data flow sequence diagrams
Phase 5 · Fix stale claims (from Phase 2)
Apply every correction discovered in Phase 2 to both the dedicated doc and any remaining references in top-level docs. Common fixes:
- Title / project name / version in HTML
<title> and footer
- Counts in section headings ("14 个组件" → "17 个顶层组件 + 3 个子组件目录")
- Missing directories in file maps
- Outdated dependency versions in tech stack tables
- Wrong GitHub links
Phase 6 · Validate
- Markdown lint: run
get_errors on every changed .md file — fix MD040 (code block language) and other warnings
- HTML lint: run
get_errors on changed .html files
- Link integrity:
grep_search for any docs/ paths referenced in top-level docs to confirm targets exist
- CodeGraph staleness: after edits, check for the "⚠️ Some files referenced below were edited" banner — re-read those specific files if it appears
Quick Reference: Verification Cheatsheet
# Count API routes (App Router)
Get-ChildItem -Path "app/api" -Recurse -Filter "route.ts" | Measure-Object
# List all components (including subdirectories)
Get-ChildItem -Path "components" -Recurse -Filter "*.tsx"
# Verify package versions
Get-Content package.json | Select-String "version"
# Find all SKILL.md locations the loader scans
node --input-type=module -e "import {getAgentDir, DefaultResourceLoader} from '@earendil-works/pi-coding-agent'; const l = new DefaultResourceLoader({cwd: process.cwd(), agentDir: getAgentDir()}); await l.reload(); l.getSkills().skills.forEach(s => console.log(s.filePath));"
For symbol-level verification, prefer CodeGraph MCP tools over grep:
codegraph_explore — one call returns source + callers + blast radiuscodegraph_search — fast name → location lookupcodegraph_node — single symbol depth (source + caller/callee trail)
Common Mistakes
1. Extracting too aggressively
Wrong: Move everything out of AGENTS.md, leaving only a link.
Right: Keep the 5 things developers look up daily inline; extract the rest.
Test: "If a new dev opens AGENTS.md for the first time, can they start coding in 60 seconds?" If yes, the slim version is right.
2. Trusting doc counts without verification
Wrong: See "19 API routes" in docs, assume it's correct, copy it to the new doc.
Right: Run the count command. Docs almost always lag behind code.
3. Breaking existing anchor links
Wrong: Move content to a new file, leave AGENTS.md#architecture pointing at a section that no longer exists.
Right: When extracting, add a stub section in the old location with a redirect note, or update all inbound links.
4. Duplicating instead of relocating
Wrong: Copy architecture content to docs/ARCHITECTURE.md AND leave the full version in AGENTS.md.
Right: Move it. Replace the original location with a 3-line summary + link. Single source of truth.
5. Skipping HTML docs
Wrong: Only update .md files; assume docs/architecture.html is fine.
Right: HTML docs rot fastest (they're not in the edit loop). Verify titles, footers, version badges, and component counts in HTML too.
Real-World Example
The pi-agent-desktop project went through this exact process in June 2026:
Before:
AGENTS.md: ~350 lines mixing quick-start with ASCII architecture diagrams, full file map, and detailed trapsCLAUDE.md: ~250 lines with overlapping architecture descriptiondocs/architecture.html: titled "Pi Web v0.6.11" (project was renamed to pi-agent-desktop v0.7.11)
After:
AGENTS.md: ~150 lines — quick-start + 3-line architecture summary + linkCLAUDE.md: ~100 lines — guide + 3 most-common pitfalls + linkdocs/ARCHITECTURE.md: 30KB authoritative doc with 15 sections, Mermaid diagrams, full tablesdocs/architecture.html: corrected title, version, 8 stale facts fixed via CodeGraph
CodeGraph verification caught 8 stale claims:
| Claim | Doc said | Actual |
|---|
| Title | Pi Web 架构深度解析 | Pi Agent Desktop 架构深度解析 |
| Version | v0.6.11 / 2026-05-26 | v0.7.11 / 2026-06-21 |
| pi SDK version | ^0.75.5 | ^0.78.0 |
| API route count | "19 条" | 24 条 |
| Architecture layers | 3 (missing Electron) | 4 |
| Component count | 14 | 17 + 3 subdirectories |
| File map | missing electron/, docs/ | complete |
| Tech stack | missing Electron deps | added Electron/builder/updater |
Required Tools
- CodeGraph MCP (
codegraph_explore, codegraph_search, codegraph_node) — primary verification tool
list_dir, read_file, grep_search — fallback when CodeGraph doesn't cover a claimrun_in_terminal (PowerShell Get-ChildItem / Measure-Object) — counting filesget_errors — markdown/HTML lint validationmanage_todo_list — track the 6-phase workflow
If CodeGraph is not indexed (no .codegraph/ directory), the workflow still works but verification is slower — use grep_search + list_dir + read_file instead.
