diff --git a/.claude/skills/triage-old-worktrees/SKILL.md b/.claude/skills/triage-old-worktrees/SKILL.md new file mode 100644 index 000000000..296a4be45 --- /dev/null +++ b/.claude/skills/triage-old-worktrees/SKILL.md @@ -0,0 +1,185 @@ +--- +name: triage-old-worktrees +description: "Use when auditing stale worktrees in Freshell to determine which contain novel unmerged work, which should be landed, which need finishing, and which can be safely deleted." +--- + +# Triage Old Worktrees + +## When to Use + +Use this skill when the repo has accumulated worktrees in `.worktrees/` whose branches may or may not have been merged into `main`. This skill provides a systematic, agent-driven process to classify each worktree and produce a clear action plan. + +## Prerequisites + +- `origin/main` is the integration branch (Freshell policy) +- Merge-commit PR workflow — branch tips become ancestors of `origin/main` when merged +- Worktree branches start from `origin/main` and target PRs to `main` + +## Process Overview + +``` +01-baseline → Establish safe-to-ignore criteria & filter worktrees +02-first-pass → One subagent scans all candidate worktrees for novel work +03-second-pass → Parallel deep-dive subagents for meaningful worktrees +04-aggregate → Produce final report (md + csv + html) with verdicts +``` + +Each step produces files in the analysis worktree. The final output drives deletion decisions and work-to-land prioritization. + +--- + +## Step 1: Establish Baseline Criteria + +Deploy a subagent to review the codebase and worktree inventory (`.worktrees/branch-inventory.json` if it exists) and establish criteria for "safe to ignore." + +### Criteria Categories + +**Category A — Auto-Skip / Safe to Delete (no deep dive needed):** +- HEAD is ancestor of `origin/main` AND working tree is clean AND branch has 0 ahead commits +- Plan-only or doc-only branches (`plan/*`, `docs/*`, `proof-*`) +- Trivial changes (< 5 lines, config-only, test-reorder-only) +- Branches already recorded as superseded in `branch-inventory.json` + +**Category B — First-Pass Only (quick inspection):** +- ANCESTOR=YES + dirty working tree (check `git diff` for lost work) +- ANCESTOR=NO + stale trivial branch (1-5 ahead, 100+ behind `origin/main`) +- ANCESTOR=NO + trivial naming pattern (`plan/*`, `docs/*`, `proof-*`, `port/*`, `debug/*`, `test/*`, `chore/*`) AND ahead <= 20 + +**Category C — Deep-Dive Required:** +- ANCESTOR=NO + ahead > 5 +- ANCESTOR=NO + behind == 0 (truly novel, no mainline catch-up) +- Any `feat/*`, `fix/*`, `codex/*`, `freshagent-*`, `freshcodex-*`, `freshopencode-*`, `opencode-*`, `rollback/*` branches +- Dirty working tree on any meaningful branch + +### Baseline Data to Gather + +For each worktree in scope: +``` +git -C .worktrees/ rev-parse HEAD +git merge-base --is-ancestor origin/main # YES/NO +git -C .worktrees/ symbolic-ref --short HEAD # branch name +git -C .worktrees/ log -1 --format=%ci # last commit date +git rev-list --count origin/main.. # ahead count +git rev-list --count ..origin/main # behind count +git -C .worktrees/ status --porcelain # working tree check +``` + +Filter to the desired time window (e.g., `past 4 weeks` = `date > "2026-05-23"`). + +Write baseline criteria to `.worktrees//baseline-criteria.md`. + +--- + +## Step 2: First Pass — Novel Work Detection + +Deploy **one fresh (no-context) subagent** to run the process over all worktrees in scope. For each worktree, it determines whether the worktree contains novel work not landed on `origin/main`. + +### Checks Per Worktree + +```bash +git -C .worktrees/ merge-base --is-ancestor HEAD origin/main +git -C .worktrees/ status --porcelain +git -C .worktrees/ log --oneline origin/main..HEAD # unmerged commits +git -C .worktrees/ diff --stat origin/main...HEAD # change scope +``` + +### Output + +- `first-pass-table.md` — one-line-per-worktree table with columns: worktree, branch, date, ancestor?, status, commits, files Δ, meaningful?, summary +- `worktrees-to-deep-dive.txt` — list of worktrees needing second pass +- Skip plan-only worktrees and trivial (< 5 line) changes from deep dive + +--- + +## Step 3: Second Pass — Deep Evaluation + +Deploy **multiple fresh subagents in parallel**, grouped by topic area (3-4 worktrees per subagent). Each subagent dives deep on its assigned worktrees and produces a verdict. + +### Verdict Categories + +1. **Ready for landing** — work is done, never landed, seems useful. After thorough static analysis, code review, and optional test runs, the work is complete and worthwhile. + +2. **Finish work** — significant progress towards something useful, but still has bugs, open questions, or integration gaps. + +3. **Throw away — useless** — superseded by different work, the user/session history made clear this was a mistake or dead end. + +4. **Throw away — in main already** — the same functionality already landed on `origin/main`, possibly via a different implementation. + +### Deep-Dive Checks + +For each worktree, the subagent should: + +1. **Git analysis:** `log origin/main..HEAD`, `diff origin/main...HEAD`, `diff origin/main...HEAD --stat` +2. **Check if on main already:** `git merge-base --is-ancestor`, grep for key identifiers in `origin/main`, compare blob hashes +3. **Check for superseding work:** search `origin/main` for related keywords and implementer commits +4. **Run relevant tests:** `npm run test:vitest -- run ` to verify the work still works +5. **Check if the bug still exists:** read current code on main to see if the bug scenario is still present +6. **Look for context:** check `~/.claude/projects/freshell/sessions/`, `~/.codex/`, `~/.config/opencode/` for session history +7. **If in doubt:** deploy a fresh subagent to render the verdict. Never defer to the user. + +### Topic Grouping + +Group worktrees by topic to minimize context switching within a subagent: +- OpenCode/freshopencode/freshcodex +- Fresh agent UI +- Terminal/catchup/replay +- Settings/electron/codex +- Tab status / reliability + +Each deep-dive report goes to `.worktrees//deep-dive/-.md`. + +--- + +## Step 4: Aggregate Final Report + +Deploy one subagent to read all deep-dive reports, baseline criteria, and first-pass table, then produce three files: + +### `final-report.md` +- Executive summary with verdict counts +- Section per verdict category (Ready for Landing, Finish Work, In Main Already, Skipped) +- Each worktree listed with: name, branch, date, verdict, evidence summary, recommendation narrative +- Full reference table sorted by recency + +### `final-report.csv` +- Columns: `num,worktree,branch,date,verdict,category,analysis` +- One row per audited worktree +- Categories: `ready-landing`, `finish-work`, `in-main`, `skipped-plan`, `skipped-trivial` + +### `final-report.html` +- Standalone, self-contained HTML (no external dependencies) +- Color-coded cards per verdict: green=ready-landing, yellow=finish-work, gray=in-main, light-gray=skipped +- Summary cards with counts +- Sortable/filterable table +- Links to deep-dive report files (relative paths) + +--- + +## Expected Outcomes + +After completing all steps, the analysis worktree contains: + +``` +.worktrees// +├── baseline-criteria.md +├── first-pass-table.md +├── worktrees-to-deep-dive.txt +├── deep-dive/ +│ ├── 01-.md +│ ├── 02-.md +│ └── ... +├── final-report.md +├── final-report.csv +└── final-report.html +``` + +The final report tells you: +- Which worktrees to delete (already merged / skipped) +- Which worktrees to land (ready for landing) +- Which worktrees need finishing (what's incomplete, what's blocking) +- Which are the highest priority (the "0 behind main" worktrees with novel commits) + +## After the Audit + +1. Delete worktrees in "already in main" and "skipped" categories +2. Create PRs for "ready for landing" branches +3. For "finish work" branches, file katas describing the problem, referencing the worktree and assessment