khamel83/janitor

/janitor — Project Debrief

Reads janitor signal files and gives you a plain-language status report.

Usage

/janitor              Full debrief (everything)
/janitor status       Quick summary only
/janitor stale        Stale documents and content freshness
/janitor orphans      Unlinked/orphaned documents
/janitor risks        Bus factor, critical files, test gaps
/janitor activity     Recent changes and session focus

Process

Step 1: Read project type

cat .janitor/project-type.json

Returns {"type": "code"|"document"|"hybrid"}. Use this to decide which signals are relevant.

Step 2: Read session context

cat .janitor/recent-focus.json

Get session_count for the header. Check files and commands for what's been active.

Step 3: Read the onboarding summary (if it exists and is fresh)

Read CLAUDE.local.md. If the first line says "Auto-generated by janitor" and the file was modified within the last 24 hours, use it as the foundation. Otherwise, build from raw signals.

Step 4: Read signal files based on subcommand

| Subcommand | Files to read | |-----------|--------------| | (none / full) | All files below | | status | project-type.json, recent-focus.json, CLAUDE.local.md | | stale | doc-staleness.json, doc-recent-activity.json | | orphans | doc-orphans.json, doc-crossrefs.json | | risks | knowledge-risk.json, critical-files.json, test-gaps.json, code-smells.json | | activity | doc-recent-activity.json, recent-focus.json, doc-crossrefs.json |

Read each file with the Read tool. If a file doesn't exist, skip it.

Step 5: Synthesize

Turn the raw JSON into a debrief. Follow these rules:

1. Every finding MUST include a file path. "Auth module has issues" is useless. "core/auth.py has 0 tests and 1 contributor" is useful.
2. Use specific numbers. "3 stale docs (45+ days old)" not "some old files".
3. Skip empty sections. If there are 0 stale docs, don't mention staleness.
4. Adapt to project type. Document repos → focus on staleness, orphans, clusters. Code repos → focus on test gaps, smells, deps. Hybrid → show both but prioritize.
5. End with actionable next steps. Numbered, specific, with file references.

Output Format

## Project Debrief: [repo name from basename]
**Type:** code/document/hybrid | **Sessions:** N | **Signals:** fresh/stale

### Status
[2-3 sentence summary. Use CLAUDE.local.md if fresh, otherwise synthesize from signals.]

### Stale Content  [only if stale_count > 0]
- `file.md` — N days since last edit
- ...

### Orphan Documents  [only if orphan_count > 0]
- `file.md` — not linked from any other file
- ...

### Test Gaps  [only if gap_count > 0 and code/hybrid]
- `file.py` — changed recently, no tests

### Code Quality  [only if smells exist and code/hybrid]
- N oversized files, N long functions
- Top: `file.py` (N lines)

### Critical Files  [only if entries exist]
- `file` — touched in N sessions, N downstream deps

### Knowledge Risk  [only if at_risk entries exist]
- `file` — sole contributor: Name, N edits

### Recent Activity
- `file` — Nx by Author
- ...

### Recommended Actions
1. [Specific action with file reference]
2. [Specific action with file reference]
3. [Specific action with file reference]

Signal File Reference

| File | Keys | Project Type | |------|------|-------------| | project-type.json | type | all | | recent-focus.json | files, commands, session_count | all | | doc-staleness.json | stale_count, fresh_count, stale_files[] | doc/hybrid | | doc-orphans.json | orphan_count, orphan_files[], total_documents | doc/hybrid | | doc-clusters.json | cluster_count, clusters[] | doc/hybrid | | doc-size-outliers.json | outlier_count, outliers[] | all | | doc-recent-activity.json | changes_count, recent_changes[] | doc/hybrid | | doc-crossrefs.json | documents_with_links, most_referenced[] | doc/hybrid | | test-gaps.json | gap_count, gaps[] | code/hybrid | | code-smells.json | oversized_files[], oversized_functions[] | code/hybrid | | dep-graph.json | files_with_imports, impact_ranking[] | code/hybrid | | critical-files.json | critical_files[] | all | | knowledge-risk.json | at_risk[] | all | | config-drift.json | drift_count, drifted_file_names[] | all | | blockers.json | blockers[] | all | | dead-ends.json | dead_ends[] | all |

Notes

• If .janitor/ doesn't exist, say "No janitor data found. Start a Claude Code session here to generate signals."
• All data is computed from git + file analysis. No LLM calls needed for the debrief itself.
• For the full debrief, prioritize: blockers > risks > staleness > activity > orphans > clusters > crossrefs