Doc janitor

Doc Janitor

Overview

Survey the project → classify documents → generate/merge core docs → archive redundant files → verify.

Core principle: there are exactly three actions for existing files — keep, merge, archive. Delete is not one of them. Judging a file "worthless" is not your call: when unsure, archive it.

Phase 0: Safety Check

• No git repository → first suggest git init && git add -A && git commit to leave a restorable snapshot. If the user is absent or declines → proceed, but strictly archive-only, never delete
• Before any move, confirm the target path does not overwrite an existing file

Phase 1: Survey

• Structure: directory tree, language, build system, entry points, dependencies
• Document inventory: README, CLAUDE.md, docs/, plus progress files, reports, logs, notes, and TODOs scattered anywhere (watch for non-English filenames)
• If git exists, use commit history to judge file age and activity

Phase 2: Classify

Tag every document-like file with one category:

Category	Examples	Action
Permanent	README, CLAUDE.md, architecture docs	Keep and update
Active	current progress, latest report	Merge each kind into one file under docs/
Stale	old report versions, abandoned notes	Archive
Artifacts	*.log, build output, caches	Archive + add to .gitignore

• Multiple files of the same kind (e.g. 3 progress files) → merge into a single file: latest wins, historical highlights go into a table, archive the sources — do not delete them
• Personal notes and files of unknown origin → archive as-is; first fold any technically valuable points into the relevant doc

Phase 3: Generate / Update Core Docs

The strategy is preserve-and-merge, not rewrite-from-scratch:

• CLAUDE.md: architecture overview, common commands, project conventions, non-obvious gotchas. Existing hand-written conventions must be preserved verbatim; only update stale parts and fill gaps. Keep it lean — write only what cannot be inferred from the code
• README.md: purpose, install, how to run. Every command written must match the current code (entry files and dependency files actually exist)
• docs/ hierarchy: create ARCHITECTURE.md and module docs only when the project is big enough; do not force them on small projects (YAGNI)
• Fill the gaps: think about what else this project type needs — API docs, deployment guide, data dictionary, contributing guide… list suggestions; directly add the ones that are clearly important and have enough information

Phase 4: Archive & Restructure

• Stale/redundant/artifact files → docs/archive/YYYY-MM-DD-original-name
• Before archiving each file, grep for its filename: if other docs reference it → fix the references first, then move
• Code layout problems (entry point in the wrong directory, tangled modules) → write to docs/REORG-SUGGESTIONS.md: current state, suggestion, rationale, blast radius. Suggest only — never move code files

Phase 5: Verify & Summarize

• Check every relative link between docs
• Actually run the runnable install/run commands from the README
• Output a summary: what was updated, merged, archived (with archive paths), and a digest of REORG-SUGGESTIONS

Red Flags — Stop When You Catch Yourself Thinking

Thought	Reality
"This file is worthless, just delete it"	You cannot judge its value to the user. Archive
"Logs/build artifacts can be deleted directly"	Archive + .gitignore
"Content is merged, sources can go"	Archive merged sources — they are the rollback path
"Rewriting CLAUDE.md is cleaner"	Hand-written conventions are the most expensive content. Preserve and merge
"Might as well move the code files too"	Code reorg goes into the suggestions report only