Update Project Doc

Update Project Doc — Refresh Stale Documentation

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.

When to Use

• After significant project work (new files, completed milestones, structural changes)
• During session-close when offered
• When the user says "update project docs", "refresh docs", "sync my docs", "update my README"
• Periodically to keep documentation accurate

What It Does NOT Do

• Never rewrites research content (hypotheses, arguments, literature, design decisions)
• Never deletes sections — only updates factual/structural content within existing sections
• Never creates new documentation files — only updates existing ones

---

Protocol

Step 1: Detect Documentation Files

Find all documentation files in the project:

1. Check for CLAUDE.md in project root
2. Check for README.md in project root
3. Scan docs/ and docs/*/ for .md files containing file trees or counts
4. Note which files exist — only update what's present

Special 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.

Step 2: Gather Current State

Collect the actual state of the project:

1. File tree — use ls -R or Glob to build the actual directory structure (respect .gitignore patterns, skip out/, __pycache__/, .venv/, node_modules/)
2. Recent git history — git log --oneline -20 for recent commits
3. Session logs — read the latest 1-2 files in log/ (if the directory exists)
4. Bibliography count — count entries in any .bib file(s): grep -c '@' *.bib
5. Symlink targets — readlink on any documented symlinks
6. Context files — read .context/current-focus.md or .context/project-recap.md if present

Task 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)

Step 3: Run Staleness Checks

Compare gathered state against documented content. Flag any mismatches:

Step 3b: Leanness Audit

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.

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.