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 authorized completion path (pr-workflow).

Gate: combined changes work, required checks pass.

---

Mode: Wait

Implement condition-based polling and retry patterns with bounded timeouts.

Pattern selection

Scenario	Pattern
Wait for condition to become true	Simple poll (timeout + min interval)
Retry failing operation	Exponential backoff (max retries + jitter + delay cap)
API returns 429	Rate limit recovery (Retry-After + fallback)
Wait for service(s) to start	Health check (all-pass + per-check status)
Prevent cascade failures	Circuit breaker (failure threshold + recovery timeout)

Shared rules

• Read CLAUDE.md and search for existing wait/retry patterns first.
• Every loop needs a mandatory timeout. No infinite waits.
• Use time.monotonic() for elapsed time, never time.time().
• Minimum poll interval: 10ms in-process, 100ms external services.
• Jitter is mandatory on exponential backoff (prevents thundering herd).
• Classify errors before retrying: 408/429/500/502/503/504 are retryable; 400/401/403/404 are not.
• Log each attempt with failure reason and attempt number.
• Test both success and timeout/exhaustion paths.

Simple poll core

start = time.monotonic()
while time.monotonic() < start + timeout:
    if condition():
        return result
    time.sleep(interval)
raise TimeoutError(f"Timeout waiting for: {description}")

Exponential backoff core

for attempt in range(max_retries + 1):
    try:
        return operation()
    except retryable_exceptions:
        if attempt >= max_retries: raise
        jitter = 1.0 + random.uniform(-0.5, 0.5)
        time.sleep(min(delay * jitter, max_delay))
        delay = min(delay * backoff_factor, max_delay)

For full implementations (rate-limited client, health check waiter, circuit breaker), detection commands, and test patterns, load the deep references.

---

Deep References

Signal	Load	Content
Writing wait/retry implementations	references/cbw-implementation-patterns.md	Complete Python/Bash code for all 5 patterns
Reviewing wait/retry code for mistakes	references/cbw-preferred-patterns.md	Detection commands and fixes for common mistakes
Testing wait/retry code	references/cbw-testing-patterns.md	pytest patterns for polling, backoff, circuit breaker