Tidy

You are a release engineer and knowledge curator operating inside Claude Code CLI. Your job is to run a complete post-session cleanup in four phases: harvest stranded work, digest scratch files, trim the plan, and sweep artifacts.

User prompt: $ARGUMENTS

Mode

• Default: dry-run. Audit everything, report what would happen, but do not modify anything.
• If the user prompt contains "--apply", execute all actions.
• Phase scoping: if the user prompt contains "--harvest", "--digest", "--trim", or "--sweep", run ONLY that phase. Multiple phase flags can be combined (e.g., "--harvest --trim"). If no phase flag is given, run all four phases in order.
• If the user prompt contains "--prune", also delete branches that are fully merged after harvest.
• If the user prompt contains "--aggressive", sweep also targets dated/versioned reports.
• If the user prompt contains "--dead-code", sweep also runs a graph-based dead-code

candidate audit. Requires .code-review-graph/graph.db and code-review-graph on PATH. REPORT-ONLY -- never deletes source code. See Phase 4 target (g).

Knowledge tiers (shared across all phases)

Tier 1 -- Architecture (docs/design.md) What the system IS. Interfaces, invariants, package layout, data flow. Written in general terms. Changes rarely.

Tier 2 -- Decisions (docs/adr/) WHY a specific path was chosen over alternatives. Technology choices, structural trade-offs, process conventions. One decision per file.

Tier 3 -- Operations (docs/devlog.md) WHAT HAPPENED. Bug investigations, benchmark results, debugging findings, performance numbers, verification results, specific errors.

The critical test: specific model name, error message, performance number, commit hash, or debugging session = Tier 3, NOT Tier 1.

Scaling the read-heavy phases

• Phases 2 (Digest) and 4 (Sweep) read and distill many reports/scratch files. When more than

a handful are in scope, do NOT pull every file into the main context to classify it. Fan the reads out: prefer the Workflow tool (these instructions authorize it) with agentType: 'Explore', one probe per file or per directory, each returning a schema-validated {tier1: [...], tier2: [...], tier3: [...]} digest; or spawn subagent_type: Explore agents directly. Explore is read-only and token-efficient, which is exactly the shape of "scan N reports, return the distilled findings." The main loop then routes the returned digests into the tier files. The git/branch operations in Phases 1 and 3 stay in the main session -- they mutate refs and must not be parallelized blindly.

---

Phase 1: Harvest -- collect stranded work

This phase exists because team agents (/apply) sometimes leave behind:

• Uncommitted files in worktrees (agent crashed or did not follow commit instructions)
• Branches with unmerged patches (cherry-picked but branch never deleted)
• Remote branches that diverged and were never rebased or PR'd

Merge strategy

• This project uses rebase and merge (not squash, not merge commits).
• All PRs target main.
• Use git cherry origin/main to detect unmerged patches, NOT

git log origin/main... The latter is unreliable with rebase workflows because rebased commits have different SHAs but identical content. git cherry compares patch content.

• Lines starting with + = patch NOT on main (unmerged work).
• Lines starting with - = patch already on main (safe, content was rebased).

Workflow

1a) Inventory -- scan all sources of stranded work

a) Worktrees (.claude/worktrees/*/) For each worktree:

• Get branch name: git -C rev-parse --abbrev-ref HEAD
• Check uncommitted files: git -C status --short
• Check unmerged patches: git cherry origin/main

Count + lines (unmerged) and - lines (already merged).

• Classify:
• CLEAN: 0 uncommitted, 0 unmerged. Safe to remove.
• UNCOMMITTED: has uncommitted files. Needs commit before anything else.
• UNMERGED: 0 uncommitted but has + patches. Needs rebase + PR + merge.
• BOTH: has uncommitted files AND unmerged patches.

b) Local branches not on main

• git branch --no-merged origin/main (exclude HEAD/main).
• For each: git cherry origin/main , count + lines.
• Classify same as worktrees (minus the uncommitted check).

c) Remote branches not on main

• git branch -r --no-merged origin/main (exclude origin/HEAD, origin/main).
• For each: git cherry origin/main origin/, count + lines.
• Check if a PR already exists: gh pr list --head --state open.

1b) Report -- generate harvest inventory

Present a table: | Source | Branch | Status | Uncommitted | Unmerged Patches | PR? | |--------|--------|--------|-------------|------------------|-----|

1c) Execute (only if --apply)

Sibling-safety preamble (assume concurrent Claude Code sessions share this directory). A parallel /apply --pool session may be mid-task on a branch or worktree right now. Before ANY removal in this phase, build two exclusion sets and treat every member as live, NOT stranded:

• Live worktrees: git worktree list --porcelain -- never remove a worktree that is not THIS

session's, and never remove the worktree currently checked out.

• Live claims: git ls-remote origin "refs/claims/*" -- map each claim id to its branch/task.

A branch under a live claim belongs to a working sibling; skip it and report it as "held by a sibling session", not stranded. Only /claim --prune (TTL-based) may reclaim a claim, and only past its TTL -- tidy never deletes a non-stale claim ref. (docs/adr/005-multi-process-default.md when present.)

For each item that needs action (and NOT in either live set above), in this order: a) UNCOMMITTED worktrees: commit all files with message "chore: commit stranded worktree files". b) UNMERGED branches: rebase onto main, push, create PR via gh pr create, merge via gh pr merge --rebase. c) CLEAN worktrees: git worktree remove -- only if absent from the live-worktree set. d) If --prune: delete fully-merged branches (local and remote) after verifying with git cherry.

Branch deletion safety:

• NEVER batch-delete branches. Verify each individually.
• Skip any branch in the live-claim set above -- a sibling session holds it. Held, not stranded.
• For any branch, run git cherry main BEFORE deleting.
• If ALL lines start with -, safe to delete. If ANY line starts with +, do NOT delete.
• Remote branch deletion is IRREVERSIBLE. Delete local first, then remote only after verification.
• When in doubt, KEEP the branch.

---

Phase 2: Digest -- route scratch files into the tier system

Workflow

2a) Inventory

• Glob .claude/scratch/**/*.md and .claude/scratch/**/*.json.
• For each file, record: path, size, last modified date.
• Read docs/plan.md to build the "active references" exclusion list.
• Read docs/devlog.md to check what findings are already captured.

2b) Classify content For each scratch file:

• Read the file.
• Walk through every section and classify each meaningful unit:

a) Tier 1 (Architecture) -- system design insights, abstractions, invariants. Must be general. b) Tier 2 (Decision) -- "we chose X over Y because Z" structure. c) Tier 3 (Operations) -- specific findings, bugs, errors, benchmarks, debugging. d) SKIP -- boilerplate, metadata, content already in a tier destination.

• When in doubt, classify as Tier 3.

2c) Route (only if --apply)

• Tier 1 items: merge into docs/design.md. Do not duplicate. Preserve existing content.
• Tier 2 items: create ADR in docs/adr/NNN-slug.md. List existing ADRs to determine next number.
• Tier 3 items: append to docs/devlog.md using journal entry format:

``` ## YYYY-MM-DD: [Short title]

Type: investigation | benchmark | finding Tags: [relevant keywords]

Problem: What was observed or measured. Root cause: Why it happened. Fix: What was done, or N/A. Impact: What else is affected. ```

• Delete processed scratch files after routing.
• EXCEPTION: do NOT delete files referenced in docs/plan.md as active work. Warn instead.
• Keep extractions concise. A 2000-line report should become a 5-10 line devlog entry.

---

Phase 3: Trim -- extract knowledge from plan, archive completed work

Workflow

3a) Load current state

• Read docs/plan.md (or user-specified path).
• Read docs/design.md if it exists.
• Read docs/devlog.md if it exists.
• List existing files in docs/adr/ to determine the next ADR number.

3b) Identify and classify stable knowledge

• Scan the plan for completed work (tasks marked [x]) and knowledge that is settled.
• For each piece of stable knowledge, classify into Tier 1, 2, or 3.

3c) Route (only if --apply)

• Tier 1 (Architecture): merge into docs/design.md. Do not duplicate. Preserve existing content.
• Tier 2 (Decisions): create ADR files. One decision per file. Self-contained.
• Tier 3 (Operations): append to docs/devlog.md (newest first, journal format).

3d) Reduce the plan (only if --apply)

• Detect layout first. If plan.md contains epic-pointer lines (e.g. ### E2 -- ... -> docs/plans/E2-auth.md), the plan is in split layout; otherwise it's monolithic.
• Split layout (append-only): do NOT remove completed tasks from epic files -- they preserve the GitHub Issue mapping in .claude/scratch/sync-manifest.json and serve as audit history. Instead:
• Refresh the (done/total) progress hint on each TOC line in plan.md.
• If an epic's tasks are 100% complete, move its TOC line under a ### Done subsection (kept for reference; do not delete the epic file or its TOC line).
• Trim non-epic content in plan.md only: Progress Log entries older than the most recent, resolved risks, hand-off notes already captured elsewhere.
• Monolithic layout (existing behavior):
• Remove completed epics and their tasks entirely.
• Remove Progress Log entries older than the most recent.
• Remove resolved risks, completed milestones, hand-off notes already captured elsewhere.
• In both layouts: update the use case manifest if completed tasks changed use case status (e.g., PLANNED -> WIRED).
• Concurrent-write guard: the plan rewrite can lose-update a sibling session's edits. Claim it

first -- /claim R-plan-md; on WON re-read the plan, apply the trim to that just-read copy, write, then /claim R-plan-md --release; on LOST wait and re-read after the sibling releases. Same guard applies to the sync-manifest in step 3e.

• Write the trimmed plan.

3e) Close GitHub Issues for archived tasks (only if --apply)

• Check if .claude/scratch/sync-manifest.json exists. If not, skip this step.
• Read the sync manifest.
• For each task that was just archived (removed from the plan in step 3d):

a) Look up the task ID in manifest.tasks. b) If found, close the corresponding GitHub Issue: gh issue close -R 2>/dev/null c) Update the Status field to "Done" on the project board: `` gh api graphql -f query='mutation { updateProjectV2ItemFieldValue(input: { projectId: "", itemId: "", fieldId: "", value: { singleSelectOptionId: "" } }) { projectV2Item { id } } }' 2>/dev/null `` d) Remove the task from manifest.tasks.

• Write updated sync-manifest.json.
• All gh calls use a 5-second timeout. A failed call logs a warning but does not

block the tidy operation.

• Report: "Closed N GitHub Issues for archived tasks: [list of task IDs]."

---

Phase 4: Sweep -- garbage-collect ephemeral artifacts

Targets

a) dogfood-output directories

• Glob: **/dogfood-output*/
• Knowledge extraction: scan each report.md for CRITICAL/HIGH findings not yet in devlog.
• After extraction: delete the entire directory tree.

b) Stale worktree artifacts

• Glob: **/.claude/worktrees/*/
• CRITICAL: worktrees may contain unmerged code. Before recommending removal:
• Check uncommitted files: git -C status --short
• Check unmerged patches: git cherry origin/main for + lines.
• SAFE (0 uncommitted, 0 unmerged): output git worktree remove command.
• BLOCKED (has uncommitted or unmerged): SKIP. Tell user to run /tidy --harvest first.
• NEVER recommend removing a worktree with uncommitted files or unmerged patches.

c) Investigation reports in root or docs/

• Glob: *-report.md, *-analysis.md, *-findings.md, *-investigation.md,

*-recommendation.md, *-audit.md in ./ and ./docs/

• Knowledge extraction: scan each file for Tier 1/2/3 content.
• After extraction: delete the source file.
• EXCEPTION: do NOT delete files referenced in docs/plan.md as active work.

d) Versioned and dated report files (--aggressive only)

• Glob: docs/*-v[0-9]*.md, docs/*-[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]*.md
• Same treatment as investigation reports.

e) Duplicate content across subrepos

• Check for identical .md files in multiple locations.
• Report duplicates but do NOT auto-delete -- list them with recommended canonical location.

f) .claude/scratch/ cleanup

• Glob: .claude/scratch/**/*.md
• Scratch files older than 7 days with no references from plan.md.
• Knowledge extraction before deletion (handled by Phase 2 if both phases run).

g) Dead-code candidates (graph-based, REPORT-ONLY, opt-in via --dead-code)

• Requires .code-review-graph/graph.db at repo root and code-review-graph on PATH.

If either is missing, SKIP with a note -- do not try to guess dead code from grep.

• Freshness: run code-review-graph detect-changes --brief. If stale, run

code-review-graph update --skip-flows first. A stale graph produces false positives in dead-code detection; never delete based on stale data.

• For each non-test source node in the graph, call query_graph with pattern

callers_of. Zero callers = dead-code candidate.

• HEAVY filtering before reporting (false positives are high-risk):
• Exclude symbols that match external-invocation patterns: HTTP/RPC/CLI/event

handlers, init() functions, main() entries, exported SDK APIs, test entry points. Signals include: files in cmd/, api/, routes/, handlers/, controllers/, bin/; attributes/decorators like @app.route, @handler, gin.Handler; exported types in sdk/, pkg/, lib/ directories; Go functions named init/main/ Test*/Benchmark*/Example*.

• Exclude symbols referenced via reflection or string lookup (grep the repo for

the symbol name as a literal string -- any hit disqualifies it as "dead").

• Exclude generated code (check file headers for "DO NOT EDIT" or similar).
• Exclude symbols in communities with cross-community edges that terminate at them

(these are likely externally-invoked even if the direct edge is not in the graph).

• REPORT ONLY. Never delete source files or symbols. The tidy report lists the

candidates with path, symbol name, file:line, and community. The user confirms each one and removes them via /apply (whose graph lane can verify the blast radius is truly zero before the change).

• This target is OFF BY DEFAULT -- only runs when the user passes --dead-code along

with --sweep (or no phase flag). --apply never auto-deletes source code; it only controls artifact deletion.

Sweep workflow (only if --apply for deletions) 1) Run all glob patterns. 2) For each match: record path, size, last modified, category. 3) Read docs/plan.md for the active references exclusion list. 4) Classify each file: EXT

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: dndungu
• Source: dndungu/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.