Add specification for @issuetopr mention behavior

[youngchingjui]

Summary

This PR adds a comprehensive specification document that defines how the @issuetopr app should respond when mentioned in GitHub issues and pull requests. This serves as a design guide for implementing the mention-triggered workflow functionality.

Key Changes

• New specification document (docs/specs/issuetopr-mention-behavior.md) covering:
  • Trigger locations: Documents all places where @issuetopr can be mentioned (issue comments, PR comments, PR reviews, inline review comments)
  • PR review deduplication: Defines a strategy to prevent duplicate workflow triggers when users mention @issuetopr in both top-level reviews and inline comments using review ID correlation
  • Response behavior: Specifies the expected app behavior including acknowledgment, response, execution, and reporting
  • Context-aware actions: Guidance on deciding between running workflows vs. conversational responses based on user intent
  • Context gathering: Requirements for understanding repository, issue/PR, and comment context before taking action
  • Feedback loop: Support for iterative improvements through multiple interactions
  • Error handling: Defined responses for various error states (unauthorized users, rate limiting, unclear requests, etc.)

Notable Implementation Details

• The deduplication strategy uses a short-lived cache (30-60 second window) keyed by pull_request_review_id to handle nearly-simultaneous webhook events from GitHub
• The spec distinguishes between workflow-triggering requests (code changes, fixes, implementations) and conversational responses (questions, explanations, suggestions)
• Emphasizes context gathering from repository, issue/PR history, and specific comments before taking action
• Defaults to asking for clarification in ambiguous cases rather than making assumptions

This specification provides the foundation for implementing the core mention-triggered functionality of the @issuetopr app.

---

Note

Low Risk
Documentation-only change with no runtime/code-path impact; risk is limited to potential misinterpretation of intended behavior.

Overview
Adds a new spec doc, docs/specs/issuetopr-mention-behavior.md, defining expected @issuetopr behavior when mentioned in issues, PR comments, and PR reviews.

The spec covers reply-vs-change decision rules, scope matching based on mention location, the user interaction flow (acknowledge/respond/execute/report), and an approach to deduplicate near-simultaneous PR review webhooks via a short-lived cache keyed by pull_request_review_id.

^{Written by Cursor Bugbot for commit bc4cf5a. This will update automatically on new commits. Configure here.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

• 🔍 Trigger a full review

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch claude/github-app-webhook-specs-XiEBI

Tip

🧪 Unit Test Generation v2 is now available!

We have significantly improved our unit test generation capabilities.

To enable: Add this to your .coderabbit.yaml configuration:

reviews:
  finishing_touches:
    unit_tests:
      enabled: true

Try it out by using the @coderabbitai generate unit tests command on your code files or under ✨ Finishing Touches on the walkthrough!

Have feedback? Share your thoughts on our Discord thread!

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}