docs(commands): teach Claude to extract PR refs and quote focus text#8
Merged
JohnnyVicious merged 1 commit intomainfrom Apr 12, 2026
Merged
Conversation
`/opencode:adversarial-review on PR #389` was silently misrouted to a working-tree review because bash strips unquoted `#389` tokens as comments before they reach the companion script. The fix in PR #2 (detectPrReference + focus auto-detect in handleAdversarialReview) was correct in isolation but never ran — by the time the companion script saw argv, the `#389` had already been removed at the shell boundary, so the regex had nothing to match. The fix has to live at the slash-command markdown level, because that is where Claude reads the instructions about how to construct the bash command. Two complementary defenses: 1. **PR reference extraction (REQUIRED)**. New rule in both adversarial-review.md and review.md telling Claude to recognise `PR #N` / `pr #N` / `PR N` patterns in the user's input, extract the number, pass it as `--pr N`, and strip the matched phrase from any focus text. Includes a worked transformation example showing the wrong (bash-eats-the-comment) vs right (--pr extracted) form. 2. **Focus text quoting (REQUIRED, adversarial only)**. New rule in adversarial-review.md telling Claude to wrap focus text in single quotes when invoking bash, so other shell metacharacters (`*`, `$`, `;`, `&`, `|`, `<`, `>`, parens, backticks) survive. Includes guidance on the `'\''` escape for apostrophes. 3. Updated the foreground/background flow examples to stop showing `$ARGUMENTS` literally (which trained Claude to invoke bash without any of the above transformations) and instead show the illustrative shape `<flags> [--pr N] ['<quoted focus>']` with an explicit "transform $ARGUMENTS first" instruction. The companion script's focus-text PR auto-detect (detectPrReference) is intentionally kept as a fallback for cases where focus text reaches the script intact (e.g. someone calling the companion directly via bash with proper quoting, bypassing the slash command). No code or test changes — these are slash-command instructions read by Claude, not executed by node.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Fixes the bug you spotted: `/opencode:adversarial-review on PR #389` was silently misrouted to a working-tree review because bash strips unquoted `#389` tokens as comments before they reach the companion script.
`detectPrReference` (added in #2) was correct, but it never ran — by the time argv reached node, the `#389` had already been chopped off at the shell boundary, so the regex had nothing to match. Demonstration:
```
$ bash -c 'node -e "console.log(JSON.stringify(process.argv.slice(1)))" adversarial-review on PR #389'
["adversarial-review","on","PR"] ← unquoted: #389 stripped
$ bash -c "node -e "console.log(JSON.stringify(process.argv.slice(1)))" adversarial-review 'on PR #389'"
["adversarial-review","on PR #389"] ← single-quoted: preserved
```
The fix has to live at the slash-command markdown level, because that's where Claude reads the instructions about how to construct the bash command. Code-level fixes are powerless once bash has already eaten the input.
Changes
PR reference extraction (REQUIRED — both
review.mdandadversarial-review.md):PR #N/pr #N/PR Npatterns in the user's input, extract the number, pass it as--pr N, and strip the matched phrase from any focus text.on PR #390 challenge the caching strategy→--pr 390 'challenge the caching strategy'.Focus text quoting (REQUIRED —
adversarial-review.mdonly, sincereview.mddoesn't take focus text):*,$,;,&,|,<,>, parens, backticks) survive intact.'\''escape recipe for apostrophes in user input.Foreground/background flow examples updated in
adversarial-review.md:$ARGUMENTSliterally (which was training Claude to invoke bash without any of the above transformations).<flags> [--pr N] ['<quoted focus text>']with an explicit "transform $ARGUMENTS first" instruction pointing at the rules above.Companion-script behaviour kept as fallback
detectPrReferenceand the auto-detect path inhandleAdversarialRevieware intentionally kept, so that:Test plan
npm test— 62 tests, 0 failures (markdown-only changes don't affect tests)/opencode:adversarial-review on PR #389should producenode ... adversarial-review --pr 389and the review should hit PR #389's diff, not the local working tree