project-cleanup

name

project-cleanup

description

Enhanced project cleanup with validation, audit, cleanup, and application phases. Trims TODO.md done items, condenses old SESSION.md entries, audits INSIGHTS.md, validates cross-doc consistency, fixes broken links, and adds missing CLAUDE.md gaps. Fully interactive — each section presents numbered sub-tasks, user picks which to run (1,2,3, all, skip). Use this whenever the user says "project cleanup", "cleanup project files", "trim the project", "clean up session", "compress old sessions", "audit insights", "check doc consistency", or any variation of wanting to maintain or audit the project's AI-facing documentation.

Project Cleanup — Enhanced

Complete project maintenance: Validation → Audit → Cleanup → Application.

Each phase presents numbered sub-tasks. User replies with task numbers to run (1,3,5, all, or skip), then those tasks execute sequentially with pauses for confirmation before application.

---

Preparation — Read all files

Before producing any proposal, read:

• TODO.md — full file
• SESSION.md — full file (KEY LEARNINGS + all chronological entries)
• INSIGHTS.md — full file
• CLAUDE.md — for gaps and content audit
• .gitignore — verify local-only working directories are excluded appropriately
• .reference/INDEX.md — verify it exists and is current
• .reference/ folder — list all files and check their metadata

Also identify:

• Project .claude/skills/ directory
• Global skills directory (if configured for cross-project reuse)

---

Phase 1 — VALIDATION (Check doc consistency)

Sub-tasks:

1. SESSION.md link audit — Check for broken/outdated file references
2. INSIGHTS.md file validation — Verify referenced files exist
3. .reference/ health check — Verify metadata complete + fresh (Last reviewed ≤ 30 days)
4. CLAUDE.md gap detection — Check if "CLAUDE.md Gaps" from INSIGHTS are documented
5. Broken internal refs in skills — Find stale paths in skill files

→ Which validation tasks to run? Reply: 1, 2, 3, 1,3,5, all, or skip

After user replies:

For each selected task, perform the audit and report findings:

• Task 1: List broken SESSION.md links + suggested corrections
• Task 2: List missing files/folders referenced in INSIGHTS.md
• Task 3: List .reference/ files with missing/stale metadata
• Task 4: List CLAUDE.md gaps NOT yet documented
• Task 5: List skill files containing stale .ai-notes/ paths

Present one task result at a time. After all selected tasks complete, ask:

Validation complete. Proceed to Phase 2 (Audit)?
→ Reply: yes, or skip to Phase 3/4

---

Phase 2 — AUDIT (Check INSIGHTS integrity)

Sub-tasks:

1. Skill Candidates — Check if skills exist + are complete
2. Skill Upgrades — Verify described improvements are in place
3. CLAUDE.md Gaps — Verify gaps aren't already documented
4. Automation Ideas — Verify scripts/aliases exist if created

→ Which audit tasks to run? Reply: 1, 2, 3, 4, 1,2, all, or skip

After user replies:

For each selected task, audit INSIGHTS.md entries and categorize:

• Task 1: ✅ Skill built, ⚠️ Partial, ❌ Still needed
• Task 2: ✅ Upgrade done, ⚠️ Partial, ❌ Still open
• Task 3: ✅ Already in CLAUDE, ❌ Still missing
• Task 4: ✅ Script exists, ❌ Still pending

Present findings one task at a time:

### [Task title] — Results
✅ [item] — [reason]
⚠️ [item] — [what's done vs missing]
❌ [item] — [still open]

→ Which to mark as done? Reply: numbers, "all ✅", or "no changes"

After all selected tasks complete, ask:

Audit complete. Proceed to Phase 3 (Cleanup)?
→ Reply: yes, or skip to Phase 4

---

Phase 3 — CLEANUP (Trim & compress project files)

Sub-tasks:

1. TODO.md — Tighten verbose done-item titles (preserve 3-line format)
2. SESSION.md — Condense old entries (keep last 10 full + KEY LEARNINGS)
3. INSIGHTS.md — Archive applied/stale items to 🗃️ Archive section

→ Which cleanup tasks to run? Reply: 1, 2, 3, 1,3, all, or skip

After user replies:

For each selected task, produce proposals:

Task 1 — TODO.md Done Item Compression

Done items follow the standard structure:

- [x] Task title
scope: ... | target: ... | owner: ... | next: ... | updated: YYYY-MM-DD
#tag1 #tag2 #tag3

Rule: Keep the full 3-line structure (title + metadata + tags). Compress only if:

• Title is unnecessarily verbose (shorten to essential info)
• Metadata line is complete and accurate (keep as-is)
• Tags are present (keep as-is)

Present as:

### TODO.md — Done items to review
[N] done items found (M lines total)

1. **[Current title]** → **[Proposed shorter title]**
   scope: [change?] | updated: [YYYY-MM-DD]
   tags: [keep as-is]

2. **[Current title]** → **[Proposed shorter title]**
   scope: [change?] | updated: [YYYY-MM-DD]
   tags: [keep as-is]

...

→ Compress which items? Reply: numbers, all, or skip

Keep the full 3-line format. Only shorten the title line if needed.

Task 2 — SESSION.md Condensing

### SESSION.md — Sessions to condense
Keeping entries [oldest date] → [date] in full (last 10)
Condensing [N] older entries:

[date] [title] → "[proposed 1-2 line summary]"
[date] [title] → "[proposed 1-2 line summary]"
...

→ Condense which sessions? Reply: numbers, all, or skip

Note: KEY LEARNINGS section is never touched.

Task 3 — INSIGHTS.md Archival

### INSIGHTS.md — Entries to archive
Based on Phase 2 audit results:

✅ [Entry title] — confirmed done
✅ [Entry title] — confirmed done
[Other entries: keep in place]

→ Archive which entries? Reply: numbers (just the ✅ ones), all ✅, or skip

---

Phase 4 — APPLICATION (Apply all confirmed changes)

Sub-tasks:

1. Fix broken links — Update SESSION.md + INSIGHTS.md references
2. Add missing CLAUDE.md gaps — Inject gaps found in Phase 1
3. Update .reference/ metadata — Refresh Last reviewed dates
4. Apply all file edits — Commit changes to TODO.md, SESSION.md, INSIGHTS.md, CLAUDE.md

→ Which application steps to run? Reply: 1, 2, 3, 4, 1,2,4, all, or skip

After user replies:

Execute each selected step:

Step 1 — Fix Broken Links

For each broken link identified in Phase 1:

• Update reference to correct path or new location
• Confirm each replacement before applying

Step 2 — Add Missing CLAUDE.md Gaps

For each gap identified in Phase 1 that's missing from CLAUDE.md:

• Read the relevant CLAUDE.md section
• Add one-liner explanation under appropriate section
• Update "Last reviewed" date in CLAUDE.md

Step 3 — Update Reference Metadata

For each .reference/ file:

• If touched recently: update Last reviewed to today
• If >30 days stale: flag for possible refresh (don't force)

Step 4 — Apply All Edits

Apply changes to all modified files:

• TODO.md (if Task 1 selected)
• SESSION.md (if Task 2 selected)
• INSIGHTS.md (if Task 3 selected)
• CLAUDE.md (if new gaps added)
• .reference/ files (if metadata updated)

---

Final Report

## Project Cleanup Complete — [YYYY-MM-DD]

### Validation (Phase 1)
- Tasks run: [selected]
- Issues found: [N links fixed, N gaps added, N metadata updates]

### Audit (Phase 2)
- Tasks run: [selected]
- Results: [N skills audited, N upgrades checked, etc.]
- Items marked done: [N]

### Cleanup (Phase 3)
- Tasks run: [selected]
- TODO.md: [N done items reviewed (titles tightened if needed, 3-line format preserved)]
- SESSION.md: [N sessions condensed, last N kept full]
- INSIGHTS.md: [N entries archived, N still open]

### Application (Phase 4)
- Tasks run: [selected]
- Files updated: TODO.md, SESSION.md, INSIGHTS.md, CLAUDE.md, .reference/*.md
- Total changes: [N links fixed, N gaps added, N metadata updates]

### Health Summary
- Broken references: ✅ fixed
- Missing CLAUDE.md gaps: ✅ added
- .reference/ metadata: ✅ current
- INSIGHTS.md: ✅ archived ([N] done, [N] open)

---

Notes on Judgment & Validation

On Validation (Phase 1)

• Broken links: Any .ai-notes/, .reference/, or ./ path that doesn't exist or points to the wrong location.
• Missing files: If INSIGHTS.md references a file that doesn't exist, flag as stale unless there's a clear reason (e.g., server script hasn't been created yet).
• .reference/ metadata freshness: Last reviewed ≤ 30 days = ✅ Fresh. >30 days = ⚠️ Check if still in use. >90 days = consider stale.
• CLAUDE.md gaps: A gap is "filled" if the concept exists somewhere in CLAUDE.md — doesn't matter if it's not in the expected section.
• Skill reference updates: If a skill was renamed or moved, update all references across project and global skills directories.

On Audit (Phase 2)

• Skill candidates: ✅ if skill folder exists AND SKILL.md contains the described functionality.
• Skill upgrades: ✅ if the SKILL.md contains the improvement; search for key concepts, not exact wording.
• CLAUDE.md gaps: ✅ if the concept is documented anywhere in CLAUDE. ❌ if not present.
• Automation ideas: ✅ if script exists and is functional (not a stub). ❌ if never created or is a placeholder.

On Cleanup (Phase 3)

• TODO done items: Keep full 3-line format per task (title | metadata | tags). Only shorten title if verbose. Always preserve scope/target/owner/updated/tags lines exactly. Don't strip structure down to just the title.
• SESSION.md condensing: When in doubt, keep more. If a session was a major milestone (migration, critical bug fix, security incident), give it 2-3 lines instead of 1.
• INSIGHTS archival: Only archive if work is confirmed done. Don't archive just because it's old. If an INSIGHTS "CLAUDE.md Gap" was identified but never added to CLAUDE.md, it stays open.

On Application (Phase 4)

• Link fixes: Update references systematically. If a file was moved from .ai-notes/ to .reference/, update all references at once.
• CLAUDE.md gap injection: Add gaps to the most relevant section. If no section fits, create a minimal subsection (1-2 sentences).
• Metadata refresh: Only update Last reviewed for .reference/ files; don't force-update files that haven't been touched recently. If a file is >90 days stale, flag for future refresh rather than updating today.

Never Delete

Critical rule: Never delete, only compress or archive. Everything moved to a compressed or archived form remains in project history. The project timeline matters.

---

Triggers & Invocation

Use this skill when user says:

• "project cleanup" — run all phases
• "project cleanup validation" — run Phase 1 only
• "project cleanup audit" — run Phase 2 only
• "project cleanup trim" — run Phase 3 only
• "project cleanup apply" — run Phase 4 only
• "fix doc links" — run Phase 1 Task 1 + Phase 4 Step 1
• "check reference health" — run Phase 1 Task 3
• "add claude gaps" — run Phase 1 Task 4 + Phase 4 Step 2
• Any variation of "cleanup", "audit", "trim", "consistency check", "doc sync", "fix references"