name: github-interaction
description: Comprehensive guide for working with GitHub data and APIs. Use when fetching issues, PRs, discussions, comments, reviews, or any GitHub content. Covers tool selection (mcp_github vs fetch vs semantic search), complete conversation fetching patterns, pagination handling, and common workflows. Critical for avoiding standard API failures when fetching comments/reviews—MCP tools required.

GitHub Interaction

Guide for effective GitHub data retrieval covering tool selection, complete conversation fetching, and common patterns.

Critical Rule: MCP Tools for Comments and Reviews

ALWAYS use GitHub MCP tools (mcp_github_*) to fetch PR/issue comments and reviews. Standard API access will fail.

This is the most common mistake. When you need comments, reviews, or discussion threads, you MUST use the MCP tools.

Tool Selection Decision Tree

When to use mcp_github_* tools

Use for ALL GitHub data operations:
- ✅ Fetching issues, PRs, discussions (individual or lists)
- ✅ Getting comments (issue comments, PR review comments, discussion comments)
- ✅ Getting reviews (PR reviews and review threads)
- ✅ Getting file contents from repos
- ✅ Creating/updating issues, PRs, comments
- ✅ Searching issues, PRs, code, repositories, users
- ✅ Managing branches, commits, assignees, labels

Examples:

mcp_github_issue_read (method: get, get_comments, get_sub_issues, get_labels)
mcp_github_pull_request_read (method: get, get_diff, get_files, get_review_comments, get_reviews, get_comments)
mcp_github_get_discussion + mcp_github_get_discussion_comments
mcp_github_search_issues, mcp_github_search_pull_requests, mcp_github_search_code
mcp_github_get_file_contents

When to use fetch_webpage

Use ONLY for external web content:
- ✅ Public documentation sites
- ✅ Blog posts, articles (not on GitHub)
- ✅ External APIs or services
- ❌ NEVER for GitHub issues/PRs/discussions/comments

When to use github_repo semantic search

Use for finding code patterns across GitHub repositories:
- ✅ Searching for function/class implementations across repos
- ✅ Finding usage examples in codebases
- ✅ Discovering patterns in specific GitHub repo source code
- ❌ Not for issues/PRs/discussions (use mcp_github_search_* instead)

When to use grep_search / semantic_search

Use for LOCAL workspace files only:
- ✅ Searching files in current VS Code workspace
- ✅ Finding patterns in brain repository notes
- ✅ Locating local code or documentation
- ❌ NEVER for GitHub remote content

Complete Conversation Fetching Patterns

Fetching a Full Issue

Pattern: Get issue + get all comments

1. mcp_github_issue_read (method: get, issue_number: X)
   → Returns issue details (title, body, state, assignees, labels, etc.)

2. mcp_github_issue_read (method: get_comments, issue_number: X, perPage: 100)
   → Returns all comments with author, timestamp, body
   → Use pagination if > 100 comments (page parameter)

What you get: Complete issue thread including description and all discussion

Fetching a Full Pull Request

Pattern: Get PR + diff + files + review comments + reviews + general comments

1. mcp_github_pull_request_read (method: get, pullNumber: X)
   → Returns PR metadata (title, body, state, base/head, mergeable, etc.)

2. mcp_github_pull_request_read (method: get_diff, pullNumber: X)
   → Returns unified diff of all changes

3. mcp_github_pull_request_read (method: get_files, pullNumber: X, perPage: 100)
   → Returns list of changed files with stats
   → Paginate if many files changed

4. mcp_github_pull_request_read (method: get_review_comments, pullNumber: X, perPage: 100)
   → Returns review threads (line-specific comments grouped by thread)
   → Each thread has metadata: isResolved, isOutdated, isCollapsed
   → Use cursor-based pagination (after parameter) if needed

5. mcp_github_pull_request_read (method: get_reviews, pullNumber: X, perPage: 100)
   → Returns formal reviews (APPROVE, REQUEST_CHANGES, COMMENT)
   → Includes review body and state

6. mcp_github_pull_request_read (method: get_comments, pullNumber: X, perPage: 100)
   → Returns general PR comments (not line-specific)
   → These are issue-style comments on the PR conversation

What you get: Complete PR context including code changes, all review feedback, and discussion

Important distinctions:
- get_review_comments: Line-specific code review threads
- get_reviews: Formal review submissions (approve/request changes)
- get_comments: General conversation comments (not tied to code lines)

Fetching a Full Discussion

Pattern: Get discussion + get all comments with pagination

1. mcp_github_get_discussion (owner: X, repo: Y, discussionNumber: Z)
   → Returns discussion details (title, body, category, state)

2. mcp_github_get_discussion_comments (owner: X, repo: Y, discussionNumber: Z, perPage: 100)
   → Returns nested comment threads
   → Use cursor-based pagination (after: endCursor from previous response)
   → Each comment includes replies (nested threads)

What you get: Complete discussion with all threaded replies

Pagination note: Discussions use GraphQL cursor-based pagination. Check pageInfo.hasNextPage and use pageInfo.endCursor in after parameter.

Common Patterns and Workflows

Searching for PRs/Issues with Filters

Date filtering:

mcp_github_search_pull_requests
  query: "author:jonmagic created:2025-11-01..2025-11-30"

mcp_github_search_issues
  query: "involves:jonmagic updated:>=2025-11-01"

State filtering:

# Merged PRs only
query: "is:merged author:jonmagic repo:github/github"

# Open issues assigned to you
query: "is:open assignee:jonmagic"

# Closed issues in date range
query: "is:closed closed:2025-11-01..2025-11-30"

Combining filters:

query: "is:pr is:merged author:jonmagic repo:github/hamzo created:2025-11-01..2025-11-30"

Fetching Multiple Items Efficiently

Batch pattern (for small lists):

1. Search for items: mcp_github_search_pull_requests
2. For each result (up to 5-10), fetch details in parallel:
   - mcp_github_pull_request_read (method: get, pullNumber: N)

Avoid: Fetching full details for 50+ items at once. Instead, ask user which specific items to deep-dive.

Creating PRs with Proper Formatting

mcp_github_create_pull_request
  title: "Clear, specific title"
  body: "## Summary\n\n...\n\n## Changes\n\n- Item 1\n- Item 2"
  head: "feature-branch-name"
  base: "main"
  draft: false (or true for work-in-progress)

Body formatting tips:
- Use Markdown (headings, lists, code blocks)
- Reference issues: Closes #123 or Relates to #456
- Include context for reviewers
- Add testing notes or screenshots if relevant

Adding Comments vs Reviews

Issue comment (general discussion):

mcp_github_add_issue_comment
  issue_number: X
  body: "Your comment text"

PR review (formal approval/changes requested):

1. Create pending review:
   mcp_github_pull_request_review_write (method: create)
     body: "Overall feedback"
     event: null (omit to create pending)

2. Submit review:
   mcp_github_pull_request_review_write (method: submit_pending)
     body: "Final summary"
     event: "APPROVE" | "REQUEST_CHANGES" | "COMMENT"

Pagination Best Practices

REST-based Pagination (page/perPage)

Used by: list_issues, list_pull_requests, get_comments, get_files, get_reviews

perPage: 100 (max)
page: 1, 2, 3, ... (1-based)

Pattern:

1. First call: perPage: 100, page: 1
2. If results.length === 100, likely more pages
3. Next call: perPage: 100, page: 2
4. Repeat until results.length < 100

GraphQL Cursor Pagination (after/endCursor)

Used by: list_issues (GraphQL mode), get_discussion_comments, get_review_comments

perPage: 100
after: "cursor-string-from-previous-response"

Pattern:

1. First call: perPage: 100 (no after)
2. Check response.pageInfo.hasNextPage
3. If true, next call: perPage: 100, after: response.pageInfo.endCursor
4. Repeat until hasNextPage === false

Common Mistakes to Avoid

❌ Using fetch_webpage for GitHub issues/PRs
- Standard web scraping doesn't work for GitHub content
- Always use MCP tools

❌ Forgetting pagination
- Default limits are often 30 items
- Set perPage: 100 to reduce round trips
- Check for more pages before concluding

❌ Mixing up comment types
- Issue comments ≠ PR review comments ≠ PR general comments
- Use correct method for each type

❌ Not filtering by date range
- Fetching all historical data when you only need recent work
- Use created:, updated:, merged: filters

❌ Ignoring PR state when searching for completed work
- Open PRs should go to "Ideas" section in snippets
- Only merged/closed PRs belong in "Ships"
- Use is:merged or is:closed filters

Quick Reference: Method Cheat Sheet

Issues

• Get issue: issue_read (method: get)
• Get comments: issue_read (method: get_comments)
• Get sub-issues: issue_read (method: get_sub_issues)
• Create/update: issue_write (method: create | update)
• Search: search_issues

Pull Requests

• Get PR: pull_request_read (method: get)
• Get diff: pull_request_read (method: get_diff)
• Get files: pull_request_read (method: get_files)
• Get review comments: pull_request_read (method: get_review_comments)
• Get reviews: pull_request_read (method: get_reviews)
• Get general comments: pull_request_read (method: get_comments)
• Create PR: create_pull_request
• Update PR: update_pull_request
• Search: search_pull_requests

Discussions

• Get discussion: get_discussion
• Get comments: get_discussion_comments
• List: list_discussions

Other

• Search code: search_code
• Search repos: search_repositories
• Get file: get_file_contents
• List branches: list_branches
• Get commit: get_commit