wan-huiyan
UserCoordination toolkit for parallel Claude Code sessions sharing one repo — issue-pickup claim protocol, worktree isolation pitfalls, parallel-PR conflict recovery, subagent integrity, and squash/merge mechanics. 61 skills, Pattern B multi-skill plugin.
Categories
Indexed Skills (68)
claude-code-projects-jsonl-worktree-fanout
Search prior-session JSONL transcripts across worktree-namespaced project directories under `~/.claude/projects/`. Use when: (1) the user asks "find a previous session about X" or "remind me when we discussed Y" for a project that uses git worktrees, (2) you grep the canonical `~/.claude/projects/<project-dir>/*.jsonl` and the matching session isn't there, (3) you need to enumerate every conversation that touched a project regardless of which worktree it ran from. Claude Code stores each git worktree's session JSONLs under a separately-namespaced project directory (`<project-name>--claude-worktrees-<worktree-name>/`), not under the canonical `<project-name>/` directory. Searching only the canonical dir silently misses sessions run from worktrees — even though the user experienced them as "in the same project". Sister to the `git-worktree` skill family at the Claude-Code-state layer.
code-reviewer-subagent-no-bash-blocked-on-pr-diff
Code-review subagents are frequently provisioned WITHOUT a Bash tool, so they cannot run `gh pr diff`, `git diff`, or `git checkout` — and when you prompt them to "review PR #N, fetch the diff with gh pr diff" they return a BLOCKED report (no review performed), not findings. Use when: (1) dispatching feature-dev:code-reviewer / voltagent-* / Explore agents to review GitHub PRs or branches; (2) a review agent returns "I have no shell/gh/git tool" or "the PR sources are not in the working tree" or reviews `main` (which predates the PR) instead of the PR; (3) one reviewer in a parallel panel comes back BLOCKED while siblings succeeded. Fix: pre-generate per-base diffs to files + point the agent at materialized worktree paths, don't tell it to run gh/git.
concurrent-session-checkout-clobbers-shared-worktree
A second Claude Code session (or agent/person) sharing the same working directory runs `git checkout`/`git switch`, flipping the branch for the whole working tree underneath your session and clobbering your uncommitted work. Use when: (1) a file you just edited has silently reverted — often with a "file was modified, either by the user or by a linter" system reminder, (2) `git branch --show-current` shows a branch you didn't switch to, (3) `git reflog` shows a `checkout: moving from X to Y` you never ran, (4) unfamiliar files/changes appear in `git status`. Covers detecting the collision and recovering via an isolated git worktree.
credit-stall-mid-orchestration-revive-collision
Recover gracefully when an Anthropic credit/billing failure stalls multiple in-flight parallel subagents mid-orchestration, then later resolves. Use when: (1) you've dispatched 2+ parallel subagents (Task tool with `run_in_background: true`) and a credit/billing issue, MCP outage, or other transient harness failure has frozen them, (2) the user reports the issue is now resolved and asks you to continue, (3) you're about to relaunch "resume" agents to pick up where stalled originals left off. Defends against the silent-revive trap: when API access is restored, ORIGINAL stalled subagents can auto-resume from where they froze and continue working IN PARALLEL with any "resume" agents you dispatch — leading to two agents racing on the same branch / PR / files, duplicate review comments, or one agent overwriting the other's work. Captures the diagnostic recipe (JSONL mtime + worktree-state inspection, NOT just agent status) and the safe resume pattern (state-aware briefs that detect current state and pivot to value
cross-worktree-spec-handoff-via-checkout-paths
Pass design specs, handoff prompts, or any other shared artefact between two parallel Claude Code sessions that are working in different git worktrees on different branches — without merging the producing branch to main first. Use when: (1) session A produced design docs / a handoff prompt / a mockup file on branch X, (2) session B (different cwd / different worktree, on branch Y branched from main) reports "the file doesn't exist" or "I can't find the design spec you mentioned", (3) you want B unblocked NOW without a PR review cycle, (4) both worktrees are local checkouts of the same repo (share `.git`). The unblock: `git checkout <producing-branch> -- <paths>` from inside B's worktree pulls the files in as staged additions, no merge needed. Also covers the related gitignore-exception trick when the artefact files are blanket-ignored (e.g., `*.html` in a repo that produces HTML deliverables but also keeps design mockups under `docs/`). v1.1.0 (2026-05-26) adds the diagnostic-search variant: when the user say
deploy-from-stale-worktree-silent-rollback
Diagnose "I deployed a new Cloud Run / Docker image but a bunch of recently merged fixes regressed in production." Use when: (1) the deploy script does `gcloud builds submit ... "${SCRIPT_DIR}"` or `docker build <dir>` (build context = local filesystem, NOT a git ref), (2) the user has many git worktrees / multiple checkouts of the same repo, (3) the user reports "redeployed but the fix from PR #X isn't live" or "lots of fixes regressed after my deploy", (4) the deployed revision created at time T was authored by the user themselves (not CI). Root cause: deploy was run from a worktree whose HEAD predates the merged PRs; the build packaged stale local files, silently rolling back N commits worth of merged fixes. Provides the authoritative diagnostic (download Cloud Build source tarball + byte-diff against git history to identify the source commit) and the fix (rebuild from current main checkout, or instant traffic-switch rollback to the last known-good revision). v1.1 adds a pre-deploy preflight (5 lines from
docs-branch-off-feature-branch-smuggles-code
Catch the bug class where a "docs follow-up" PR silently ships the parent feature's code under a `docs(sN):` title because the docs branch was created from the current working branch (a feature branch), not from `origin/main`. Use when: (1) you just opened a PR titled `docs(...)` or `chore(...)` after wrapping up a feature session, (2) `gh pr diff <N> --name-only` shows files OUTSIDE `docs/` (source code, Dockerfile, tests, generated artefacts), (3) `git log origin/main..HEAD` shows TWO+ commits where you only authored one or two docs commits, (4) the surprise commit author/message is from your own earlier feature work on the parent branch, (5) the PR body claims "docs-only" but the actual diff carries code. Trigger surface: end-of-session handoff workflows that `git checkout -b docs/sN-handoff` from inside a feature worktree that's still on `feat/sN-feature`. Squash-merging such a PR auto-promotes the feature code under a "docs" title — bypassing the planned merge-and-deploy gate for the feature PR, and sile
factcheck-subagent-needs-complete-sources
When dispatching a subagent to fact-check or verify a document/report/claims against source material, hand it COMPLETE primary sources — never your own abridged summary or partial dump. Use when: (1) you are about to launch an Agent/Task subagent to "fact-check", "verify", "independently check", "stress-test", or "review the claims in" a document against sources; (2) you are assembling the source bundle or writing the prompt for that agent; (3) a verification subagent returns a verdict like "claim X is unsupported / appears in no source / looks fabricated" — before accepting it, check whether the gap is in a source YOU abridged. An agent fed a partial source reports confident FALSE-POSITIVE "unsupported" verdicts on exactly the regions you trimmed out.
flask-debug-cross-worktree-edit-stale
Diagnose "I edited the template / view / CSS but Flask debug-mode keeps serving the old version" when running a local dev server (Flask, Django runserver, Rails server, etc.) from one git worktree while editing files in a sibling worktree of the same repo. Use when: (1) you have multiple `git worktree` checkouts of the same repo (typical with `.claude/worktrees/<feature>` directories), (2) a dev server is running in worktree A serving its working tree, (3) you're making edits in worktree B because branch X is checked out at A and you can't `git checkout X` in B too, (4) `curl http://127.0.0.1:PORT/page` returns byte-identical responses despite your edits, (5) you're tempted to blame Jinja bytecode cache, Flask `@_ttl_cache`, or browser caching. Root cause is filesystem-level: each git worktree has its own independent working tree on disk; Flask is reading worktree A's files, not worktree B's. Cache-busting tricks (`touch app.py`, browser hard refresh, restart Flask) won't help. Sister skill to `flask-debug-tt
gh-pr-create-orchestration-cwd-wrong-head
Diagnose and prevent `gh pr create` opening a PR against the WRONG head branch when invoked from a parallel-orchestration setup with multiple worktrees. Use when: (1) you've dispatched subagents to work in sub-worktrees but you're finalizing PRs from a separate orchestration worktree, (2) `gh pr create` succeeds but `gh pr view --json headRefName` shows your orchestration worktree's branch (e.g. `docs/sNNN-handoff`) instead of the feature branch the subagent committed to (e.g. `fix/issue-X`), (3) two PRs exist for the same logical change because a revived subagent opened a second one on the correct branch. Trigger: PR title is correct (heredoc body matches your intent) but the PR's `headRefName` doesn't match the feature worktree's branch — your CWD when invoking `gh` overrode the head selection.
gh-pr-merge-unstable-state-needs-auto-and-watch-branch-deletes
Diagnose and recover from two adjacent `gh pr merge` failure modes that masquerade as merge conflicts. Use when: (1) `gh pr merge --squash` (or `--merge`) errors with "To have the pull request merged after all the requirements have been met, add the `--auto` flag" AND "Run the following to resolve the merge conflicts locally" even though you just pushed a clean resolution; (2) `gh pr view <N> --json mergeable,mergeStateStatus` returns `MERGEABLE` + `UNSTABLE` rather than `MERGEABLE` + `CLEAN`; (3) you delete the remote branch (`git push origin --delete <branch>`) immediately after `gh pr merge` returns a conflict warning thinking the merge succeeded — and discover the PR has flipped to `CLOSED` rather than `MERGED`. The actual root cause for (1)/(2) is almost always pending CI / branch-protection checks, NOT real merge conflicts; the fix is `--auto` flag so `gh` queues the merge for when checks pass. For (3) — recovery requires restoring the remote branch (`git push -u origin <branch>` from your local copy) a
gh-pr-merge-worktree-checkout-trap
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
gh-squash-merge-closes-only-one-issue
GitHub auto-close on squash-merge only catches ONE issue per PR even when the PR title/body says "Closes #447, #448, #449, #450". The first issue closes; the rest stay OPEN. Use when: (1) you opened a PR with a title or body listing multiple "Closes #X, #Y, #Z" references, (2) the PR squash-merged successfully (`gh pr view N --json state` = MERGED), (3) `gh issue list --state open` shows some of the referenced issues are still OPEN. Root cause: GitHub's auto-close keyword parser binds one keyword to one issue; "Closes #447, #448" is interpreted as "Closes #447" plus an inline reference to #448. Fix: either (a) write one keyword per issue ("Closes #447. Closes #448. Closes #449.") in the PR body BEFORE merging, or (b) post-merge, run `gh issue close $N --comment "Closed by PR #M (squash-merge auto-close caught only one)"` for each leftover. Different from `pr-followup-commit-stranded-after-squash` (which covers stranded COMMITS, not stranded ISSUES). Saves a "why are my issues still open after merging the fix?
gha-pr-merge-ref-shows-upstream-changes
Diagnose "my CI failed on a file I didn't change — the test passes locally but CI insists there's a duplicate / conflict / lint violation that isn't in my branch." Caused by GitHub Actions checking out `refs/pull/N/merge` (the auto-computed merge of PR head + base) on `pull_request` events. Use when: (1) CI fails on a `git`/lint/whole-tree check (duplicate IDs, schema drift, file-content audit) that PASSES on the same SHA locally, (2) you're working in a dense parallel-PR window where main is moving faster than your CI runs, (3) `gh run view N --json headSha` matches your latest force-push but `git fetch origin main && git diff origin/main..HEAD` shows main is ahead by N commits, (4) the failure references symbols / IDs / values that are present in MAIN but absent from your branch. Root cause: GitHub re-computes the merge ref every time the base moves, so CI on `pull_request` sees `main-at-CI-start + your-branch`, NOT just `your-branch`. Sister concept to `gha-billing-failure-fast-fail-pattern` (different GHA
git-add-u-after-async-post-commit-hook
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
git-amend-hits-async-post-commit-hook-commit
Use when a `git commit --amend` silently rewrites the WRONG commit in a repo that has an async/background post-commit hook. Trigger: after a normal commit, `git log` shows an unexpected extra commit on top that a background hook created (`[auto-docs] ...`, a docs/site regen, a changelog/checkbox tick) — and a later `--amend` folds your change into THAT hook commit instead of your feature commit. The amend reports success; no error. Also use proactively before instructing subagents to `--amend` in any repo with a background post-commit hook. Sibling of git-add-u-after-async-post-commit-hook, git-rebase-stalls-async-post-commit-hook, worktree-index-corrupt-async-post-commit-hook.
git-diff-2dot-vs-3dot-merge-safety
Avoid false-positive "this PR will delete files on main" alarms when reviewing a PR that was branched off an older commit. Use when: (1) `git diff origin/main..pr-branch` shows files being deleted that you DON'T want to lose, but (2) GitHub reports `mergeable: MERGEABLE / mergeStateStatus: CLEAN`, (3) you're about to demand a rebase or block the merge to "preserve" those files. The 2-dot diff is misleading — it shows everything different between two trees, including files added on `main` AFTER the branch point that the branch never saw. The 3-dot diff (`origin/main...pr-branch --diff-filter=D`) respects the merge-base and shows only what the branch actually deleted. Also covers the empty-cherry-pick signal that a "divergent" local commit's content is already on main under a different hash.
git-pull-after-squash-merge
Fix "untracked working tree files would be overwritten by merge" errors when pulling after a squash merge. Use when: (1) `git pull` fails listing files that should already be on main, (2) you just squash-merged a PR and can't pull on another branch, (3) files from a merged branch appear as "untracked" blocking checkout or pull. The root cause is that squash merge creates new commits — the original branch files exist on main but your local copy has them as untracked leftovers from the old branch. ALSO triggers on `git checkout main` from a long-stale branch when untracked local files shadow files that became tracked on main since the branch diverged. **Before removing the blocking files, diff each against `git show origin/main:<path>` — content, not just existence — because a differing untracked copy holds unique local content that blind `rm` / `git clean -fd` / `reset --hard` will silently destroy.**
git-rebase-stalls-async-post-commit-hook
Fix `git rebase origin/main` (or any multi-commit rebase) silently stalling mid-replay with `hint: pick <SHA> ... It has been rescheduled; To edit the command before continuing, please edit the todo list first` output, leaving a stuck `.git/worktrees/<name>/rebase-merge/` directory that `git rebase --abort` does NOT clear. Use when: (1) you ran `git rebase origin/main` on a branch with N commits to replay, (2) the rebase output shows partial progress (`Rebasing (1/N)... Rebasing (2/N)...`) then hangs or returns with `It has been rescheduled` hint for a specific commit SHA, (3) `git status` reports `## HEAD (no branch)` (detached), (4) `git rebase --abort` returns silently but the next `git rebase` reports `fatal: It seems that there is already a rebase-merge directory`, (5) the project has an async `post-commit` hook that spawns a long-running subprocess in background (the canonical signature is `[post-commit] ... running ... in background` printed during the rebase output, OR a `.git/hooks/post-commit` that
git-stash-pop-pulls-unrelated-stash
Diagnose and avoid `git stash pop` pulling in a stale stash from a different branch when the preceding `git stash` was a no-op. Use when: (1) `git stash` reports "No local changes to save" but you `git stash pop` anyway as a reflex; (2) `git stash pop` surfaces files you don't recognize, often with "both modified" merge conflicts in files unrelated to your current work; (3) `git status` after a stash pop shows changes in files from other features / other branches; (4) `git stash list` reveals stash entries from sibling worktrees or older branches. The stash stack is GLOBAL across branches and worktrees — it's LIFO and branch-agnostic. Pairing `git stash` / `git stash pop` defensively (e.g., before `git checkout -- file`) only works when the initial stash actually saved something; otherwise the pop reaches deeper into history. Save under user-wide skills.
handoff-prompt-stale-user-hint-newer-state
Gate execution of a structured runbook/handoff/plan prompt behind an AskUserQuestion when the user explicitly hints that newer state (issues filed, PRs merged, probes shipped) has landed since the prompt was authored. Use when: (1) the user invokes "execute docs/handoffs/session_NNN_*.md" or "run this plan" or "implement this ADR" AND adds an inline aside like "but please be aware of #642, #662, #663" / "watch out for PR #N" / "FYI #issue landed since this was written"; (2) before executing, a scan reveals issues/PRs in the user's hint list were filed/merged AFTER the prompt's authoring timestamp; (3) the newer artifacts could materially change what the prompt should do (e.g., a P1 issue surfacing that the prompt's design decision needs revisiting, a probe correction flipping a verdict, a sibling PR's merge claiming an ID the prompt reserved). Default behavior to avoid: execute the prompt verbatim and paper over the divergence in a post-merge comment. Correct behavior: pause, fetch current state of each hinte
main-bash-cwd-persists-nested-worktree
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,
merge-conflict-generated-files
Resolve merge/rebase conflicts where the conflicting files are DERIVED OUTPUTS from a source-of-truth generator script. Use when: (1) multiple files conflict but they are all generated from a single source (e.g., site/*.html from a tracker Python script, dist/*.js from a bundler config, openapi.json from OpenAPI spec, Sphinx/Docusaurus HTML from .rst/.md), (2) hand-merging the generated files line-by-line would produce wrong/stale output because the files encode computed aggregates, (3) two parallel branches both modified the generator source AND committed regenerated outputs. Core insight: generated outputs are fully derived — resolve their source, re-run the generator, stage the fresh output. Don't waste time resolving HTML/JSON conflicts in files that will be overwritten by the generator anyway.
merged-pr-not-deployed-gate-label-missing
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
multi-agent-skill-silent-phase-compression
Diagnose and fix silent compression of MANDATORY phases in multi-agent orchestrator skills (review panels, debate workflows, multi-reviewer pipelines). Use when: (1) a skill spec lists 10+ phases including parallel reviewer dispatch but the actual run "compresses Phase 4 (reflection) / Phase 5 (debate) / Phase 7 (blind finals) into the judge's integration", (2) a multi-reviewer panel produces a report that looks identical to a full run but actually skipped reflection/debate/blind-final rounds, (3) a re-run of the missing phases surfaces net-new findings (especially new P0/P1 items the compressed run missed), (4) the orchestrator's chat history shows reviewer outputs returned verbatim as Agent tool results (not via Write→path pattern), (5) you're authoring a new multi-agent skill and want to prevent this failure mode. Counter-intuitive root cause: subagent dispatch IS parallel and each subagent has its OWN context window, but their full outputs land verbatim in the ORCHESTRATOR's chat history, accumulating to
multi-phase-skill-disk-reading-strategy
Fix silent subagent failures in late phases of multi-phase Claude Code skills. Use when: (1) a skill has 10+ phases and the last phase's subagent silently fails to launch, (2) Phase N produces output that Phase N+1 needs but the orchestrator's context is near capacity, (3) the orchestrator injects large data payloads (500+ lines) into subagent prompts and the subagent produces degraded or empty output, (4) a skill's final output step works in short reviews but fails in long ones. The fix: have late-pipeline subagents read already-written files from disk instead of receiving data via orchestrator context injection.
multi-worktree-file-url-stale-content
When a user opens a `file://` URL bookmark to a file in a repo with multiple git worktrees, the browser shows whatever the targeted worktree's branch contains — NOT main, NOT the latest merge. Use when: (1) user reports "I don't see my change" or "the fix isn't there" right after a PR was merged, (2) you've confirmed via `git show origin/main:<path>` that main has the fix but the user-visible file:// view doesn't, (3) the file path mentioned by the user contains `.claude/worktrees/<name>/`, `worktrees/`, or any other multi-checkout root, (4) `git worktree list` shows 2+ paths and the bookmarked one is on a feature branch. Distinguishes from: `worktree-outer-ls-mistaken-for-main-state` (about `ls` outside any worktree), `flask-debug-cross-worktree-edit-stale` (about Flask debug reload reading wrong worktree). This skill specifically covers the user-bookmarks-a-file-URL variant where neither `ls` nor a server reload is in play — the browser opens whatever exists on disk in that worktree at that path.
parallel-pr-scope-overlap-tiebreaker-delta-check
Before applying a handoff prompt's tiebreaker default ("merge the first-mover", "the clean-against-main one", "the one with reviewer APPROVE") to pick a winner between two parallel PRs that implemented the SAME scope, run `gh pr diff` on BOTH and audit for substantive deltas. Use when: (1) a session prompt or handoff doc surfaces a parallel-PR collision and recommends a tiebreaker, (2) two PRs targeting the same issue / same fix area are open simultaneously authored by different sessions, (3) the prompt's recommended winner is the older / cleaner / single-reviewer one — exactly the conditions under which "first-mover" rules can ship the inferior implementation, (4) you're tempted to skip the delta-check because the diffs "are probably substantively equivalent" or the prompt already analyzed them. Symptom of having skipped this check: weeks later a follow-up PR re-implements a correctness improvement that was already in the loser's diff. Sister to `synthetic-id-collision-rebase` (same-id register collisions; m
parallel-pr-template-fork-duplicates-moved-section
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
pr-conflict-from-mid-flight-merges
Diagnose and resolve a GitHub PR that flips to CONFLICTING / DIRTY (or "This branch has conflicts that must be resolved") because OTHER PRs landed on `main` while this PR was open. Use when: (1) a PR was clean when opened but is now CONFLICTING after hours/days, (2) `gh pr view N --json mergeStateStatus` returns DIRTY / mergeable CONFLICTING, (3) the feature branch has accumulated commits whose content is already on main via a different PR (squash-merged with a different SHA), (4) you need to figure out WHICH PRs landed and which of YOUR commits are now redundant before rebasing. Prescribes a 6-step recipe: gh status → list landed commits → detect redundant cherry-picks → reset to origin tip → rebase → reconcile.
pr-followup-commit-stranded-after-squash
Diagnose and recover follow-up commits that were pushed to an open PR's branch but never reached `main` because the user squash-merged the PR between pushes. Use when: (1) you pushed commit 1, opened a PR, then iteratively pushed commits 2, 3, ... in response to user feedback, (2) you go to merge / verify and find the PR is already MERGED, (3) the squash commit on main has insertion counts / file content matching ONLY commit 1 — your follow-up commits are stranded on the now-closed branch. Root cause: GitHub squash captures the commits that were on the branch *at merge time*, not what you push afterward. The mental model "squash collapses everything that ever lived on the branch" is wrong. Fix: branch off current main, cherry-pick the stranded commits, open a follow-up PR.
pr-hijack-via-stale-worktree-branch-ref
Diagnose and recover from accidentally overwriting another session's open PR when `git push -u origin <branch>` in a long-lived worktree silently replaces the remote branch ref. Use when ANY of the following appears: (1) you ran `git checkout -b <branch> origin/main` and `git push -u` and git reported `* [new branch]` even though the branch already existed upstream, (2) `gh pr create` then errors with `a pull request for branch "<branch>" into branch "main" already exists` pointing to a PR you didn't author, (3) `gh pr view N --json commits` on that PR shows YOUR commit instead of the one the title/body describes, (4) you discover your worktree's session-start git status banner was stale (showed branch X but actual branch was Y). Pattern surfaces when a prior session in the SAME worktree opened a PR on a generically-named feature branch, then reset the worktree's local refs without cleaning the remote. Recovery requires `git push --force-with-lease` — a destructive op requiring explicit user authorization. Si
pr-plan-bucket-triage-before-sizing
Run a 1-day "Phase 0 bucket triage" with subagent-per-bucket dispatch BEFORE writing detailed PR plans, when scoping work on a codebase that (a) someone else is actively shipping on, (b) you haven't audited recently, or (c) you're relying on assumptions about route existence, UI wiring, storage shape, or defect scope. Use when: (1) you're about to invoke `superpowers:writing-plans` for 3+ PRs and your LOC estimates contain question marks or "TBD by triage" markers; (2) brainstorming output references "the colleague's module is a stub" / "the UI doesn't exist yet" / "the report download is missing" — assumptions you haven't grep'd; (3) the design says "PR-N depends on triage findings"; (4) you catch yourself writing "size: 150-600 LOC" ranges; (5) the codebase has a roadmap doc claiming features are "Done" but with caveats that haven't been re-verified. The skill defines the bucket-triage pattern (6 typical buckets: routes/templates, existing surface, module integration, break diagnosis, pattern audit, storage
prep-pr-close-keyword-auto-closes-issue
Diagnose and prevent the trap where a scaffolding/prep/planning/handoff PR (one that ships a paste-ready prompt, an ADR, an implementation plan, or any docs-only artefact describing FUTURE work) contains a close-keyword like `closes #N` / `fixes #N` / `resolves #N` in its TITLE or BODY, which GitHub auto-applies at merge time — closing issue #N BEFORE the actual implementation work has been done. Use when: (1) `gh issue view <N>` reports the issue CLOSED but you know the work hasn't run, (2) you're about to open a PR shipping a "next-session prompt" / "implementation plan" / "ADR proposal" / "scaffolding" and the title or body references an issue, (3) `gh api repos/<O>/<R>/issues/<N>/timeline` shows the closing commit is a docs-only PR (only `docs/handoffs/`, `docs/plans/`, `docs/decisions/`, or `docs/specs/` paths changed), (4) a fresh session is asked to execute an issue that already shows as CLOSED. Different from `gh-squash-merge-closes-only-one-issue` (THERE: one of many issues closed on merge; HERE: an
safe-bulk-worktree-branch-cleanup
Safely bulk-clean accumulated git worktrees and branches without losing progress. Use when: (1) user says the repo is "messy with worktrees", "too many branches", "clean up the repo", "review the worktrees"; (2) `git worktree list` / `git branch -a` shows dozens of stale entries; (3) you must delete many branches/worktrees but the user said "without losing progress" / "keep <X>". Centres on the non-obvious trap that `git branch --merged` and `git merge-base --is-ancestor` report false "NOT merged" for squash-merged branches — so safety must be gated on PR state, not ancestry. Covers the verify-before-delete gate, salvaging untracked files before `git worktree remove`, and a SHA recovery manifest.
session-handoff-detect-prior-orphan-pr
Pre-flight detection of a prior incomplete /session-handoff run that already created a branch, PR, handoff doc, and/or worktree — so the current invocation doesn't open a duplicate PR. Use when (1) you're about to write `docs/handoffs/session_N_handoff.md` as part of /session-handoff, (2) you just created or considered creating a `docs/sN-handoff` branch and `git` reports "branch already exists" or `+` (checked out elsewhere), (3) you find a worktree under `.claude/worktrees/` whose name vaguely matches the current session number, (4) `git status` in a worktree you don't recognize shows "nothing to commit" but the working tree contains a session handoff doc you haven't seen written this turn. Root cause: a prior orchestrator (parallel session, aborted earlier run, or a /session-handoff that ran partway and lost its context) created the branch + handoff doc + push + PR before the current orchestrator picked up. Without this check, you'll write a fresh handoff doc in the main checkout, commit to a different bra
session-handoff-number-collision-with-unmerged-sibling
Detect and recover from a session-number collision when running session-handoff and a parallel/sibling session has authored a same-numbered handoff doc that hasn't merged into main yet. Use when: (1) you're in `session-handoff` Phase 1 about to write `docs/handoffs/session_NNN_handoff.md`, (2) `ls docs/handoffs/` shows the highest number is N-1 (so you pick N), BUT (3) MEMORY.md "Recent sessions" or sessions_archive.md already contains a `session_NNN_*.md` entry pointing at another worktree's branch whose PR hasn't merged. Symptom: you create files that don't collide on disk (the sibling's files live on a separate branch) but DO collide logically — both PRs claim "S167", a future reader can't tell which is which, and any cross-reference to "session_167_*" becomes ambiguous. Defends against the silent-logical-collision class (sister to `barryu-pr-conflict-site-regen` v1.4.0 Step 2c which covers the same shape for tracker IDs). Sister to `feedback_coordination_framing_for_ parallel_artifact_collisions` (proacti
squash-merge-content-preservation-vs-ancestor-check
Use when verifying that an upstream commit (e.g., a colleague's work, a feature-branch commit) is preserved in a target branch after a propagation PR has merged — and the verification script uses `git merge-base --is-ancestor <upstream-sha> <target-branch>`. If the merge mode was **squash**, that ancestor check ALWAYS returns non-zero even when content is preserved verbatim, because squash collapses every commit into a single new SHA on the target. Apply this skill when: (1) preservation audit for a recently-merged propagation PR returns "MISSING" or non-zero exit on `git merge-base --is-ancestor`, (2) handoff prompt mixes `is-ancestor` AND content checks without specifying merge mode, (3) you need to gate a merge on "did colleague's signature work survive". The correct probe depends on merge mode — fast-forward / no-ff preserves lineage; squash does not.
stacked-pr-base-branch-deletion-auto-closes-dependent
Recover from the trap where deleting a base PR's branch auto-closes any open dependent stacked PR, and the closed PR cannot be reopened or retargeted. Use when: (1) you set up a stacked PR pair (PR2's `base` field = PR1's branch instead of `main`), (2) you merged PR1 via squash, (3) PR1's remote branch got deleted — via ANY route: `gh pr merge <N> --squash --delete-branch`, `gh api -X DELETE refs/heads/<branch>`, or `gh pr merge` followed by separate branch cleanup — (4) the dependent PR2 is now reported as `state: CLOSED` even though you never closed it, (5) `gh pr reopen N` fails with `Could not open the pull request`, (6) `gh pr edit N --base main` fails with `Cannot change the base branch of a closed pull request`. The only recovery for the stacked-PR case is to open a fresh PR from the same head branch with base=main. **v1.2.0 (2026-05-19) adds the recoverable single-PR variant**: if the deleted branch was the HEAD of a single, in-flight, NEVER-MERGED PR (e.g. user deleted the branch after a failed merge
stacked-pr-review-per-base-diff-and-attach
Two paired patterns for reviewing a stack of dependent PRs (#A → #B → #C where each is based on the prior, not on main). (1) Reviewer agents need each PR's diff against ITS OWN base, not all-vs-main — otherwise upstream PR's changes show as part of downstream PR's diff and reviewers misattribute findings. Use `gh pr diff <N> -R owner/repo > prN-vs-its-base.diff` per PR. (2) Review reports for the whole stack should be committed to the BASE branch of the stack (the bottom PR's branch), not to the most recent one — every PR up the stack inherits them via base-branch advance, and PR diffs still show only the actual feature changes because merge-base advances too. Use when: dispatching a multi-agent review panel against 2+ stacked PRs; deciding where to commit reviewer report .md files; auditing whether a stacked-PR review panel saw the right per-PR scope.
stale-base-pr-silently-reverts-upstream-content
Detect and recover when a sibling PR's squash-merge silently reverts an upstream PR's content changes because the sibling was based on a pre-upstream main snapshot and its line-level rewrites overlapped the upstream PR's edits. Use when: (1) two PRs are open in parallel against the same file(s) — one refreshing numbers/values, the other rewriting copy/language, (2) the number-refresh PR merges first, the language-rewrite PR merges second, (3) the language-rewrite PR claims "all numbers preserved" in its body — true against ITS base, not against post-upstream-merge main, (4) post-merge of the second PR, displayed numbers regress to pre-fix values while OTHER files in the same upstream PR (untouched by the second PR) still hold the new values — creating a train-serve / display-vs-backend mismatch, (5) CI on both PRs was green and `mergeable: MERGEABLE` because git's 3-way merge resolves textual overlap silently (it does not see "numbers vs language" semantics). Detection: grep upstream PR's distinctive strings
subagent-bash-cd-wrong-worktree
Diagnose and prevent subagents committing to the wrong git branch when dispatched in multi-worktree setups. Use when (1) you dispatched a subagent (Task tool) with bash steps like `cd <target-worktree> && git commit ...`, (2) the subagent reported DONE with a real-looking commit SHA, (3) `git log` on the target worktree doesn't show that SHA — but `git branch --contains <sha>` finds it on a sibling branch (typically the parent repo's checked-out branch). Root cause: each Bash tool call starts in a shell whose cwd is reset to the agent's launch directory; `cd` in one call does not persist to the next. The subagent silently runs `git commit` from the launch directory's checked-out branch, not the worktree it intended.
subagent-driven-branch-ref-froze-stranded-commits
Diagnose and recover from "PR merged, but half my work is missing from main" cases in `superpowers:subagent-driven-development` (or similar one-fresh- subagent-per-task) sessions, where committed work survives in the worktree's `HEAD` chain but never makes it into the pushed branch ref. Use when ANY of these appears: (1) `gh pr view <N>` body claims "M files changed, N insertions" but `gh pr diff <N> --name-only | wc -l` returns a smaller number than you expect (canary: PR-body file count > actual squash-commit file count), (2) the merged squash commit on main is MISSING entire files you remember creating (Dockerfile, route handler, deploy artefact, etc.) — and you wrote AND committed them per the subagent reports, (3) `git rev-parse HEAD` ≠ `git rev-parse <feature-branch>` in the worktree (HEAD is ahead), (4) `git reflog show <feature-branch>` ends earlier than `git log --oneline` on the same worktree (reflog gap = stranded zone), (5) tests that passed locally during the session now fail on main because file
subagent-external-wait-orchestrator-takeover
Avoid orchestrator-budget burn when a subagent's main work is done but it's still polling an external event (CI completion, auto-deploy GHA workflow, Cloud Build, gcloud run revision rollout, long-running test suite, etc.). Use when: (1) you've dispatched a subagent with a final-step instruction like "verify auto-deploy" / "wait for CI green" / "poll until revision active", (2) the subagent has already done its substantive work (PR merged, artifact built) and is now in a polling loop, (3) you notice repeated `<task-notification>` events from that agent with `tool_uses: 0` and short `duration_ms` (a few seconds each) — each cycle says "still waiting" or "still in progress" with zero forward progress, (4) each notification forces the orchestrator to spend a turn responding (often dozens of these before the external event completes). The subagent isn't broken — it's doing what you asked — but the polling work belongs to the ORCHESTRATOR, not a subagent. Captures the takeover pattern: dispatch the subagent for th
subagent-pre-existing-misattribution
Catch subagent reviewers misattributing test failures across the pre-existing / PR-introduced boundary — in BOTH directions. Use when: (1) a multi-task subagent-driven plan reports "N pre-existing failures, unrelated" across consecutive tasks and the count never changes, (2) an architectural / final reviewer at the end catches assertions that should have been updated 5 tasks ago, (3) an implementer reports "verified pre-existing on clean tree by running git stash" but the breaking change is already committed on the branch, (4) you're building or executing a multi-task plan with subagent reviewers that compare suite-wide pass/fail counts to a "baseline", (5) **a single code-review subagent reviewing one PR flags failures as "Critical / PR-introduced" and reasons "the PR correctly updated X but forgot the test" — without ever diffing against origin/main** (the over-flagging mirror image: the reviewer infers causation from the *current file state* and assumes your PR made a change it never made). Root cause (bot
subagent-reports-complete-but-pr-unmerged
Catch the systematic gap between sub-agent "completed" status and the actual end state of a PR-merge orchestration task. Use when: (1) you've dispatched multiple parallel sub-agents (general-purpose or specialist) to open + review + merge PRs, (2) the parent receives `<task-notification>` with `status: completed` but the sub-agent's last action was waiting on CI, addressing a review finding, or pushing a rebased branch, (3) you're tempted to mark the parent task done based on the completion notification alone, (4) the parent has a TaskList tracking PR closure and you'd silently leave PRs OPEN. Root cause: sub-agents naturally terminate when they've kicked off the last asynchronous step (CI watcher, push command, reviewer dispatch), even if their brief required them to wait for that step's terminal state and then perform a follow-up (label, merge, delete-branch). The completion notification reflects sub-agent CONTEXT exhaustion, not orchestration COMPLETION. Observed 4/4 in one session. Fix: parent always runs
subagent-watchdog-stall-on-ui-template-track
Recognise the failure mode where a `general-purpose` (or similar) subagent dispatched to do UI/template-heavy work stalls and gets killed by the no-streamed-output watchdog (~600s of silence → terminate). Use when: (1) you dispatched a subagent for UI work (new page route + Jinja/template authoring + per-step iterative tests + small CSS), (2) the agent reports `failed: Agent stalled: no progress for 600s (stream watchdog did not recover)` with a partial result fragment like "Now let me look at the routes..." indicating it died mid-investigation, (3) the worktree contains uncommitted changes (the agent edited files before going silent and the work is salvageable), (4) you're considering re-dispatching with the same prompt or a "tighter" version — DON'T, because the stall is structural to dispatching this shape of work, not the prompt's fault. The fix is to switch to inline execution for the remainder of THIS task and bias toward inline for future UI/template tracks even though they cost more main-context token
synthetic-id-collision-rebase
Fix the "I claimed cat7-7bg, they claimed cat7-7bg, theirs merged first" failure mode when rebasing a PR after parallel sessions land mid-flight. Use when: (1) rebasing a stale PR onto current main produces a conflict in an append-only register file (tracker entries, ADR `NNNN-` prefixes, migration filenames, OpenAPI operationIds, error codes, lessons.md `## N.` numbering), (2) BOTH your branch and a freshly-merged branch added an entry under THE SAME synthetic ID — the collision is namespace, not just text, (3) plain "accept both sides" yields two rows with identical IDs that violate the file's invariant, (4) multiple Claude Code sessions share a working tree and each picked "next free letter" from their local view of the file. Prescribes a reroll workflow: scan ALL taken IDs in current main, pick truly-next-free, replay only your entry under the new ID, regenerate any derived artifacts (site, indexes), force-push. Also covers the variant where git splits the conflict boundary mid-argument-list of a multi-li
cutify-that-tab
Add a cute, hand-authored SVG favicon to a web app — the tiny icon that shows in the browser tab. Use when the user asks to add a favicon, browser tab icon, tab logo, page icon, site icon, or "cute thing in the tab," or says the current tab shows a blank/default square. Covers 3 techniques in increasing effort: (A) emoji-as-favicon via inline SVG data URI — zero assets; (B) gradient mascot blob — a soft blob shape with a face built from circles + a quadratic-curve smile; (C) 16×16 pixel-art sticker using SVG <rect> on an integer grid with shape-rendering="crispEdges" (bunny, bear, chick, mochi cat, ghost, frog, strawberry, cloud, dango, bee, ...). Includes the modern `<link rel="icon" type="image/svg+xml">` recipe (no more .ico files, no PNG fallbacks needed for modern browsers), tab-size verification, and which technique fits which vibe. Skip if the user wants a corporate/photographic logo — this skill is for hand-authored, cute, low-effort icons.
ab-harness
Run a counterfactual A/B harness on Claude Code to measure whether the user's ~/.claude setup (memories, lessons, axioms, skills, hooks, plugins) actually helps on real tasks vs. a blank-canvas env. Use when: (1) User wants to "prove my setup works" or "quantify setup impact" to colleagues; (2) User asks "is my setup actually helping" beyond what ecosystem-audit's reference-count scan can show; (3) A project has the counterfactual measurement step of an audit → measure → clean pipeline queued. Covers the clean-env mechanism (CLAUDE_CONFIG_DIR), what it does and doesn't isolate, fair-comparison knobs (model pinning, permission mode, stdin), how to mine num_turns/tool_calls/pitfall-hits from the resulting JSONL transcripts, and the honest caveats any n=3 harness report must declare.
doc-freshness-reverse-lint
Detect stale normative guidance after the user adds a NEW "don't X / avoid Y" rule to ~/.claude/lessons.md, ~/.claude/axioms.md, or any ~/.claude/projects/<slug>/memory/feedback_*.md. Also audits ~/.claude/skills/ for skills whose `last_verified` frontmatter has expired or that opt into a freshness contract without declaring one (axiom #21). Trigger when: (1) a PostToolUse hook fires on Edit|Write to one of those memory files and the diff contains a new negation rule; (2) user asks "are my project docs still consistent with my lessons / feedback?", "any stale advice in docs/?", "run doc freshness audit", "any stale skills?"; (3) weekly cron audit is due. Produces a list of CANDIDATE stale claims — file:line refs only. NEVER auto-edits. Conservative by design: for prose lint, surfaces only when the new rule has an explicit negation (don't / never / avoid / stop) AND a multi-token searchable phrase AND ≥1 grep hit. For skill freshness, the default mode flags only on EXPLICIT frontmatter signals (expired `last_v
gcp-dataform-rest-api-deploy
Deploy .sqlx files to Google Cloud Dataform repositories via REST API without the Dataform CLI. Use when: (1) deploying Dataform SQL from CI/CD or scripts, (2) programmatically updating Dataform workspaces, (3) triggering Dataform invocations from Cloud Workflows or automation, (4) adding NEW .sqlx files to a Dataform repo that also hosts other production release configs (v1.1.0: requires pre-merge workspace compile + post-merge cross-check gating to avoid breaking sibling release configs), (5) hitting "Only a commitish value of main is allowed" error when trying to compile a dev branch or non-main gitCommitish, (6) needing to discover exact target names with `_loader` suffix for workflowInvocations includedTargets, (7) renaming a .sqlx file whose `name:` (target name) is unchanged — both old and new produce the same target so they can't coexist (v1.2.0: atomic write+remove in one workspace commit + Gate-3 post-push compile against EVERY release config, with rollback recipe). Covers the full lifecycle: writeF
gh-issue-claim-coordination
Coordinate GitHub issue pickup across parallel Claude Code sessions (or human + agent) using BOTH `assignees` and a `wip` label, so sibling sessions detect the claim and skip. Use BEFORE writing any code that closes / addresses a GitHub issue when there's any chance another session is working the same repo. Trigger on phrases like "pick up issue
git-worktree
This skill manages Git worktrees for isolated parallel development. It handles creating, listing, switching, and cleaning up worktrees with a simple interactive interface, following KISS principles.
ecosystem-audit
ALWAYS use this skill when the user asks any question about their Claude Code setup, installed skills, memory system, handoffs, worktrees, or ~/.claude directory health. This is the go-to skill for introspection of the Claude Code environment itself. Specifically trigger on: (1) Skill inventory questions — "how many skills do I have", "which skills am I using", "what's dormant", "which skills can I uninstall", "are there overlapping skills"; (2) Cleanup and hygiene requests — "clean up my ecosystem", "audit my setup", "~/.claude feels bloated", "monthly hygiene check", "what needs cleanup", "stale worktrees", "orphaned handoff prompts"; (3) Diagnostic symptoms — "my memory system isn't working", "lessons aren't being picked up", "skill is not triggering", "claude keeps forgetting", "why is the wrong skill firing", "duplicate skill confusion"; (4) Health dashboards — "show me a health dashboard", "utilization across skills/memory/handoffs", "ecosystem health report"; (5) Any mention of auditing persistent arti
repo-hygiene
Pre-PR checklist and repo cleanup for data science and analytics projects. Use this skill BEFORE creating a PR, merging branches, or handing off a repo. Catches common mistakes that waste hours later: data files committed to git, hardcoded paths, runtime artifacts tracked, branch ownership confusion, internal docs drifting from deliverables, and client data in public repos. Also use when the user says "clean up the repo", "is this ready to merge?", "prepare for handover", "before we push", "repo hygiene", or when you notice tracked .csv, .db, .parquet, or /Users/ paths during any file operation. Especially important for repos with multiple contributors working on parallel branches.
session-handoff
End-of-session handoff that captures session knowledge, dispatches output across the canonical 7-bucket docs/ taxonomy (decisions/runbooks/analysis/references/reviews/handoffs/deliverables — aligned with memory-hygiene v3.3), triggers a doc-freshness reverse-lint + skill-freshness audit to catch stale normative guidance, emits the future-to-do plan's follow-up items as GitHub issues, updates memory, and prepares next-session prompts. Use when: (1) user says 'wrap up', 'hand over', 'create handoff', 'end of session', 'write handoff', 'session handoff'; (2) non-trivial work session (3+ tasks) is ending; (3) context window is approaching limits; (4) user says 'consolidate', 'what's the current state', 'start here document' after parallel sessions; (5) the session produced artifacts that belong in more than one docs/ bucket (ADR + analysis + runbook + review). Includes cross-session consolidation when 3+ handoffs accumulate and a mandatory reverse-lint verify step against any lessons.md / feedback_*.md touched th
publish-skill
Publish a Claude Code skill to GitHub as a polished, adoptable open-source repo, AND diagnose `claude plugin install` failures on a published skill. Use when the user says "publish this skill", "put this on GitHub", "share this skill", "release this skill publicly", "open source my skill", "make this skill installable", "create a GitHub repo for my skill", "package this skill for the marketplace", or wants to update an existing published skill repo. Also trigger when the user says "submit to awesome-claude-skills", "add my skill to the awesome list", "how do I let others install my skill?", "I finished my skill, now what?", "push my skill to a public repo", "generate a README and publish", "bump the version and republish", or "turn my local skill into a polished repo". ALSO trigger on `claude plugin install` failures and diagnostic questions: `Plugin X not found in any configured marketplace`, `Plugin X not found in marketplace Y`, `Invalid schema: plugins.0.source: Invalid input`, `Failed to add marketplace:
skill-sync
Keep locally installed Claude Code skills in sync with their GitHub repos. Use when the user says "sync my skills", "push skill updates", "which skills are out of date?", "skill-sync", "push my skill changes", "are my skills in sync?", "register my skills", or "init skill registry". Companion to publish-skill (publish = first-time, skill-sync = ongoing maintenance). Do NOT use for creating new skills (use skill-creator), first-time publishing (use publish-skill), or improving skill quality (use schliff).
large-redesign-parallel-branch-collision-audit
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` + `starbucks-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-r
overnight-insight-discovery
Run an overnight autonomous B-vs-C parallel insight-discovery workflow that surfaces ah-ha findings from data for a client. Use when: (1) a client wants interesting or surprising insights (not just monitoring or action items); (2) you want to hedge LLM creativity against deterministic rigor by running two tracks in parallel and consolidating; (3) the work fits an 8-hour autonomous window with review-panel gates; (4) the underlying data supports both exploratory querying and mechanical candidate scans. Specializes `overnight-review-client-delivery` for INSIGHT DISCOVERY rather than deliverable polishing — the two are sister skills with different problem shapes. ALWAYS use this skill when the user asks for "ah-ha insights", "surprise patterns", "funnel leaks", "hidden findings", "overnight analysis to surface X", or wants a dual-approach (creative + mechanical) for client-facing insight work — even if they don't explicitly name the pattern. NOT for: synchronous analysis (use exploratory- data-analysis), single-
overnight-multi-issue-implementation
Run an overnight autonomous workflow that takes a cluster of related GitHub issues (typically a P1 review-panel finding set) and ships them to merged PRs by morning. Use when: (1) the user wants 6-15 related issues closed in one autonomous run, (2) the issues split naturally into two PRs (e.g., hardening + features, or refactor + new-functionality), (3) the user is going to sleep and won't be available to merge PR1 between phases, (4) each issue has clear acceptance criteria so each task can be implemented + tested + reviewed independently. Specializes `superpowers:subagent-driven- development` for the "issues -> stacked PRs by morning" problem shape: stacks PR2 on PR1's branch (so PR2 doesn't wait for human PR1-merge mid- night), audits tracker IDs against main before claiming (concurrent sessions steal ids), runs final code-review subagent before proposing merge, and surfaces important findings as PR comments before squashing (so review trail survives). Sister plugin to `overnight-review-client- delivery` (
overnight-review-client-delivery
Run an overnight autonomous work session that produces a client delivery package the next morning, with a multi-agent review panel built in to catch factual errors before they reach the client. Use when: (1) you have client deliverables that need polishing/regenerating before a morning hand-off, (2) you want a thorough quality gate without blocking on synchronous review, (3) the work scope is bounded enough to fit in 1-3 hours of agent time, (4) you want to maximise agent throughput by running content work and review agents in parallel. Implements the Phase A (content work in foreground) / Phase B (8-agent review panel in parallel background) / Phase C (morning synthesis + user hand-off) structure validated on the a causal-impact project, including the locked-file escape hatch discipline for surgical P0 fixes, the "regenerate don't banner" rule for stale content refreshes, and parallel-agent branch hygiene to avoid silent commit drops. NOT for: synchronous code review (use ce:review or claude-code-guide inste
overnight-review-panel-blocked-reviewer-reads-as-clean
Overnight specialization of `code-reviewer-subagent-no-bash-blocked-on-pr-diff` (the general tool-gap mechanism). In an UNATTENDED overnight review panel, a reviewer that couldn't see the code reads as a CLEAN one — so a real bug ships by morning. The usual cause: code-review subagents (feature-dev:code-reviewer, voltagent-*, Explore) are frequently provisioned WITHOUT a Bash tool, so when prompted to "review PR #N, fetch the diff with gh pr diff" they return a BLOCKED report (no review performed), or silently review the current checkout (often `main`, which predates the PR). Use when: (1) an overnight review panel (e.g. `overnight-multi-issue-implementation` Phase C, or any `agent-review-panel` run) dispatches reviewers against GitHub PRs or branches not checked out in the working tree; (2) a reviewer returns "I have no shell/gh/git tool" or "the PR sources are not in the working tree"; (3) one reviewer in a parallel panel comes back BLOCKED while siblings succeeded. Fix: pre-generate per-base diffs to files
schedule-poll-orchestrator-pattern
Fire-ASAP orchestrator pattern for multi-track autonomous workflows dispatched via scheduled triggers (RemoteTrigger / CronCreate) rather than in-session agents. Use when: (1) a multi-track overnight workflow's orchestrator trigger has a fixed `t+Nh` timer that wastes wallclock when tracks finish early, (2) an overnight run should run consolidation/merge AS SOON AS all parallel tracks report complete, not on a clock, (3) the parent orchestrator session is too context-heavy to stay alive 12-20h and needs a scheduled successor to pick up track outputs, (4) you're choosing between "fire all tracks + one fixed-timer consolidator" vs "fire tracks + self-rescheduling polling consolidator". The polling pattern replaces a fixed wait with a cheap re-schedule loop that exits to consolidation at the first poll where all tracks report `phase: complete`. Distinct from `successor-handoff` (in-session parent polling a subagent) — this is for scheduled-trigger orchestrators that need to survive session ends.
subagent-review-tier-calibration-for-overnight-pr-chains
Calibrate review intensity per-PR when orchestrating a long chain (10+ PRs) of independent tasks overnight from a single implementation plan. Use when: (1) running `superpowers:subagent-driven-development` against a plan that produces many independent PRs (not stacked PRs from an issue cluster — for that shape use `overnight-multi-issue-implementation`), (2) user has authorized auto-merge on green review, (3) the user is asleep / unavailable to merge between tasks, (4) the chain spans multiple risk tiers (some PRs rewrite views/handlers, others restyle CSS only). The skill prescribes three review tiers — full two-stage / combined single-agent / bash-only verification — and a decision rubric for picking the right tier per PR to maximize overnight throughput WITHOUT silently approving real bugs. Sister to `subagent-driven-development` (specializes its review step for throughput-tuned chains) and `overnight-multi-issue-implementation` (different problem shape — issues vs. plan tasks; stacked vs. independent). Sy
memory-hygiene
Audit and clean up Claude Code's persistent memory system — MEMORY.md, memory files, lessons, and ADRs. Use this skill when: (1) the user asks to clean up, audit, or review their memory/lessons/ADRs, (2) MEMORY.md is approaching or exceeding the 200-line limit, (3) lesson files have grown large and may contain duplicates, (4) you notice ADR numbering conflicts, (5) memory files seem stale or contradicted by current code, or (6) the user says things like 'my memory is getting messy', 'clean up my lessons', 'deduplicate', 'review ADRs', 'memory audit'. Also proactively suggest running this after 10+ sessions on a project, or when MEMORY.md triggers a truncation warning.
test-effectiveness-auditor
Quantitatively measure how effective a project's automated tests are at catching real bugs. Use this skill when: (1) the user asks 'how good are our tests?', 'do our tests actually catch bugs?', 'measure test effectiveness', or 'audit our test suite'; (2) a team has anecdotal impressions about test quality but no data; (3) before investing in more tests, to identify which gaps matter most; (4) after an incident slipped through CI, to understand whether the test suite should have caught it; (5) when evaluating whether a CI pipeline is paying for itself. Produces a report at ~/Documents/<project>_test_effectiveness_audit.md with per-incident catch rates, a classified gap list, and targeted recommendations. Read-only relative to project source — does not modify code or auto-write tests.
Bio shown is the top-scored skill's repo description as a fallback — real GitHub bios land in a future update.