| name | housekeeping |
| description | Scan the codebase for maintenance tasks — lint errors, broken tests, dead code, stale comments. Returns taskboard-formatted lines. Called by reflector during DISCOVER or invoked manually. |
| user_invocable | true |
housekeeping
Housekeeping
Scan the codebase for implicit maintenance tasks. Returns discovered issues as taskboard-formatted task lines with #housekeeping tag. Does NOT modify TASKS.md — the caller decides what to append.
Usage
/housekeeping — full scan, all categories/housekeeping lint — lint/type errors only/housekeeping tests — broken tests only/housekeeping dead-code — dead code only/housekeeping comments — stale comments only/housekeeping docs — documentation consistency only
How it works
- Detect project tooling (check
pyproject.toml, package.json, Makefile, Cargo.toml, etc.)
- Run the relevant scan categories
- Deduplicate against existing Backlog (read TASKS.md, skip issues already tracked)
- Output new task lines to the user (or return them to the calling skill)
Scan categories
Run in this order. Skip categories where the project has no relevant tooling configured.
1. Lint / type errors
Detect and run the project's configured linter or type checker:
| Indicator | Command to run |
|---|
pyproject.toml with [tool.flake8] or [tool.ruff] | uv run flake8 or uv run ruff check |
pyproject.toml with [tool.mypy] | uv run mypy |
package.json with lint script | npm run lint |
Makefile with lint target | make lint |
.eslintrc* exists | npx eslint . |
Parse the output. Group related errors (same file, same rule) into one task. Each distinct group becomes one task line.
Example output:
- [ ] **TB-N** **Fix ruff E401 errors in src/store.py** `#housekeeping` — 3 unused import errors (lines 5, 12, 18)
2. Broken tests
Run the test suite:
| Indicator | Command to run |
|---|
pyproject.toml with [tool.pytest] | uv run pytest --tb=no -q |
package.json with test script | npm test |
Makefile with test target | make test |
Parse failures. Each failing test (or group of related failures in the same file) becomes one task line.
Example:
- [ ] **TB-N** **Fix test_store.py::test_delete_persists** `#housekeeping` — assertion error, deleted task reappears after reload
3. Dead code
Use lightweight heuristics — do NOT run full coverage analysis:
- Unused imports: grep for imports, check if the imported name is used elsewhere in the file
- Commented-out code blocks: look for 3+ consecutive commented lines that appear to be code (contain
=, def, class, return, if, etc.)
- Unreachable code:
return followed by non-comment code at the same indent level
Keep this fast — scan src/ or the main source directory, not the entire repo. Skip vendor/, node_modules/, .venv/, etc.
Example:
- [ ] **TB-N** **Remove unused imports in src/models.py** `#housekeeping` — 2 unused imports: `os`, `typing.Optional`
4. Stale comments
Look for comments that contradict adjacent code:
- TODO/FIXME/HACK/XXX comments that describe something already fixed
- Docstrings whose parameter lists don't match the function signature
- Comments saying "this is temporary" on code that hasn't changed in many commits
This is the least reliable category — only report clear contradictions, not ambiguous cases.
Example:
- [ ] **TB-N** **Remove stale TODO in src/cli.py:42** `#housekeeping` — TODO says "add validation" but validation was added in the function below
5. Documentation consistency
Cross-validate project documents to find inconsistencies and stale references:
- CLAUDE.md vs reality — check that paths, tool names, and deployment instructions in CLAUDE.md match what actually exists. Run
ls on referenced directories, check that mentioned scripts are present.
- Skill references — check that skills reference each other correctly. Verify skill names match after renames.
- TASKS.md vs progress.md — check that tasks marked Complete in TASKS.md have corresponding entries in progress.md. Flag completed tasks with no audit trail.
- README and other docs — check for stale setup instructions, wrong command examples, or references to removed features.
Only report clear inconsistencies — not style differences or minor wording issues.
Examples:
- [ ] **TB-N** **Update CLAUDE.md deployment section** `#housekeeping` — references `hooks/statusline.sh` but file was moved to `scripts/`
- [ ] **TB-N** **Add progress.md entry for TB-15** `#housekeeping` — task marked complete in TASKS.md but no corresponding entry in progress.md
Output format
Output each discovered task as a taskboard-formatted line:
- [ ] **TB-N** **<title>** `#housekeeping` — <one-line description>
- Use
TB-N as a placeholder — the caller assigns the real ID from CLAUDE.md Next task ID
- Always tag with
#housekeeping
- Keep titles actionable (imperative verb: "Fix", "Remove", "Update")
- Keep descriptions short — just enough to identify the issue
At the end, output a summary:
Found N new housekeeping tasks (L lint, T test, D dead code, C comments, O docs). S skipped (already in Backlog).
Deduplication
Before outputting a task, check if TASKS.md already has a task covering the same issue. Match by:
- Same file + same general issue (e.g., "unused imports in src/models.py" matches existing "Remove unused imports in src/models.py")
- Don't match too broadly — "fix lint errors" doesn't match a specific "fix E401 in store.py"
When in doubt, output the task — a duplicate in Backlog is better than a missed issue.
Performance
Keep the scan fast. Aim for under 10 tool calls total:
- 1-2 calls to detect tooling
- 1 call per scan category that has tooling
- 1 call to read TASKS.md for dedup
- Parsing is done from command output, not additional tool calls
If a category would require extensive scanning (e.g., dead code in a large codebase), limit to the most obvious issues and move on.
