agent-traffic-control

Diagnose and bypass `gh pr merge --squash --delete-branch` failing with "failed to run git: fatal: 'main' is already used by worktree at ..." when another git worktree has main checked out. Use when: (1) you run gh pr merge and see this exact error, (2) you have multiple worktrees in the repo (e.g. `.claude/worktrees/*`), (3) the error appears even though the GitHub merge itself looks fine. The merge SUCCEEDED on GitHub — only gh's local-side effect (post-merge `git checkout main`) failed. Verify via `gh pr view N --json state,mergedAt`; if state=MERGED, you're done. This also applies to `gh pr checkout` and any other `gh` subcommand that tries to touch the local main branch while another worktree has it claimed. v1.2.0 (2026-05-26) adds the sequential-error variant: if you re-run from the main-repo worktree after the first error, you can then hit "cannot delete branch <feature-branch> used by worktree at <feature-worktree>" — same one-checkout-per-branch invariant, this time applied to the feature branch. Cl

When generating LONG Chinese/Japanese/Korean (CJK) STRUCTURED output (a big JSON report, a multi-section document) from an LLM chat API, the response truncates mid-JSON and your parser throws "no parseable JSON" / "Expecting ',' delimiter" / JSONDecodeError — even though the SAME prompt in English worked. Root cause: CJK is token-heavy (≈1–2 tokens per character vs ≈0.25 for English), so a report that fit your max_tokens in English overflows it in Chinese. Some models ALSO hard-cap output well below what you request (e.g. qwen-max caps at 8192) and silently truncate. Use when: a zh/ja/ko structured-generation run fails JSON parsing, worked in English, or a specific model truncates while others on the same prompt succeed. Covers the ~2× token budget rule, per-model output caps, and a salvage that recovers the complete sections from a truncated object.

Catch the failure where a subagent dispatched ONLY to DECIDE/DESIGN (a judge, a design-panel synthesizer, a "pick the mechanism" agent) instead EXECUTES the plan — and, having full Bash/gcloud/bq, provisions LIVE infrastructure (creates a BQ dataset/table, a DTS scheduled query, a log metric, a paging alert policy) and even git-commits code — when you only wanted a recommendation. Use when: (1) you author a Workflow/Agent whose structured-output schema has a field that reads as an execution mandate ("this_session_plan", "exact ordered steps", "deploy_steps", "what was provisioned") and the agent has mutate-capable tools; (2) a design/judge agent's result says "DONE — created X" / "provisioned live" instead of "recommend X"; (3) you are about to trust a decision agent's self-report of what it changed. The agent treats a "plan/steps" output field as a TODO to carry out, not a proposal. Fix: constrain design/decision subagents READ-ONLY in the prompt (explicitly: "do NOT run any mutating bq/gcloud/git command; S

Prevent (and recover from) `git add -u` + `git commit --amend` + `git push --force-with-lease` catastrophically rolling thousands of unrelated tracked-file deletions into an amended commit when the project has an async post-commit hook that mutates tracked files (e.g. regenerates `docs/site/*.html`, `docs/site/index.html`, `MEMORY.md`, or any other tracked artefact in a background `&` / `nohup` / "running … in background" process). Use when: (1) you just made a small commit, the post-commit log line says `[post-commit] … running … in background`, and you're about to amend with corrected message / typo / issue ref; (2) `git commit --amend` output reports `1000+ files changed, … insertions, NNN,NNN deletions(-)` when you only intended a 6-file change; (3) the force-pushed branch on origin shows a massive deletion diff and `git status` after the amend shows previously-tracked files like `MEMORY.md`, `.github/`, `.cursor/`, `scripts/` as Untracked; (4) you ran `git add -u` reflexively before `--amend` on a projec

Prevent and diagnose nested git worktrees created at the wrong filesystem path when orchestrating parallel work from the main Claude Code agent. Use when (1) you ran `git worktree add .claude/worktrees/<name> ...` from the main agent's Bash tool, (2) `git worktree list` shows the new worktree at an unexpected nested path like `.claude/worktrees/<previous-worktree>/.claude/worktrees/<name>` instead of the intended top-level location, (3) a subagent dispatched to the intended path reports "worktree path mismatch" or operates from a longer nested path. Root cause: the main agent's Bash tool **persists cwd between calls** (per its docstring: "The working directory persists between commands"). An earlier `cd /abs/path && cmd` changes the main shell's cwd; a later `git worktree add <relative-path> ...` resolves against that persisted cwd rather than the project root, silently creating nested layouts. This is the **inverse** of the subagent variant (subagent-bash-cd-wrong-worktree) — subagent shells reset per call,

Diagnose "I merged my PR + CI is green but the live service still doesn't show my changes." Use when: (1) a code-bearing PR has been squash-merged into main with all required status checks passing, (2) the user reports the change is still missing from the deployed environment minutes-to-hours later, (3) the repo has a `pull_request: types: [closed]` workflow gated on a label (typically `auto-deploy`, `deploy`, `ship-it`) and/or a path filter, (4) the deploy workflow's run row in `gh run list` shows `conclusion=skipped` for your PR's branch — visually identical to `success` in the run summary. Distinct from `gha-auto-deploy-never-ran-skipped-mask` (sister skill: same "skipped masks failure" symptom class but different cause — that skill is about the FIRST time the gate fires and the deploy step then hits a permission gap; THIS skill is about the routine case where the gate correctly works and the PR simply didn't satisfy it). Trigger phrases: "I can't see the changes live", "merged but not deployed", "PR shipp

When a large Workflow/Agent fan-out (dozens of parallel subagents on Opus) mass-fails with "Server is temporarily limiting requests (not your usage limit)" / HTTP 429 — most agents dying, a few that finished before the burst surviving — recover by re-running the SAME fan-out on Sonnet and throttled into sequential waves (not one wide burst). Use when: (1) a Workflow returns far fewer results than dispatched and the failures all read "Rate limited" / 429 with "not your usage limit"; (2) you launched 20+ concurrent Opus subagents in one shot; (3) the task is well within Sonnet's range (triage, review, code-tracing, classification). Sonnet is a SEPARATE capacity pool, so it sidesteps the Opus-specific server throttle; the orchestrator/synthesis can stay on Opus.

Diagnose silent semantic duplication after two parallel PRs ship. Use when: (1) one PR (the **mover**) relocates a section/component/block from template X to template Y (X loses it, Y gains it), (2) a sibling PR (the **forker**), authored against pre-mover main, creates / promotes / copies template Z from the OLD version of X (when X still contained the section), (3) both PRs squash-merge without textual conflict because they touch different files, (4) after both deploy, the section appears on BOTH the mover's destination Y AND on the forker's route Z. Symptom is user-visible: "I see this radar / card / nav block in two places, why?" Root cause is structural — git's textual 3-way merge can't see that file Z ⊆ pre-mover-X. Fix: hand-delete the section from one location (usually the forker's), update tests if any asserted on the duplicate render. Prevention: when the mover merges first, rebase the forker BEFORE squash and audit any moved sections; or add a cross-route uniqueness test (`grep -c "<section-id>"` a

Before firing a multi-hour or multi-agent data dispatch (overnight insight runs, parallel subagent fleets, Cloud Run batch jobs, scheduled pipelines), run a fast 5-minute schema probe to verify that every dataset path, table name, and column name referenced in the plan/scope doc actually exists in the warehouse. Use when: (1) you inherited a scope doc authored by a predecessor session and are about to dispatch 2+ long-running agents or jobs based on its table references, (2) the plan doc mentions specific BQ paths like `project.dataset.table` / column names like `enrolled_2025` and you're copying them verbatim into agent prompts or SQL, (3) you're tempted to trust a scope doc that "looks authoritative" (has prior-PR approvals, multi-session review history), (4) dispatch cost is measured in $50+ or wallclock in hours. Catches the failure mode where predecessor docs carry confidently-asserted dataset/column names that are factually wrong — fabricated from memory or stale from a prior schema. Typical catches: da

When dispatching a sub-agent (Agent / Task) to WRITE content that cross- references existing code paths, explicitly grant + expect grep-driven correction of the dispatcher's task-framing claims. Use when: (1) your prompt to a sub-agent asserts facts about what an existing codebase contains ("X is NOT in v6.1", "Y is already implemented at module Z", "feature F handles case G"); (2) the sub-agent will produce a document, analysis, or design that consumers will treat as authoritative; (3) the sub-agent has Read/Grep/Glob access to the code being claimed about. Without an explicit "verify these claims + tag corrections" instruction, a sub-agent will either (a) faithfully reproduce the dispatcher's wrong claim, or (b) silently substitute its own view without flagging the contradiction — both leave the dispatcher with a doc that LOOKS right but is stale. Companion to `factcheck-subagent-needs-complete-sources` (which covers feeding fact-check agents complete sources) — this skill covers the INVERSION: telling writ

Use when a Workflow-tool (or background Agent) subagent doing heavy multi-step compute STALLS mid-stream and loses work. Trigger conditions: (1) a workflow agent fails with "API Error: Response stalled mid-stream. The response above may be incomplete" and returns null; (2) a subagent runs many bq/python/tool calls in one long turn and dies before writing/committing; (3) the agent must emit a LARGE structured return (big arrays/objects) and stalls while producing it; (4) recurring stalls on long single-agent turns. Root insight: agent turns stall on long compute + large returns; DETERMINISTIC computation should run as a direct script the orchestrator executes, with agents reserved for judgment. Covers file-first idempotent durability, design-injection to avoid rediscovery, and compact returns.

Use when a Workflow (or background Agent) synthesis step returns a LARGE markdown deliverable inside a structured-output (schema) field — e.g. a `next_prompt_markdown`, a full report, a generated doc — and you need to persist it to a file. The completion notification TRUNCATES the result and shows the field JSON-escaped (literal `\n`, `\"`), so hand-retranscribing it into a Write call is both lossy (you only saw part of it) and error-prone (escapes leak as literal text). Trigger: you're about to retype an agent's big returned markdown blob from a `<task-notification>` or truncated tool result into a file. Symptoms it prevents: a saved doc containing literal `\n`/`\"`, or silently missing the tail past the truncation cap.

A sequential, stateful multi-agent process (adversarial DEBATE rounds, iterative reflect-then-rebut, staged consensus where step N reads step N-1's peers) silently VANISHES when the task is run under "ultracode" or authored as a Workflow — the run collapses to a parallel find→verify→judge with no reviewer-to-reviewer cross-talk. Use when: (1) you ran "review / red-team / debate X in ultracode mode" and the workflow shows only ~3 stages (review → verify → judge), no debate/reflection/blind- final; (2) you invoked a multi-phase SKILL (e.g. roundtable:agent-review-panel) but the execution was a parallel fan-out with no agents reading each other; (3) a skill whose spec MANDATES sequential phases produced a result with those phases absent and it is NOT context-compression (that's the sister skill multi-agent-skill-silent-phase- compression). Counter-intuitive root cause: the Workflow/ultracode engine is a PARALLEL fan-out engine (parallel()/pipeline(), agents never see each other) with no primitive for sequential

Claude Code Workflow tool gotcha: a pipeline() stage that returns parallel([...]) resolves to a BARE ARRAY, but a sibling stage that returns {dimension, verified: []} resolves to an OBJECT — so a collector written as `per.flatMap(p => Array.isArray(p?.verified) ? p.verified : [])` SILENTLY DROPS every item from the array-shaped stages. Use when: (1) a fan-out review/verify workflow reports "0 confirmed / 0 refuted" or "0 findings" but the agent count / journal shows verify agents actually ran; (2) a loop-until-dry or review workflow looks suspiciously CLEAN; (3) you wrote a pipeline whose stage-2 conditionally returns parallel(...) for some items and an object for others. The "0 findings" is a FALSE all-clear from a result-collection bug, not a real result. Fix: handle BOTH shapes in the collector.

Security trap when authoring/reviewing a GitHub Actions deploy (or any privileged job) triggered by `on: workflow_run` and gated on the triggering run's BRANCH NAME. Use when: (1) a `workflow_run` job gates on `github.event.workflow_run.head_branch == 'main'` (or conclusion == 'success') to decide a privileged deploy / publish / OIDC-cloud action, (2) you are wiring CI-gated auto-deploy-on-merge ("deploy after the CI workflow passes on main"), (3) reviewing a workflow that mints cloud creds (WIF/OIDC, `id-token: write`) off a `workflow_run` event. The trap: `head_branch` is the UNQUALIFIED ref name, and a FORK's default branch is also named `main`. A fork-PR's CI run (event `pull_request`) can complete `success` with `head_branch=='main'`; the upstream `workflow_run` deploy then runs in the PRIVILEGED upstream context and ships the fork's `head_sha` to prod. The "fork CI can't read secrets/OIDC" intuition is a trap — that's the CI job; the deploy is a SEPARATE privileged job. Fix: also gate on the triggering

A dynamic Workflow (the Workflow tool / multi-agent orchestration) parallel()/pipeline() agent that DID all its work returns null and the run reports "StructuredOutput retry cap (5) exceeded — 5 failed calls with no valid output" — NOT because the agent found nothing or was rate-limited, but because its result OBJECT was too large / malformed to serialize in one StructuredOutput call (a big nested array of findings, long SQL/quotes per row), often compounded by a stray closing-tag / truncation that corrupts the JSON. Use when: (1) a workflow fan-out comes back N-of-M and a failure line names the StructuredOutput retry cap (distinct from the rate-limit "empty-args 50-90×" mode); (2) an agent's transcript shows FULL (non-empty) StructuredOutput tool_use inputs that keep failing validation; (3) the agent's own last text says "payload too large / getting truncated" or "stray </parameter> corrupted the JSON". Covers RECOVERING the near-complete work from the agent-*.jsonl transcript's failed StructuredOutput attem

A dynamic Workflow (the Workflow tool / multi-agent orchestration) returns FEWER results than it dispatched, and one or more parallel() agents "failed" — because during a transient server-side rate-limit storm the affected agents called StructuredOutput 50-90× each with EMPTY args (0 fields), failed schema validation every time, then died on a terminal API error. Use when: (1) a workflow fan-out comes back with N-of-M results and logs show "API Error: Server is temporarily limiting requests (not your usage limit) · Rate limited"; (2) agent-*.jsonl shows many StructuredOutput tool_use calls whose input has zero keys; (3) heavy code-tracing agents fail to emit a big required schema while a light agent on the same run succeeded. Covers recovering the COMPLETED agents from journal.jsonl (don't re-run them), re-dispatching the failed ones as FREE-TEXT (no schema), and prevention (concise field values, anti-empty-call directive, free-text for heavy-context agents, a watchdog that greps the empty-SO signature).

Two failure modes that crash an entire dynamic Workflow (the Workflow tool / multi-agent orchestration scripts) and discard all completed agents' work. Use when: (1) a workflow fails with "Error: agent({schema}): subagent completed without calling StructuredOutput (after 2 in-conversation nudges)" — caused by a STANDALONE/terminal `await agent(prompt, {schema})` that is NOT inside parallel()/pipeline(), so the throw propagates and fails the whole run even though the other agents succeeded; (2) a workflow fails immediately with "TypeError: undefined is not an object (evaluating 'P.candidates.map')" or args being a string — caused by the `args` global arriving as a JSON STRING in the script, not a parsed object. Covers guarding standalone schema agents (try/catch, parallel wrapper, or schema-less), defensive JSON.parse of args, and recovering a crashed run cheaply via resumeFromRunId (completed agents return cached).

Fix `pytest exit 4` ("file or directory not found") when running a test command in a git worktree checked out at an OLD commit. Use when: (1) you're doing historical replay (incident replay, mutation testing, git bisect with tests) and the suite errors out in 1-2 seconds with no test execution, (2) the test command works fine at HEAD but fails at pre-fix SHAs, (3) `pytest scripts/overnight/tests/ goal/tests/ --tb=no -q` returns "ERROR: file or directory not found: scripts/overnight/tests/" at an old SHA, (4) you're building tooling that runs the project's canonical test command across multiple historical SHAs. The fix is NOT to add the missing dir back — it didn't exist then. The fix is to filter the test-dir list at each SHA to only those that exist in that commit's tree, then invoke pytest with the filtered list. If none survive, classify the SHA as "unrunnable" rather than failing the whole replay.

Fix for `git checkout <branch>` failing with `fatal: '<branch>' is already used by worktree at '.../autodocs-<name>'` (or a subagent reviewing a PR reports a path like `.../worktrees/autodocs-<topic>/...`). Use when: (1) right after a commit whose hook printed `[post-commit] Python files changed — running doc update in background...`, a later branch switch is blocked; (2) you can't check out the branch you just committed to because "another worktree" holds it; (3) a review/subagent cites a file path under an `autodocs-*` worktree you never created. Root cause: the async post-commit doc-update hook spawns its OWN git worktree on the active branch (git forbids a branch being checked out in two worktrees). Fix: `git worktree remove --force` the autodocs worktree (after confirming it committed nothing), then checkout proceeds. Distinct from the index.lock variant — see worktree-index-corrupt-async-post-commit-hook.

In a repo with an ASYNC/background post-commit hook (one that fires after a commit and creates its OWN follow-up commit — `[auto-docs] …`, a docs/site regen, a changelog/checkbox tick), the hook's commit can land LOCAL-ONLY *after* your `git push` already captured just your work commit, so it is never in the PR and gets ORPHANED + silently lost when the squash-merged branch is deleted. Use when: (1) you pushed a fix, PR'd it, and squash-merged, then a later `git status -sb` shows your feature branch is `[ahead 1]` (or ahead N) of its `origin/<branch>` tracking ref even though "everything merged"; (2) that extra commit is authored by a background hook (message prefix `[auto-docs]`, `chore: regenerate …`, no human author intent) and contains REAL content (a corrected design/doc, a regenerated site asset); (3) you're about to delete the merged branch / move on and would lose it. The cause: the hook runs asynchronously ("running doc update in background…"), so `git push -u origin` completes BEFORE the hook commit

A verification/review/audit subagent YOU dispatched (Workflow agents, Explore, general-purpose, code-reviewer — anything with Bash) runs a file-level `git checkout <path>` / `git restore <path>` / `git stash` to compare your work against HEAD, and silently REVERTS your uncommitted working-tree edit in the shared worktree. The agent then reports that edit as "missing / not persisted / blocker", and sibling agents pile onto the phantom. Use when: (1) a review or verification agent reports a file/entry/line you KNOW you just wrote is "missing", "not in the file", "not persisted", or "only in the diff not the file"; (2) its evidence cites "a subsequent git checkout shows…" or "git diff shows it but the working tree doesn't"; (3) a harness "file was modified, either by the user or by a linter" reminder names a file you edited but didn't touch since; (4) your own passing test suite REQUIRES the thing the agent says is missing (the decisive tell — if tests that need it passed, it WAS there). Prevention: commit (or s

Fix a RECURRING `fatal: Unable to create '.../worktrees/<name>/index.lock': File exists` that comes back after you `rm` it — in a busy/multi-worktree repo where your OWN git commands keep spawning `git maintenance run --auto` (→ `git gc --auto` / `git repack` / `git pack-objects`). Use when: (1) a `git checkout`/`add`/`commit` fails with "Another git process seems to be running … index.lock: File exists", (2) deleting the lock works ONCE then it returns on the next git command, (3) `pgrep -fl 'git (gc|maintenance|repack|pack-objects)'` shows background maintenance running, (4) the repo has many loose objects from heavy fetch/checkout/commit churn (many worktrees, frequent rebases), OR (5) a PARALLEL session's commit was killed mid-flight and left a stale 0-byte lock blocking all sessions in the shared worktree. Includes the cause-agnostic forensic test for whether a lock is SAFE to remove (lsof-unheld + 0-byte + old mtime). NOT for: stale lock from a crashed async POST-COMMIT hook (see `worktree-index-corrupt

In a git-worktree session, your OWN Read/Write/Edit tool calls that use a BASE-repo absolute path (one MISSING the `.claude/worktrees/<name>/` segment) silently operate on the base repo's working tree — a DIFFERENT, often month-stale branch sharing the same `.git`. Use when: (1) a `Read`'s line numbers / function locations don't match a `grep` you ran in the worktree cwd (Bash sees the worktree; Read with a base path sees the base repo); (2) a `Write`/`Edit` "succeeds" but the file never appears in the worktree's `git status -sb` (it landed in the base repo, untracked there); (3) a review/subagent (or a fresh checkout) reports a file you just wrote "doesn't exist"; (4) a file looks surprisingly smaller/older than expected (e.g. bq_queries.py 7228 lines via base path vs 8434 in the worktree). Root cause: harness file tools take absolute paths verbatim and do NOT pin to the worktree; the base repo is a separate checkout, usually parked on another branch. Fix: build EVERY file path under the worktree root (the e

Before starting a large-scale redesign (10+ PRs that rewrite shared files like templates, base layouts, or central views), audit ALL unmerged feature branches for commits that touch the same files. Use when: (1) the user asks for a multi-PR redesign / restructure / migration, (2) the worktree is at the top of main but other long-running branches exist with active work, (3) the redesign will replace files wholesale (template rewrites, route extractions, base.css migrations), (4) the project has a multi-branch flow (one main per client/deployment, e.g. `main` + `release-uk` + `feature/whitelabel-X`). Symptom of having skipped this audit: hours after the redesign ships, cherry-picking the parallel branch's work into main produces a head-on conflict on the rewritten file (often progress.html / report.html / a base template), and the parallel branch's a11y / safety / hotfix commits are stranded — they must be hand-merged into the new markup rather than cleanly cherry-picked. Sister to `pre-merge-client-variant-reg

A dispatched parallel implementation subagent can die mid-stream and leave ZERO durable output while the harness still reports the task "completed". Use when: (1) you fanned out 2+ foreground impl agents (Agent/Task tool) to edit code in one repo, (2) one returns `API Error: Response stalled mid-stream` / an empty or truncated final message, possibly alongside a background "<task> completed (exit code 0)" notification, (3) you're about to integrate or commit their combined work. The "completed" status is a LIE here — the agent may have written nothing (target file untouched, no test created, its self-made todos all still pending). ALWAYS reconcile each agent's CLAIMED work against the actual working tree (`git status`, grep the target file for the expected change) before integrating; the healthy sibling's work is usually intact, so just finish the dead agent's task yourself. Sister to subagent-reports-complete-but-pr-unmerged (work done, integration skipped) and credit-stall-mid-orchestration-revive-collision

Safely co-edit a deliverable WHILE another live session (a second Claude Code session, or a colleague's agent) is actively editing the same file. Use when: (1) the user warns "a parallel session is making active edits on the same file, don't delete each other's work / maybe only write when the other is finished", (2) the deliverable is BUILT from many per-item source files by an assembler (e.g. sections/*.html -> _assemble.py -> one big HTML; docs, slides, reports), (3) you must make edits without clobbering — or being clobbered by — the other session's concurrent work. Covers: mapping hot/cool items via source-file mtime, editing only disjoint sources, why an idempotent rebuild is NON-destructive (so your edits survive the other session's rebuild), the false-negative grep gotcha when verifying content landed in assembled HTML, how to CHECK COVERAGE ("is card X present / missing?") against the sources rather than the build, and the end-of-session HANDOFF/COMMIT discipline on the shared branch (commit only you

A parallel Claude/work session shipped a DIFFERENT (often better) fix to the SAME live-prod artifact for the SAME issue while you were mid-build — so your fully-implemented, validated, reviewed fix is now REDUNDANT and must NOT be deployed over theirs. Use when: (1) you picked up a "next session ships the scoped fix X" handoff/prompt and invested a full implementation, (2) the target is a SHARED prod artifact (Dataform .sqlx, a serving feature table, a deploy config, a model pointer) editable by multiple sessions, (3) the related issue is "still OPEN" but a sibling issue mysteriously CLOSED, (4) the user/another session says "stand down — already fixed live", (5) you're about to deploy and haven't re-checked the live state since you started. Core trap: a handoff/issue reflects the world WHEN IT WAS WRITTEN; "issue open" ≠ "unfixed"; a parallel session can ship between your build and your deploy. Verify the LIVE DEPLOYED state of the target artifact at task START and again IMMEDIATELY before any deploy — a 1-q

Large parallel subagent fan-outs (dispatching many Agent/Task subagents at once to each extract/transform a chunk and WRITE a file) hit a server-side rate limit, AND the agent RETURN STATUS lies about what got produced. Use when: (1) dispatching more than ~5-6 concurrent subagents and seeing "Server is temporarily limiting requests (not your usage limit) · Rate limited"; (2) deciding which "failed" subagents to re-run after a throttled batch; (3) a graphify-style chunked extraction (28 chunks → 28 subagents) where some agents error on their final return. Two facts: concurrency >~5 trips server-side throttling (distinct from your usage limit), and a throttled/errored agent usually ALREADY WROTE its output file before the error hit on its final summary — so check disk for the expected files, not the agent return, when deciding retries. Fix: batch at ≤4-5 concurrent; re-dispatch only chunks whose files are actually missing/empty. v1.1.0 adds the USER-ACCOUNT session-limit variant ("You've hit your session limit

Trap: opening/merging a PR from a branch that was created a while ago can SILENTLY DELETE (revert) files that landed on main AFTER your branch point — with NO merge conflict to warn you. Use when: (1) about to `gh pr create` or squash-merge from a long-lived / earlier-branched branch; (2) `git diff origin/main..HEAD --stat` shows DELETIONS of files you never touched; (3) a PR diff is unexpectedly large or removes another session's/teammate's work; (4) the repo has many parallel branches + a squash-merge flow (each squash makes older branches progressively staler). The fix is to merge origin/main INTO the branch first, then re-verify the diff shows only your additions. Distinct from merge-CONFLICT skills — this is the no-conflict, clean-merge silent-regression case. See also: pr-conflict-from-mid-flight-merges, large-redesign-parallel-branch-collision-audit, merge-conflict-generated-files.

After making a change you run the test suite and it shows failures — especially in files/areas your diff never touched, or a count that "feels unrelated." Before you either panic-debug them OR wave them off as "probably pre-existing," PROVE it: run the exact failing tests against a clean checkout of origin/main (a throwaway `git worktree`). Identical failures = pre-existing (ship + note them); different = your change caused it. Use when: (1) a broad/full test run after your edit reports failures and you must decide "mine or pre-existing?"; (2) you're tempted to attribute failures to your change without evidence, or to dismiss them without evidence; (3) you can't `git checkout main` because you're in a worktree where main is checked out elsewhere, or you have uncommitted work.

When you run pytest (or any `python -c "import <pkg>"`) from a git WORKTREE but the venv has an editable install (`pip install -e .`) made from the PRIMARY checkout, `import <pkg>` silently resolves to the PRIMARY checkout's source, NOT the worktree code you think you're testing. Use when: (1) you edited code in a worktree, ran the suite, it passed/failed — but you're unsure it exercised the worktree's edits, (2) tests pass on changes that "shouldn't" pass (or fail on changes you reverted), (3) a `src/`-layout project with absolute `import src.*` / `import <pkg>.*` imports, one shared `.venv`, and multiple worktrees. Fix: prepend the worktree root to `PYTHONPATH` and VERIFY resolution with `print(<pkg>.__file__)`.

Use to recover the work, plan, and failure-cause of a PRIOR Claude Code session that died / crashed / was killed mid-task (e.g. a hung tool call, an API 529 storm, the user force-quit), so the current session can continue it without redoing work or repeating the fatal mistake. Trigger when: (1) the user says something like "we had a session yesterday on worktree X that got killed — the transcript might help", "resume the crashed session", "continue what the last run was doing"; (2) you find an isolated git worktree with uncommitted WIP + a leftover plan file (tasks/session_N_todo.md) but no corresponding merged PRs; (3) a feature branch has uncommitted changes and you need to know the intent behind them. Covers: locating the dead session's worktree + leftover artifacts, finding and identifying its transcript JSONL, and mining it for the plan, the cause of death (to avoid repeating it), and any USER DECISIONS made in that session (so you don't re-ask). Also covers the trap that the dead session's "verified" /

Structure a next-session handoff so a multi-slice redesign whose slices ALL edit one hot file (a template, a central view, a shared CSS block) can still be parallelized — even though the disjoint-files test says "don't split." Use when: (1) you're writing parallel next-session prompts (session-handoff Phase 3) and the remaining work is N slices that each touch the same file (e.g. report.html / analysis.py), so the standard "split only if file sets are disjoint" rule would force everything serial; (2) one slice is a longer-lead, schema/storage/back-compat -risky or probe-gated BACKEND change that a UI slice depends on; (3) you want to give the next session a concrete collision-mitigation plan, not just "these conflict." Encodes the parallel-author / serial-integrate split, the backend-first gating-spike ordering, ascending-risk merge order, narrow-collision marking, and the partials-extraction prep-PR alternative that converts serial integration into true parallelism.

Use when DESIGNING a shared "see everyone's active/in-flight/recent items" index — a dashboard sidebar, an activity feed, a "running now" list, a per-team/per-workspace/per-user recent-items list — that CONCURRENT producers add to AND a reader prunes. If you back it with ONE shared mutable container (a JSON list/array in a GCS/S3 blob, a DB array column, a shared session-cookie list, a single file) that is read-modify-written, you get a read-modify-write RACE that silently and PERMANENTLY drops entries: the reader reads the list, a producer appends X, the reader writes back its pruned copy computed before X existed → X is gone forever and the feature's whole promise ("see each other's items") is silently violated for that item. Trigger symptoms: an item a colleague just created never appears in the shared list; "self-correcting" was assumed but the add fires only once so it never re-appears; review flags a concurrency race on a shared index. Fix: ONE marker blob/row PER ITEM (`<prefix>/<item_id>`), so create

Diagnoses + recovers the "every shell command now fails `fatal: Unable to read current working directory: Operation not permitted`" trap, which appears AFTER a git worktree you were running commands in gets removed/pruned mid-session (you merged + deleted its branch, ran `git worktree remove`, or the Claude Code harness auto-cleaned a merged/unchanged worktree). Use when: (1) git AND python both error `Operation not permitted` / `PermissionError: [Errno 1] Operation not permitted` on startup; (2) `cd /valid/abs/path && pwd` PRINTS the valid path but the very next `git`/`python` in the SAME command still fails (pwd lies); (3) the harness prints "Shell cwd was reset to <some-.claude/worktrees/...>" after each Bash call; (4) `git -C /repo`, recreating the dir with `mkdir`, `python3 -c "import os; os.chdir(...)"`, and even `dangerouslyDisableSandbox` all still fail. Core fact: the shell's kernel cwd is a DELETED directory the OS won't resolve, and zsh `cd` updates `$PWD` without a real `chdir()`, so no subprocess

Read-only subagents (Explore / code-explorer / general-purpose dispatched to AUDIT or READ code, not write) silently return line numbers and "what exists" claims from the WRONG git worktree in a repo with many worktrees — confidently-wrong stale data, no error. Use when: (1) you dispatched 1+ read/audit subagents and their cited file:line numbers, function locations, or "X is/isn't present" claims DON'T match what you read directly in your pinned worktree; (2) `git worktree list` shows 2+ paths (especially a `.claude/worktrees/` fan-out); (3) a subagent reports an issue is "not implemented" / "missing" when you can see it on fresh main; (4) two parallel audit subagents disagree with each other or with origin/main. Fix: every read-subagent prompt must pin the ABSOLUTE worktree path AND require the agent to run `git -C <path> rev-parse HEAD` and confirm the expected SHA before reading. Distinct from subagent-bash-cd-wrong-worktree (write/commit to wrong branch), worktree-outer-ls-mistaken-for-main-state (`ls`

Stop a false "my PR is reverting/touching dozens of upstream files" alarm when `git diff main...<branch>` reports far more files than your commit changed, in a multi-worktree repo. Use when: (1) you're in a worktree at `<repo>/.claude/worktrees/<X>/` (or any `git worktree`), (2) `git diff main...HEAD` (3-dot) or `--stat` shows tens/hundreds of files + thousands of lines but your actual commit (`git show --stat HEAD`) touched only a handful, (3) you're about to panic about the `stale-base-pr-silently-reverts-upstream-content` trap or block your own merge. Root cause: the LOCAL `main` ref is stale — it's parked many commits behind `origin/main` (often checked out in the PRIMARY worktree, which nobody pulled), so the merge-base of (local main, your branch) is ancient and the 3-dot diff includes every file that landed on origin/main since. The REAL PR diff is against `origin/main`. Verify with `git diff origin/main...HEAD --stat` (after `git fetch`) and `gh pr view <N> --json files`. Sibling of git-diff-2dot-vs-3

In a git worktree session, a Write/Edit whose absolute path points at the MAIN-REPO ROOT (the parent checkout) silently creates the file in that parent checkout's working tree — on whatever branch it has checked out — NOT in your worktree on your feature branch. The file then doesn't appear in `git status` on your branch and `ls`/Read inside the worktree can't find it. Use when: (1) the environment's "Primary working directory" is a worktree at `<repo>/.claude/worktrees/<name>/`, (2) you're about to Write or Edit a file by ABSOLUTE path (handoff doc, generated artifact, new source file), (3) you habitually type the repo's canonical root path (`/.../<repo>/docs/...`) instead of the worktree path (`/.../<repo>/.claude/worktrees/<name>/docs/...`), (4) a later step reports "file does not exist" / a commit is missing files you "just wrote" / `git status` is unexpectedly clean. Trap: the main repo root is a real, writable checkout; writing there succeeds silently and pollutes the parent's working tree (often on a s

When a code-review subagent (voltagent-qa-sec, opus-tier reviewer, code-reviewer, etc.) reports a HIGH or BLOCKING severity finding, verify any SPECIFIC EVIDENCE the reviewer cites (line numbers, call counts, exact function/symbol names, file paths beyond the obvious diff) BEFORE treating the severity as actionable. Use when: (1) a single-run code-review subagent returns a BLOCKING/HIGH finding justified by concrete numeric evidence like "there are EXACTLY 4 calls at lines 3174, 3230, 3251" or "this affects N files across the repo"; (2) the principle of the finding sounds plausible but you didn't immediately recall the specific symbols cited; (3) you're under time pressure to merge and the BLOCKING tag is the only thing holding you back; (4) the reviewer used opus tier and the confident, specific framing is reading as authoritative; (5) you notice the reviewer's grep would have been trivial (`grep -c "flash.*warning" foo.py`) but the report itself shows no evidence of grep output, only the assertion. Symptom: