housekeeping-docs
housekeeping-docs
Keeps repositories tidy and documentation aligned with the real implementation—structure, naming, dead code and temp artifacts, and root docs (README, SPEC, TODO, ARCHITECTURE). Use when the user asks for housekeeping, repo cleanup, doc sync, documentation alignment, hygiene, or maintaining spec-driven project files.
Goal
Keep the repository tidy, easy to navigate, and documented in a way that matches what the code actually does today—not past intentions.
Housekeeping (code and layout)
- Structure — Prefer domain-oriented or project-consistent module layout; avoid dumping unrelated files at the repo root; group related code together.
- Remove clutter — Delete temporary artifacts (build outputs committed by mistake, scratch files, obsolete scripts) after confirming they are unused. Prefer checking
git status, references, and imports before removal. - Naming — Align inconsistent file/folder/symbol names with dominant project conventions; avoid drive-by renames that touch unrelated areas.
- Dead code — Remove or consolidate obsolete code paths when clearly unused; do not delete behavior the user still relies on without evidence.
Scope only what the task requires; avoid large cosmetic refactors unrelated to the request.
Documentation updates
Update docs when behavior, scope, architecture, or workflows change—not as a separate "doc sprint" unless asked.
Keep these root files current when applicable to the change:
| File | Typical contents |
|---|---|
README.md | What the project is, how to run/develop, high-level setup |
SPEC.md | Product/technical specifications and requirements |
TODO.md | Actionable backlog and near-term work |
ARCHITECTURE.md | System shape, boundaries, and major decisions |
Rule: Documentation should describe the current system. If code and docs disagree, fix the docs (or flag the mismatch) rather than leaving stale text.
Quick checklist
Housekeeping pass:
- [ ] Remove build outputs, scratch files, temp artifacts
- [ ] Delete or consolidate unused imports and symbols
- [ ] Align inconsistent naming with project conventions
- [ ] Update README commands (install, dev, build, test)
- [ ] Sync ARCHITECTURE.md with current structure
- [ ] Update SPEC.md if requirements/scope changed
- [ ] Mark completed items in TODO.md, add new if needed
- [ ] Verify all internal links still resolve
Workflow
- Scan — Note new/changed entry points, configs, domains, and removed features from the diff or recent edits.
- Align — Update the minimum set of doc sections and file moves that reflect those facts.
- Tidy — Remove artifacts and fix obvious naming/organization issues tied to the same change.
- Verify — Quick pass: links, commands in README, and headings still match repo layout.
Expected outcomes
- Clean, maintainable tree with less noise for future work.
- Root documentation matches implementation.
- New contributors can orient faster from README + ARCHITECTURE (+ SPEC where used).
Optional reference
For projects that restrict extra markdown to docs/, keep only the mandated root files in the root and put supplementary material under docs/ per project rules.
Related skills
- domain-modularization — When restructuring, housekeeping docs ensure documentation stays aligned with the new layout.