Use when you need to update a project's own CLAUDE.md, README.md, or docs/ to reflect current state.
Scan a project's documentation files and update sections that have drifted from reality: file trees, timestamps, bibliography counts, next steps, skill/hook tallies, and more.
/session-close when offeredFind all documentation files in the project:
CLAUDE.md in project rootREADME.md in project rootdocs/ and docs/*/ for .md files containing file trees or countsSpecial case: Some projects (e.g., the political information paper) have no CLAUDE.md because they use a committed README.md as their primary project documentation instead. This is intentional for repos meant to be shared or published. In these cases, treat README.md as the main documentation file and apply all the same checks to it.
Read each detected file to understand its current content.
Collect the actual state of the project:
ls -R or Glob to build the actual directory structure (respect .gitignore patterns, skip out/, __pycache__/, .venv/, node_modules/)git log --oneline -20 for recent commitslog/ (if the directory exists).bib file(s): grep -c '@' *.bibreadlink on any documented symlinks.context/current-focus.md or .context/project-recap.md if presentTask Management only (detected by presence of skills/ directory):
7. Skill count — count directories in skills/ that contain SKILL.md
8. Hook count — count .sh files in hooks/ (if present)
9. Skill lengths — wc -l skills/*/SKILL.md to identify bloated skills
Leanness data (all projects):
10. CLAUDE.md line count — wc -l CLAUDE.md
11. CLAUDE.md section sizes — count lines per ## section
12. README.md line count — wc -l README.md
13. SKILL.md line counts — (Task Management only) wc -l skills/*/SKILL.md
14. Duplication scan — check if CLAUDE.md content duplicates what's already in README.md, docs/, or .context/ files
15. Agent line counts — wc -l .claude/agents/*.md (if present)
16. Context file line counts — wc -l .context/*.md (if present)
Compare gathered state against documented content. Flag any mismatches:
| Check | How to Detect |
|---|---|
| File tree | Generate actual tree, compare against any tree/structure block in docs (look for ``` blocks or indented listings with file paths) |
| Timestamps | Flag "Last updated", "w/c", or date stamps older than 7 days |
| Bibliography count | Compare actual .bib entry count vs any documented count (e.g., "42 references") |
| Next steps / roadmap | Cross-reference items against recent commits and session logs — flag items that appear completed |
| Manuscript status | Flag sections marked "TODO", "incomplete", or "placeholder" that now have content |
| Symlinks | Verify documented symlink targets still resolve with readlink |
| Skill/hook counts | (Task Management only) Compare actual count vs documented numbers in CLAUDE.md, README.md, and .tex files |
| Venue/target info | If CLAUDE.md documents a target journal, check it matches .context/projects/_index.md (if accessible) |
Using the data gathered in Step 2 (items 10-14), check infrastructure file sizes against thresholds. This applies to all projects, not just Task Management.
| File | Threshold | What to flag | Fix |
|---|---|---|---|
CLAUDE.md | > 200 lines total | Current line count | Extract reference sections to docs/, replace with pointers (see lean-claude-md rule) |
CLAUDE.md sections | Any ## section > 15 lines of reference material | Section name + line count | Extract to docs/ with a one-line summary + link |
CLAUDE.md duplication | Content duplicated from README/docs/.context | Which content is duplicated and where | Keep only the pointer in CLAUDE.md |
README.md | > 300 lines total | Current line count | Extract long sections to docs/ |
SKILL.md files | > 300 lines each (TM only) | File name + line count | Move templates/examples/report formats to references/ or templates/ subdirectory |
Project agents (.claude/agents/*.md) | > 400 lines each | File name + line count | Extract verbose prompt sections to companion files |
Context files (.context/*.md) | > 200 lines each | File name + line count | Archive stale content, keep current |
What counts as "reference material" (extractable): assessment guidelines, detailed literature notes, long examples, report templates, checklists, reviewer feedback.
What does NOT count (keep in place): safety rules, conventions, folder structure trees, session continuity pointers.
Present leanness findings separately from staleness findings in Step 4.
Present findings grouped by file:
Staleness report for [Project Name]:
CLAUDE.md:
- File structure tree is outdated (missing: X, Y; removed: Z)
- Skill count says 23, actual is 26
- "Last updated" date is 3 weeks old
README.md:
- Directory structure block needs updating
- Next steps: "Write introduction" appears completed (commit abc1234)
- Bibliography count says 38, actual is 42
docs/overview.md:
- No issues detected
Leanness:
- CLAUDE.md: 237 lines (threshold: 200) — ## Assessment section is 42 lines of guidelines
- README.md: OK (189 lines)
If nothing is stale, report that and stop.
Use AskUserQuestion to let the user approve, modify, or skip staleness fixes:
If Step 3b found leanness issues, present each as an individually actionable item:
Leanness fixes available:
| # | File | Issue | Current | Fix |
|---|------|-------|---------|-----|
| 1 | CLAUDE.md | >200 lines | 237 | Extract ## Assessment section → docs/ |
| 2 | skills/X/SKILL.md | >300 lines | 382 | Move checklists → references/ |
Use AskUserQuestion with multiSelect: true:
Do not defer or merely report leanness findings. Always present them as actionable items alongside staleness fixes.
For each approved change:
Edit operations — never rewrite entire filesAfter all edits, print a summary:
Updated project docs:
CLAUDE.md: file tree, skill count (23 → 26)
README.md: directory structure, bib count (38 → 42), 1 next-step marked complete
Total: 5 edits across 2 files
Edit with precise old_string / new_string.├── trees, don't switch to |--. If counts use "X total", don't change to "X skills"./session-close — offers to run this skill at Step 3.5/sync-repo private — Task Management-specific superset: propagates counts across all private TM docs including LaTeX files. Run after this skill when in the TM project.vault sync (edit vault files directly) — syncs state to the central context library (complementary; run after this)/update-focus — updates current-focus.md (different purpose: session state, not doc accuracy)