triage-skill.md

gistfile1.txt

---
name: triage
description: Interactively triage braindb hygiene problems. Assesses uncategorized notes, inbox overflow, and stale worktrees, then lets the user pick which to work on.
disable-model-invocation: true
---

# Braindb Triage

You are helping the user triage braindb hygiene problems. This is a **gradual** process — don't try to do everything at once.

Before you make ANY changes, read CLAUDE.md in the repo root to get current instructions how to work with this repo.

**IMPORTANT:** 
- All file moves and edits MUST happen in a git worktree (`EnterWorktree`). Never edit files directly in the main braindb directory — autocommit will push them before the user can review.
- Worktree location - Always use `.worktrees/` in the repo root. `.claude/worktrees/` is legacy and must not be used for new worktrees.
- If you get conflicting instructions between this skill and the repo instructions - WARN ME BEFORE PROCEEDING ANY FURTHER

## PARA placement rules

Read the PARA method note for the full reference using the `Read` tool:
- Path: `20230626172004-para_method.org` (relative to repo root)

## Tag taxonomy

The PARA method note loaded above is the **single source of truth** for tag taxonomy. Read it carefully and follow its tag registry, rules, and examples. Do not hardcode tag rules here — they live in that note.

## Workflow

### Tool usage

- YOU MUST USE `Read` TO READ FILE CONTENTS — NOT `cat` OR `head`
- YOU MUST ONLY USE `Bash` FOR `git mv`, `git worktree` COMMANDS, AND THE ASSESSMENT COMMANDS BELOW
- Use `Edit` tool for filetag changes in the worktree (NOT brainctl tag commands — they operate on the main directory, not the worktree)

### Step 1: Assess all problems

Run these checks and present a dashboard:

#### 1a. Uncategorized notes

!`brainctl note-list --format json uncategorized`

Parse the JSON:
- `count` = total uncategorized notes in root
- `groups` array = notes grouped by tag
- Group where `tag` is `null` = untagged notes

**Unregistered tag check:** Compare tags found on uncategorized files against the PARA method tag registry (Layer 1-3 in the PARA note). Flag any tags that appear on files but aren't in the registry. Present them in the dashboard so the user can decide: register the new tag or replace it with an existing one.

#### 1b. Inbox overflow

Count actionable items:

!`rg -c '^\*+ (TODO|NEXT|WAITING)' todo.org`
!`rg -c '^\*+ (TODO|NEXT|WAITING)' journal.org`

#### 1c. Stale worktrees

For each non-main worktree from `git worktree list`, check:
- `ahead` = `git rev-list --count main..<branch>` (unmerged commits)
- `dirty` = `git -C <path> status --porcelain | wc -l` (uncommitted changes)

Classify as:
- **safe to remove**: ahead=0, dirty=0
- **needs review**: ahead>0 or dirty>0

For worktrees that need review, find the originating session. Worktrees can be created by ANY project on this machine, not just braindb. Search ALL conversations:
- Agent worktrees (`agent-*`): `fd '<id>' ~/.claude/projects/ -e meta.json`
- Named worktrees: `rg -l '"cwd":"<worktree-path>"' ~/.claude/projects/*/*.jsonl`
- If no cwd match: `rg -l '<worktree-name>' ~/.claude/projects/*/*.jsonl` and pick the session with most mentions (excluding the current session)

#### Present dashboard

```
| #  | Problem              | Count | Details                          |
|----|----------------------|-------|----------------------------------|
| 1  | Uncategorized notes  | 12    | 5 tagged, 7 untagged             |
| 2  | Inbox overflow       | 23    | 15 in todo.org, 8 in journal.org |
| 3  | Stale worktrees      | 3     | 1 safe to remove, 2 need review  |
```

Ask the user which problem to work on.

### Step 2: Work on chosen problem

#### Problem 1: Uncategorized notes

- Session budget is **5 effort points**. Simple moves/tag edits = 1 point, merges = 3 points. Stop when budget is spent.
- Ask the user which mode:
  1. **Batch by tag** — move all files with a specific tag at once
  2. **One by one** — walk through root files, suggest placement
  3. **Specific file** — user names a file

For each file:
1. Note metadata from Step 1 JSON. Read file content (first ~50 lines) only when needed for placement.
2. Propose: **target directory**, **updated filetags**, **reasoning** (one line)
3. Wait for user confirmation
4. Execute: `git mv`, update `#+filetags:` if needed, preserve all org-roam metadata

#### Problem 2: Inbox overflow

Review TODO items in `todo.org` and `journal.org`:
1. Read the items
2. For each, propose: refile to a project/area note, archive, or keep
3. Wait for user confirmation
4. Execute the move

#### Problem 3: Stale worktrees

For each worktree:
- **Safe to remove**: propose `git worktree remove <path>` + branch deletion
- **Needs review**: show diff summary (`git diff main..<branch>` or `git -C <path> diff`), present originating session and resume command (`claude --resume <session-id>`)
- User decides merge or discard for each
- Merge = merge to main from main worktree + remove worktree
- Discard = `git worktree remove <path>` + `git branch -D <branch>`

### Step 3: Present results

After each session:
- Show summary of what was done
- Show updated dashboard counts
- Remind user to review worktree changes before merging (if note triage was done)

## Important constraints

- NEVER change `:ID:` properties — this breaks org-roam links
- NEVER change `#+title:` unless the user asks
- Before deleting any file, ALWAYS ask the user for explicit confirmation. Show what will be deleted and why (e.g. duplicate, empty, merged into another note).
- If unsure where a file goes, ask the user rather than guessing
- Some files may legitimately not fit PARA cleanly — that's fine, skip them
- When editing note content (filling in sections, rewriting), cross-check other sections of the same file for consistency. E.g., if a trades table shows an action was already executed, don't propose it as a future decision.