From 75a53ebb883ee610b1c63a8dfa38fb0a97f44101 Mon Sep 17 00:00:00 2001 From: jinku Date: Mon, 13 Apr 2026 00:56:07 -0700 Subject: [PATCH] Clarify review versus rescue skill routing --- README.md | 5 +++++ skills/adversarial-review/SKILL.md | 6 +++++- skills/rescue/SKILL.md | 5 ++++- skills/review/SKILL.md | 6 +++++- tests/skills-contracts.test.mjs | 8 ++++++++ 5 files changed, 27 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 3dd2f01..bd5b404 100644 --- a/README.md +++ b/README.md @@ -101,6 +101,11 @@ When it finishes, Codex should nudge you toward the right result. If not, `$cc:s | `$cc:cancel` | Cancel an active background job | | `$cc:setup` | Verify installation, auth, hooks, and review gate | +Quick routing rule: +- Use `$cc:review` for straightforward correctness review of the current diff. +- Use `$cc:adversarial-review` for riskier config/template/migration/design changes, or whenever you want stronger challenge on assumptions and tradeoffs. +- Use `$cc:rescue` when you want Claude Code to investigate, validate by changing code, or actually fix/implement something. + ### `$cc:review` Standard read-only review of your current work. diff --git a/skills/adversarial-review/SKILL.md b/skills/adversarial-review/SKILL.md index 49be6b4..ef3df05 100644 --- a/skills/adversarial-review/SKILL.md +++ b/skills/adversarial-review/SKILL.md @@ -1,12 +1,16 @@ --- name: adversarial-review -description: 'Run a design-challenging Claude Code review of local git changes in this repository. Args: --wait, --background, --base , --scope , --model , [focus text]. Use when the user wants stronger scrutiny, tradeoff analysis, or custom review focus text.' +description: 'Run a design-challenging Claude Code review of local git changes in this repository. Args: --wait, --background, --base , --scope , --model , [focus text]. Use when the user wants stronger scrutiny, tradeoff analysis, risky-change review, or custom review focus text.' --- # Claude Code Adversarial Review Use this skill when the user wants Claude Code to challenge the implementation approach, design choices, assumptions, or tradeoffs in this repository. +Prefer `$cc:adversarial-review` over `$cc:review` when the change touches configuration, infrastructure, templating, rollout mechanics, migrations, safety controls, or "this should remove mismatch/drift" style refactors. +Use it even without extra focus text when the real question is "did this actually eliminate the risk or just move it around?" +If the user wants Claude Code to go beyond review and perform investigation, validation edits, or implementation work, route to `$cc:rescue` instead. + Do not derive the companion path from this skill file or any cache directory. Always run the installed copy: `node "/scripts/claude-companion.mjs" adversarial-review ...` diff --git a/skills/rescue/SKILL.md b/skills/rescue/SKILL.md index ee3dd72..6a249fe 100644 --- a/skills/rescue/SKILL.md +++ b/skills/rescue/SKILL.md @@ -1,6 +1,6 @@ --- name: rescue -description: 'Delegate a substantial diagnosis, implementation, or follow-up task to Claude Code through the tracked-job runtime. Args: --background, --wait, --resume, --resume-last, --fresh, --write, --model , --effort , --prompt-file , [task text]. Use for deeper work, not for standard review or quick local questions.' +description: 'Delegate a substantial diagnosis, implementation, or follow-up task to Claude Code through the tracked-job runtime. Args: --background, --wait, --resume, --resume-last, --fresh, --write, --model , --effort , --prompt-file , [task text]. Use when Claude should investigate or change things, not when the user only wants review findings.' --- # Claude Code Rescue @@ -12,6 +12,9 @@ Foreground rescue responses must be that subagent's output verbatim. Use this skill when the user wants Claude Code to investigate, implement, or continue substantial work in this repository. +Prefer `$cc:rescue` when the user wants Claude Code to diagnose the issue, validate a risky change by actually editing or testing, apply fixes from a prior review, or carry a task forward across multiple steps. +Do not use rescue for "just review this diff" unless the user also wants follow-through work beyond review findings. + Do not derive the companion path from this skill file or any cache directory. Always run the installed copy: `node "/scripts/claude-companion.mjs" task ...` diff --git a/skills/review/SKILL.md b/skills/review/SKILL.md index 17bf918..3c41787 100644 --- a/skills/review/SKILL.md +++ b/skills/review/SKILL.md @@ -1,12 +1,16 @@ --- name: review -description: 'Run a standard Claude Code review of local git changes in this repository. Args: --wait, --background, --base , --scope , --model . Use for normal diff review requests, not staged-only review or custom focus text.' +description: 'Run a standard Claude Code review of local git changes in this repository. Args: --wait, --background, --base , --scope , --model . Use for straightforward correctness-oriented diff review when the user wants findings only, not custom focus text, adversarial framing, or implementation work.' --- # Claude Code Review Use this skill when the user wants Claude Code to review the current working tree or a branch diff in this repository. +Choose `$cc:review` only for straightforward review requests where the user mainly wants correctness findings on the current diff. +If the user wants stronger challenge on design, rollout risk, migration risk, configuration behavior, template mismatch elimination, or any custom focus text, route to `$cc:adversarial-review` instead. +If the user wants Claude Code to investigate, validate by changing code, or actually fix/implement something, route to `$cc:rescue` instead. + Do not derive the companion path from this skill file or any cache directory. Always run the installed copy: `node "/scripts/claude-companion.mjs" review ...` diff --git a/tests/skills-contracts.test.mjs b/tests/skills-contracts.test.mjs index 1af481a..43355d8 100644 --- a/tests/skills-contracts.test.mjs +++ b/tests/skills-contracts.test.mjs @@ -22,6 +22,9 @@ test("review skills keep background execution outside the companion command", () const installedRootPattern = /\/scripts\/claude-companion\.mjs/i; assert.match(review, /Do not derive the companion path from this skill file or any cache directory/i); + assert.match(review, /Choose `\$cc:review` only for straightforward review requests where the user mainly wants correctness findings on the current diff/i); + assert.match(review, /If the user wants stronger challenge on design, rollout risk, migration risk, configuration behavior, template mismatch elimination, or any custom focus text, route to `\$cc:adversarial-review` instead/i); + assert.match(review, /If the user wants Claude Code to investigate, validate by changing code, or actually fix\/implement something, route to `\$cc:rescue` instead/i); assert.match(review, installedRootPattern); assert.match(review, /Treat `--wait` and `--background` as Codex-side execution controls only/i); assert.match(review, /Strip them before calling the companion command/i); @@ -60,6 +63,9 @@ test("review skills keep background execution outside the companion command", () assert.doesNotMatch(review, /claude-companion\.mjs" review \$ARGUMENTS/i); assert.match(adversarial, /Do not derive the companion path from this skill file or any cache directory/i); + assert.match(adversarial, /Prefer `\$cc:adversarial-review` over `\$cc:review` when the change touches configuration, infrastructure, templating, rollout mechanics, migrations, safety controls, or "this should remove mismatch\/drift" style refactors/i); + assert.match(adversarial, /Use it even without extra focus text when the real question is "did this actually eliminate the risk or just move it around\?"/i); + assert.match(adversarial, /If the user wants Claude Code to go beyond review and perform investigation, validation edits, or implementation work, route to `\$cc:rescue` instead/i); assert.match(adversarial, installedRootPattern); assert.match(adversarial, /Treat `--wait` and `--background` as Codex-side execution controls only/i); assert.match(adversarial, /Strip them before calling the companion command/i); @@ -103,6 +109,8 @@ test("rescue skill keeps --background and --wait as host-side controls only", () const installedRootPattern = /\/scripts\/claude-companion\.mjs/i; assert.match(rescue, /Do not derive the companion path from this skill file or any cache directory/i); + assert.match(rescue, /Prefer `\$cc:rescue` when the user wants Claude Code to diagnose the issue, validate a risky change by actually editing or testing, apply fixes from a prior review, or carry a task forward across multiple steps/i); + assert.match(rescue, /Do not use rescue for "just review this diff" unless the user also wants follow-through work beyond review findings/i); assert.match(rescue, installedRootPattern); assert.match(rescue, /`--background` and `--wait` are Codex-side execution controls only/i); assert.match(rescue, /Never satisfy background rescue by launching `claude-companion\.mjs task` itself as a detached shell process/i);