Skip to content

docs(commands): teach Claude to extract PR refs and quote focus text#8

Merged
JohnnyVicious merged 1 commit intomainfrom
docs/teach-claude-pr-extraction
Apr 12, 2026
Merged

docs(commands): teach Claude to extract PR refs and quote focus text#8
JohnnyVicious merged 1 commit intomainfrom
docs/teach-claude-pr-extraction

Conversation

@JohnnyVicious
Copy link
Copy Markdown
Owner

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

  1. PR reference extraction (REQUIRED — both review.md and adversarial-review.md):

    • New rule 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: on PR #390 challenge the caching strategy--pr 390 'challenge the caching strategy'.
  2. Focus text quoting (REQUIRED — adversarial-review.md only, since review.md doesn't take focus text):

    • New rule telling Claude to wrap focus text in single quotes when invoking bash, so other shell metacharacters (*, $, ;, &, |, <, >, parens, backticks) survive intact.
    • Includes the standard '\'' escape recipe for apostrophes in user input.
  3. Foreground/background flow examples updated in adversarial-review.md:

    • Stops showing $ARGUMENTS literally (which was training Claude to invoke bash without any of the above transformations).
    • Instead shows the illustrative shape <flags> [--pr N] ['<quoted focus text>'] with an explicit "transform $ARGUMENTS first" instruction pointing at the rules above.

Companion-script behaviour kept as fallback

detectPrReference and the auto-detect path in handleAdversarialReview are intentionally kept, so that:

  • Anyone calling the companion script directly via bash with proper quoting still gets PR detection
  • Future invocation paths that don't go through the slash command still benefit
  • The defensive fallback covers Claude not following the new rules perfectly

Test plan

  • Local: npm test — 62 tests, 0 failures (markdown-only changes don't affect tests)
  • Demonstrated the bash comment-stripping behaviour with a minimal repro
  • Manual verification after merge: /opencode:adversarial-review on PR #389 should produce node ... adversarial-review --pr 389 and the review should hit PR #389's diff, not the local working tree
  • CI green

`/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.
@JohnnyVicious JohnnyVicious merged commit 519f535 into main Apr 12, 2026
1 check passed
@JohnnyVicious JohnnyVicious deleted the docs/teach-claude-pr-extraction branch April 12, 2026 13:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant