copilot-feedback-resolver

What this skill does

# Copilot Feedback Resolver

Process and resolve GitHub Copilot's automated PR review comments systematically.

## ⛔ PR Comments Prohibition (CRITICAL)

**NEVER leave comments directly on GitHub PRs.** This is strictly forbidden:

- ❌ `gh pr review --comment` - FORBIDDEN
- ❌ `gh pr comment` - FORBIDDEN
- ❌ Any GraphQL mutation that creates new reviews or PR-level comments - FORBIDDEN
- ❌ Responding to human review comments - FORBIDDEN

**This skill ONLY processes GitHub Copilot threads.** Never interact with threads created by human reviewers.

**Permitted operations:**
- ✅ Reply to EXISTING Copilot threads using `addPullRequestReviewThreadReply`
- ✅ Resolve Copilot threads using `resolveReviewThread`

## ⚠️ CRITICAL REQUIREMENTS ⚠️

### YOU MUST RESOLVE THREADS AFTER ADDRESSING THEM

**After fixing any Copilot feedback, you MUST:**

1. **Push the code changes** (`git push`)
2. **Resolve EACH thread** using the GraphQL mutation (see below)
3. **Verify resolution** by re-querying the PR

**Addressing feedback without resolving the thread is INCOMPLETE WORK.**

The thread resolution is NOT optional - it's the primary deliverable of this skill. Code changes alone are insufficient.

### Thread Resolution Mutation (USE THIS!)

**IMPORTANT:** Use inline values, NOT `$variable` syntax. The `$` character causes shell escaping issues (`Expected VAR_SIGN, actual: UNKNOWN_CHAR`).

```bash
# Replace THREAD_ID with actual thread ID (e.g., PRRT_kwDONZ...)
gh api graphql -f query='
mutation {
  resolveReviewThread(input: {threadId: "THREAD_ID"}) {
    thread { isResolved }
  }
}'
```

**You MUST call this mutation for EVERY thread you address.**

### YOU MUST UPDATE COPILOT-INSTRUCTIONS.MD FOR INCORRECT FEEDBACK

**When Copilot feedback is categorized as INCORRECT (conflicts with project conventions/patterns), you MUST:**

1. **Update `.github/copilot-instructions.md`** to document the correct pattern
2. This prevents Copilot from flagging the same or similar things in future PRs
3. The update should be concise and explain why the pattern is intentional

**Failure to update copilot-instructions.md = INCOMPLETE WORK for Incorrect category feedback.**

#### CRITICAL: File Structure Requirements

**Copilot only reads the first ~4000 characters for PR reviews.** Therefore:

1. **Review instructions MUST go at the TOP** of the file, in a dedicated section
2. **Use a specific review-targeted section** like `## PR Review Checklist (CRITICAL)` as the first section
3. **Keep the review section under 4000 characters** - measure with `head -c 4000 .github/copilot-instructions.md | wc -c`
4. **If exceeding 4000 chars, COMPRESS the section:**
   - Remove redundant words
   - Use terse bullet points
   - Combine related items
   - Move non-review guidance below the 4000 char threshold

Example structure:
```markdown
# GitHub Copilot Instructions

## PR Review Checklist (CRITICAL)
<!-- KEEP THIS SECTION UNDER 4000 CHARS - Copilot only reads first ~4000 -->

- **Pattern X**: Intentional, do not flag
- **Pattern Y**: Required for Z reason

## Code Style
<!-- Less critical sections go below -->
```

**After updating, verify:** `head -c 4000 .github/copilot-instructions.md | tail -5` should show content from the review section, not unrelated sections.

---

## Prerequisites

**CRITICAL: Load the `fx-dev:github` skill FIRST** before running any GitHub API operations. This skill provides essential patterns and error handling for `gh` CLI commands.

## WHEN TO USE THIS SKILL

**USE THIS SKILL PROACTIVELY** when ANY of the following occur:

- User says "check copilot review" / "handle copilot comments" / "resolve copilot feedback"
- User mentions "copilot" and "PR" or "comments" in the same context
- After PR creation when you notice Copilot has reviewed the PR
- User says "address copilot suggestions" / "deal with copilot"
- As part of the PR workflow after `pr-reviewer` skill completes
- When PR checks show Copilot has left review comments

**Invocation:** Use the Skill tool with `skill="fx-dev:copilot-feedback-resolver"`

## Processing Rules

**ONLY process UNRESOLVED comments. NEVER touch, modify, or re-process already resolved comments. Skip them entirely.**

## Core Workflow

### 1. Fetch Unresolved Copilot Threads

Query review threads using GraphQL.

**IMPORTANT:** Use inline values, NOT `$variable` syntax. The `$` character causes shell escaping issues.

```bash
# Replace OWNER, REPO, PR_NUMBER with actual values
gh api graphql -f query='
query {
  repository(owner: "OWNER", name: "REPO") {
    pullRequest(number: PR_NUMBER) {
      reviewThreads(first: 100) {
        nodes {
          id
          isResolved
          comments(first: 10) {
            nodes {
              author { login }
              body
            }
          }
        }
      }
    }
  }
}'
```

**Filter for:** `isResolved: false` AND author is Copilot (github-actions bot or copilot signature)

### 2. Categorize Each Comment

For each unresolved Copilot comment:

| Category | Indicator | Action |
|----------|-----------|--------|
| **Nitpick** | Contains `[nitpick]` prefix | Auto-resolve immediately |
| **Outdated** | Refers to code that no longer exists | Reply with explanation, resolve |
| **Incorrect** | Misunderstands project conventions | Reply with explanation, resolve, update copilot-instructions.md |
| **Valid** | Current, actionable concern | Delegate to coder sub-agent to fix |
| **Deferred** | Valid but out of scope for this PR | Track in PROJECT.md, reply, resolve |

### 3. Resolve Threads

Use GraphQL mutation to resolve.

**IMPORTANT:** Use inline values, NOT `$variable` syntax.

```bash
# Replace THREAD_ID with actual thread ID (e.g., PRRT_kwDONZ...)
gh api graphql -f query='
mutation {
  resolveReviewThread(input: {threadId: "THREAD_ID"}) {
    thread { isResolved }
  }
}'
```

### 4. Handle Each Category

#### Nitpicks (`[nitpick]` prefix)
- Resolve immediately without changes
- Optional brief acknowledgment reply

#### Outdated/Incorrect Copilot Comments

**CRITICAL: Reply directly to the Copilot review thread, NOT to the PR.**

Use GraphQL to add a reply to the specific Copilot thread.

**IMPORTANT:** Use inline values, NOT `$variable` syntax.

```bash
# Replace THREAD_ID and message with actual values
gh api graphql -f query='
mutation {
  addPullRequestReviewThreadReply(input: {
    pullRequestReviewThreadId: "PRRT_xxx",
    body: "Your explanation here"
  }) {
    comment { id }
  }
}'
```

**⛔ FORBIDDEN COMMANDS - NEVER USE:**
- `gh pr review <PR_NUMBER> --comment` - adds PR-level comments, not thread replies
- `gh pr comment` - adds PR-level comments
- Any interaction with human reviewer threads

1. Reply to the thread with professional explanation:
   - Outdated: "This comment refers to code refactored in commit abc123. The issue is no longer applicable."
   - Incorrect: "This conflicts with our [convention name] convention. [Brief explanation]. See [reference file] for project guidelines."
2. Resolve the thread using the mutation from section 3
3. **Update `.github/copilot-instructions.md`** to prevent recurrence:
   - Add to "## Code Reviews" section
   - Example: "- Do not suggest removing `.sr-only` classes - required accessibility utilities"
   - **If symlink:** Follow it and edit target file

#### Valid Concerns
1. Delegate to coder sub-agent with:
   - PR number and title
   - File and line number
   - Copilot comment text
   - Thread ID for resolution after fix
2. Ensure coder pushes changes and resolves thread

#### Deferred (Out of Scope)

**When feedback is valid but out of scope for the current PR:**

1. **Load the `fx-dev:project-management` skill** to track the follow-up work
2. **Add task to PROJECT.md** under the appropriate feature/section:
   - Read current PROJECT.md structure
   - Add a concise task describing the improvement
   - Commit the PROJECT.md update
3. **Reply to the thread** explaining the deferral:
   - "Valid suggestion. Tracked as follow-up ta