/process

name: process
description: "Process: retrospectives, session handoff, pair programming, subagent-driven development, condition-based waiting."
user-invocable: true
argument-hint: "[retro|handoff|pair|subagent|wait]"
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - Grep
  - Glob
  - Task
  - Agent
routing:
  not_for: "multi-phase feature work (use workflow), code review (use review)"
  triggers:
    - "what didn't work"
    - "negative results"
    - "route health"
    - "routing telemetry"
    - "review roi"
    - "hand off this session"
    - "package session state"
    - "session pickup"
    - "rehydrate session state"
    - "pair program"
    - "collaborative coding"
    - "micro-steps"
    - "step by step coding"
    - "walk me through"
    - "interactive coding"
    - "subagent per task"
    - "fresh context execution"
    - "plan execution"
    - "execute plan with agents"
    - "exponential backoff"
    - "retry pattern"
    - "wait for"
    - "poll until ready"
    - "retry until success"
    - "retro"
  category: process
  pairs_with:
    - workflow
    - testing
    - pr-workflow

Process Skill

Five modes. Parse the request to pick one. Default to **retro** when ambiguous.

| Signal | Mode | |--------|------| | Negative results, what didn't work, routing stats, review ROI, retro | **Retro** | | Hand off, package state, session pickup, rehydrate | **Handoff** | | Pair program, step by step, walk me through, one change at a time | **Pair** | | Subagent per task, execute plan, fresh context | **Subagent** | | Wait for, retry, backoff, poll, health check, circuit breaker | **Wait** |

---

Mode: Retro

Read-only retrospective. Two stores: `docs/what-didnt-work.md` (negative-results registry) and `learning.db` (routing/review telemetry via `scripts/learning-db.py`).

Subcommands

| Argument | Action | |----------|--------| | (none), what-didnt-work | Read `docs/what-didnt-work.md`. Group by date. Show each Decision verdict up front. If missing, report no negative results recorded. | | routing, route health | Run `python3 ~/.claude/scripts/learning-db.py route-health`, then `route-stats --by agent` (or the user's dimension). Present outcome basis before rates. | | reviews, review ROI | Run `learning-db.py review-roi` and `review-fps`. Present cost, findings, and false positives per agent in one table. |

For comparisons: `learning-db.py route-delta --from SHA_OR_DATE --to SHA_OR_DATE`.

---

Mode: Handoff

Two submodes sharing one state contract. HANDOFF packages work for the next session. PICKUP rehydrates from that package.

Handoff (ending/pausing work)

Produce a bullet package with these sections:

1. **Scope/status** -- task in one line, finished vs. remaining, blockers. 2. **Working tree** -- `git status -sb`; note unpushed commits and worktree path. 3. **Branch/PR** -- branch, PR URL, CI status (`gh pr checks`). 4. **Live processes** -- summarize relevant processes with attach/tail commands. Redact secrets. 5. **Tests/checks** -- commands, results, checked revision, log paths. 6. **Next steps** -- remaining actions in execution order. 7. **Risks/gotchas** -- flaky tests, feature flags, approvals needed.

Gate: every process has a copy-paste command; every pending step is ordered.

Pickup (starting on existing work)

1. Read the handoff and repository instructions. 2. Confirm branch, local commits, worktree path (`git status -sb`). 3. Check CI/PR (`gh pr view --comments`). 4. Check live processes from the handoff. Attach or tail logs. 5. Rerun only invalidated or missing checks. 6. Write next 2-3 actions as bullets, then execute.

Gate: branch, PR state, and first action confirmed. Observed state wins over handoff.

Constraints: separate observed from inherited results. Redact secrets. Scale detail to the next action.

---

Mode: Pair

**Announce-Show-Wait-Apply-Verify** micro-step protocol. Stay in the main session (forks cannot conduct user gates).

Setup

Read the request and code. Show a numbered plan (one logical change per step). Wait for acknowledgment. Track current step, remaining steps, and speed.

Per-step cycle

1. **Announce** the change and reason (1-2 sentences). 2. **Show** the proposed diff (default 15 lines, cap 50). Split larger changes into sub-steps. 3. **Wait** for a control command. 4. **Apply** only after `ok` / `yes` / `y`. 5. **Verify** with relevant checks. Report result in one sentence.

| Command | Action | |---------|--------| | `ok`/`yes`/`y` | Apply current step, propose next | | `no`/`n` | Skip, propose alternative | | `faster` | Double step size (cap 50) | | `slower` | Halve step size (min 5) | | `skip` | Skip to next step | | `plan` | Show remaining steps | | `done` | End pairing, run final verification |

"Just do it" = switch to autonomous mode for remaining authorized work.

---

Mode: Subagent

Execute a plan with fresh implementer subagents. Planning owns the plan format; this mode owns dispatch and integration.

Phase 1: SETUP

1. Read the plan once. Extract tasks with text, files, dependencies, and verify commands. 2. Track tasks as pending/in-progress/complete. 3. Capture `BASE_SHA` (`git rev-parse HEAD`), project conventions, and relevant context. 4. Check scope overlap: `python3 scripts/check-scope-overlap.py --tasks '<json>'`. Serialize overlapping writes; parallelize independent groups.

Gate: tasks, BASE_SHA, context, and scope checks ready.

Phase 2: EXECUTE (per task)

1. Mark in-progress. Dispatch implementer with full task text and context. 2. Dispatch ADR compliance reviewer. Fix requirement failures before code quality. 3. Dispatch code quality reviewer. Fix Critical and Important findings; Minor optional. 4. Mark complete. After three failed reviews at either stage, stop and report.

Gate: requirements and code quality pass per task.

Phase 3: FINALIZE

1. Review combined `BASE_SHA..HEAD` diff for cross-task conflicts and integration issues. 2. Follow the author