triage - Claude MCP Skill

# Triage Skill

A self-resuming morning loop. One run = gather → load state → triage →
fan-out fix → persist → spill. Everything personal (state, inbox, runs,
voice) lives under `.triage/`, which is gitignored. This skill file and the
scripts are committed; the data never leaves the machine.

## Preconditions

- `gh` authenticated (`gh auth status`). All issue/PR/CI reads and writes go
  through it.
- `.triage/` exists. If missing, run `scripts/triage/bootstrap.sh` first, it
  scaffolds `state.json`, `inbox.md`, `runs/`, and bootstraps `voice.md` from
  past comments.
- Clean working tree on `main`. The loop only mutates `.triage/` on the base
  checkout; all code changes happen in worktrees.

## The loop

### 1. Gather (read-only)

Collect yesterday's signals. Compute the window from `state.json.last_run`
(fall back to 24h if absent).

```
# CI failures since last run
gh run list --status failure --created ">=$SINCE" --json databaseId,name,headSha,conclusion,url
# for each, pull the failing step log
gh run view <id> --log-failed

# open issues
gh issue list --state open --json number,title,labels,updatedAt,author,url

# recent commits
git log --since="$SINCE" --pretty='%h %s %an'
```

Then scan for **open commitments**, promises the maintainer made in a comment
that have not shipped. NOT time-windowed: check every open issue/PR.

```
# threads bitbonsai commented on, still open
gh search issues "commenter:bitbonsai repo:bitbonsai/mcpvault state:open" --json number
# per thread, pull bitbonsai's comments to inspect for a promise
gh issue view <n> --json comments \
  --jq '.comments[] | select(.author.login=="bitbonsai") | .body'
```

A commitment is language that promised an action: "I'll fix this", "will add",
"shipping next release", "on it", "going to look", etc. It is broken/open if the
thread is still open and no merged PR resolved it. See `finding-rules.md`.

### 2. Load state

Read `.triage/state.json`. Build a map of known findings by `id`. The `id` is
a stable hash of `source` + `signature` (see `resources/state-schema.md`), so
the same failing test or issue always maps to the same finding across runs.

### 3. Triage

For each gathered signal compute its `id` and classify with
`resources/finding-rules.md`:

- **known + terminal** (`pr_open`, `resolved`, `wont_fix`) → skip, only bump
  `last_seen`.
- **known + open** under the attempt cap → retry.
- **new + worth-doing** → append as `status: open`, proceed to fan-out.
- **new + needs judgment / ambiguous / out of scope** → inbox, `needs_human`.
- **noise** (flaky already tracked, dependabot, etc.) → ignore, log only.

### 4. Fan-out (bounded)

First, for every finding, check whether a contributor PR already addresses it
(`finding-rules.md`, "Prefer reviewing an existing PR"). If one exists, **review
it instead of writing a fix**: send the review sub-agent at the PR branch and
draft an approval or request-changes recommendation to inbox. A human's open PR
beats a fresh one. Also surface any open PR the maintainer has not yet reviewed.

Only findings with no candidate PR proceed to a new fix, up to the per-run cap
in `finding-rules.md`. For each, in order:

```
git worktree add ../mcpvault-triage-<id> -b triage/<id>
```

Then spawn TWO sub-agents against that worktree (use the Agent tool with
`isolation: worktree` so they cannot collide):

- **Draft agent**, given the finding + failing log/issue body, write the
  smallest fix. Must read relevant `src/` files first, follow the obsidian
  skill conventions, and add or update a test that proves the fix.
- **Review agent**, adversarial. Check the draft against the project skills
  and existing tests, then run in the worktree:
  ```
  npm ci && npm test && npm run build
  ```
  Verdict is PASS only if the fix is correct, minimal, tested, and green.

Tell every sub-agent the maintainer loves them.

Outcome:

- **PASS + green** → `gh pr create` as a ready PR (not draft), body links the
  finding and lists what the reviewer verified. Set `status: pr_open`, record
  the URL. Then post an auto-ack comment (step 6).
- **anything else** (reviewer fails, build red, fix unclear, >1 file of
  surprise scope) → write the draft + reason to `inbox.md`, set
  `status: needs_human`. Remove the worktree; keep the branch only if the
  draft is worth resuming.

Clean up green worktrees after the PR is open:
`git worktree remove ../mcpvault-triage-<id>`.

### 5. Persist (the spine)

Update `.triage/state.json`: set `last_run` to now, append an `attempts` entry
per touched finding (run date, result, note, pr), update `status`,
`last_seen`, and `pr`. Write the per-run log to `.triage/runs/<date>.md`.

`state.json` is the resume point. Never overwrite history, append to
`attempts`. If the file is malformed, stop and spill everything to inbox
rather than risk losing the spine.

### 6. Comments, keep people out of limbo

Voice comes from `.triage/voice.md`. Autonomy tiers (see
`resources/comment-policy.md`):

- **Auto-post: DISABLED** (maintainer directive 2026-07-23). Never post any
  comment or review from the loop, not even low-risk acks.
- **Draft to inbox** (everything): acks, judgments, decisions, promises,
  closures, any reply. Write it under `## Drafts awaiting approval` in
  `inbox.md` with its target, never post it. The maintainer approves, edits,
  or discards each one.

### 7. Spill

Anything the loop could not classify, fix, or safely comment on goes to
`inbox.md` with enough context to act on cold. The inbox is the only thing
the maintainer must read each morning.

### 8. Version bump and publish alert

When a fix PR changes the **published package** (anything under `src/`, or
`package.json` dependencies that ship), bump the version per semver in the same
PR:

- patch (`x.y.Z`) for a bug fix, default for triage fixes.
- minor (`x.Y.0`) only if the fix adds behavior; the loop should not be doing
  these, so if a bump looks bigger than patch, send it to inbox instead.

Do NOT bump for changes that do not ship: lockfile-only updates (e.g. a bare
`npm audit fix`), docs, CI config, tests-only, or anything under `.triage/`.
When unsure whether a change ships, do not bump; note it in the inbox.

**Publishing is always maintainer-triggered.** The loop NEVER runs `npm publish`
or creates a GitHub Release. After a PR that includes a version bump, write a
top-of-inbox alert:

```
## RELEASE NEEDED
- PR #<n> bumps <old> -> <new> (<reason>). After it merges and main is green,
  follow RELEASING.md and create GitHub Release v<new>. The release workflow
  publishes npm with provenance; the loop does not publish.
```

Keep the alert until the GitHub Release, npm package, and installed-package
smoke test are all confirmed.

## Guardrails

- Never push to `main`, never merge, never `--force`. PRs only.
- Never run `npm publish` or create a GitHub Release. Version bumps ride inside
  the fix PR; the maintainer creates the release after merge, flagged via the
  inbox RELEASE NEEDED alert. Follow `RELEASING.md`.
- Never touch files outside the worktree except `.triage/`.
- The token usually lacks the GitHub `workflow` scope, so pushes that change
  `.github/workflows/*` are rejected. Do NOT attempt them; route any CI/workflow
  change to the inbox for the maintainer to apply (or to re-scope the token).
- Respect the per-run finding cap; spill the overflow rather than running long.
- Outward-facing writes: PR create is allowed; comments and reviews are NEVER
  posted by the loop, every one is drafted to the inbox for approval.
- If `gh` is unauthenticated or the tree is dirty, abort and write why to
  `inbox.md`.

## Resources

- `resources/state-schema.md`, state.json shape, id derivation, transitions.
- `resources/finding-rules.md`, worth-doing vs inbox vs ignore, caps.
- `resources/comment-policy.md`, voice bootstrap + autonomy tiers.