| 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/<name> rev-parse HEAD
git merge-base --is-ancestor <HEAD> origin/main # YES/NO
git -C .worktrees/<name> symbolic-ref --short HEAD # branch name
git -C .worktrees/<name> log -1 --format=%ci # last commit date
git rev-list --count origin/main..<branch> # ahead count
git rev-list --count <branch>..origin/main # behind count
git -C .worktrees/<name> 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/<analysis-wt>/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
git -C .worktrees/<name> merge-base --is-ancestor HEAD origin/main
git -C .worktrees/<name> status --porcelain
git -C .worktrees/<name> log --oneline origin/main..HEAD
git -C .worktrees/<name> diff --stat origin/main...HEAD
Output
first-pass-table.md — one-line-per-worktree table with columns: worktree, branch, date, ancestor?, status, commits, files Δ, meaningful?, summaryworktrees-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
-
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.
-
Finish work — significant progress towards something useful, but still has bugs, open questions, or integration gaps.
-
Throw away — useless — superseded by different work, the user/session history made clear this was a mistake or dead end.
-
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:
- Git analysis:
log origin/main..HEAD, diff origin/main...HEAD, diff origin/main...HEAD --stat
- Check if on main already:
git merge-base --is-ancestor, grep for key identifiers in origin/main, compare blob hashes
- Check for superseding work: search
origin/main for related keywords and implementer commits
- Run relevant tests:
npm run test:vitest -- run <test-pattern> to verify the work still works
- Check if the bug still exists: read current code on main to see if the bug scenario is still present
- Look for context: check
~/.claude/projects/freshell/sessions/, ~/.codex/, ~/.config/opencode/ for session history
- 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/<analysis-wt>/deep-dive/<NN>-<topic>.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/<analysis-wt>/
├── baseline-criteria.md
├── first-pass-table.md
├── worktrees-to-deep-dive.txt
├── deep-dive/
│ ├── 01-<topic>.md
│ ├── 02-<topic>.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
- Delete worktrees in "already in main" and "skipped" categories
- Create PRs for "ready for landing" branches
- For "finish work" branches, file katas describing the problem, referencing the worktree and assessment
