diff --git a/CLAUDE.md b/CLAUDE.md index 9d18d70..993dd61 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -203,9 +203,9 @@ Non-trivial work happens in a dedicated git worktree branched off the current br - **Parallel vs background**: multiple independent queries → send them in one message as parallel `Agent` tool calls. Long-running watchers (CI, builds) → `run_in_background: true`, then read output when notified. - **Multi-agent coordination**: see `~/.claude/multi-agent-comms.md` for lock patterns (e.g., `git-push` lock before pushing shared-branch fixes). - **Match model to task complexity via the `Agent` tool's `model` parameter** — pay for capability only when it earns it: - - **Haiku**: file renames, typo fixes, mechanical edits with a clear spec, simple lookups (grep for a symbol, find where X is called), reading a single file to answer a factual question, formatting/style fixes, running a single command and reporting output. Cheap, fast, good enough when the answer is mostly mechanical. - - **Sonnet** (default for most delegations): focused multi-file changes with clear requirements, writing a new test, implementing a well-specified function, code review of a single diff, migrating between APIs with known mappings. - - **Opus** (or stay on the current top-level model): architecture decisions, multi-file refactors where the shape is unclear, debugging gnarly bugs that need hypothesis iteration, reading a large unfamiliar codebase and synthesising a mental model, any work where "understanding" is the hard part rather than the mechanical output. + - **Haiku** (default for most delegations): file renames, typo fixes, mechanical edits with a clear spec, simple lookups (grep for a symbol, find where X is called), reading a single file to answer a factual question, formatting/style fixes, running a single command (or routine `gh`/`git` operations) and reporting output, implementing a tightly-specified function, writing a new test from a tight spec, code review of a small single-file diff, mechanical API/SDK migration where the mapping is documented, classifying or labelling items against a clear rubric (e.g. backlog triage chunks), summarising a single file or short diff. Cheap, fast, good enough when the answer is mostly mechanical or rubric-driven. + - **Sonnet**: focused multi-file changes where coordination across files needs judgement, implementing a function whose spec is mostly clear but has 1–2 design choices, code review of a multi-file diff or a diff with non-trivial logic, refactors with a clear target shape, agentic loops where each step requires non-trivial reasoning (not just rubric-driven labelling). Use when there's some judgement involved but not deep design or hypothesis iteration. + - **Opus** (or stay on the current top-level model): architecture decisions, multi-file refactors where the shape is unclear, debugging gnarly bugs that need hypothesis iteration, reading a large unfamiliar codebase from scratch (without `graphify-out/` available) to synthesise a mental model, any work where "understanding" is the hard part rather than the mechanical output. - **When in doubt, go one tier cheaper and see if the result is good enough** — it's easy to re-spawn on a stronger model if Haiku/Sonnet struggles, and the savings on routine work add up. - The main conversation's model is set by the user and doesn't change mid-session; this rule only applies to `Task` tool spawns. diff --git a/git-workflow.md b/git-workflow.md index f792231..6d9cc52 100644 --- a/git-workflow.md +++ b/git-workflow.md @@ -64,7 +64,7 @@ After every `git push` that publishes new commits, immediately enumerate **all** **Setup**: 1. Right after `git push`, run `gh run list --commit --json databaseId,name,status` to list every run for the pushed commit. Wait briefly (a few seconds) and re-list if the run list looks incomplete — workflows can take a moment to register. -2. For each run ID, spawn a separate background agent (`Agent` tool with `run_in_background: true`) named `ci-watch--` (e.g. `ci-watch-a1b2c3d-build`, `ci-watch-a1b2c3d-test`, `ci-watch-a1b2c3d-tf-validate`). Each name must be unique and addressable via `SendMessage`. +2. For each run ID, spawn a separate background agent (`Agent` tool with `run_in_background: true`, `model: haiku`) named `ci-watch---` (e.g. `ci-watch-a1b2c3d-build-123456789`, `ci-watch-a1b2c3d-test-123456790`). Each name must be unique and addressable via `SendMessage`. The watcher's core work — polling `gh run view`, fetching failed logs, classifying the failure — fits Haiku per CLAUDE.md §2. If the diagnosed fix requires non-trivial reasoning (multi-file logic bug, race condition), re-spawn just the fix step on Sonnet rather than forcing Haiku through it. 3. Each agent monitors **only its assigned run ID** — pass the run ID explicitly in the prompt so it doesn't poll the wrong workflow. **Each agent's job**: @@ -97,7 +97,7 @@ The loop applies to any project that uses CodeRabbit (or an equivalent automated ### 2. CodeRabbit-watcher background agent -Spawn a background `Agent` named `cr-watch-` that: +Spawn a background `Agent` named `cr-watch-` (`model: haiku` — polling, rate-limit handling, and the §3 triage into Actionable/Stylistic/Nitpick are all rubric-driven; re-spawn fix commits on Sonnet only if a finding requires non-trivial reasoning) that: - Polls `gh api repos///pulls/<#>/comments` and `gh pr view <#> --json reviews` every **60–120s** (never faster — CodeRabbit's own backend rate-limits review processing and aggressive polling won't make the review come faster). - Treats `429`, `403 secondary rate limit`, or any "rate limit" string in the response body as a **soft** error: log, sleep 120s, retry. Do not escalate. Rate-limit responses are normal during high-traffic windows; a watcher that escalates on every 429 wastes user attention. @@ -135,7 +135,7 @@ If conflicts span more than the immediate diff (e.g., a base-branch refactor mov ### 4. Wait for human merge — do NOT self-merge by default -After CI is green and CodeRabbit's loop has settled, hand off to the user. Spawn a background agent named `merge-watch-` that polls `gh pr view <#> --json state,merged,mergeCommit,mergedAt` until: +After CI is green and CodeRabbit's loop has settled, hand off to the user. Spawn a background agent named `merge-watch-` (`model: haiku` — polling and the routine §5 verifications (terraform plan, curl, simple Chrome MCP walkthroughs) are mechanical; if §5 verification turns out to need exploratory UI debugging, re-spawn that step on Sonnet) that polls `gh pr view <#> --json state,merged,mergeCommit,mergedAt` until: - `merged: true` → proceed to §5. - `state: CLOSED` and not merged → terminal, clean up, exit (and notify user that the PR was closed unmerged so any in-flight work can be re-planned). diff --git a/triage.md b/triage.md index 27807bf..7ff6695 100644 --- a/triage.md +++ b/triage.md @@ -216,9 +216,9 @@ For mid-to-large backlogs (~20+ untriaged items) or when the user explicitly ask **Choose model tier per agent** (`Agent` tool's `model` parameter): -- **Haiku**: chunks where most items are clearly typo / dup / stale on a quick read. -- **Sonnet**: most chunks. Default. -- **Opus**: chunks heavy with security findings, architecture proposals, or anything that needs judgement on priority calibration. +- **Haiku** (default): most chunks. Triage is mostly mechanical labelling against the rubric — typo/dup/stale, clear severity/effort calls, items with enough info in title+body to label without investigation. +- **Sonnet**: chunks where priority calibration needs judgement — items where severity vs. impact tradeoffs aren't obvious, or where the issue needs weighing against broader project context. +- **Opus**: rare. Chunks dominated by security findings (CVE-class issues needing exploitability assessment) or architecture proposals where evaluating the proposal itself requires deep design judgement. ## Three-pass approach for very large backlogs (100+ items)