/troubleshooting-fixes

Fix PR: Troubleshooting & Known Issues

Error handling, troubleshooting guide, and known issues.

> **See Also**: [Main Command](../fix-pr.md) | [Workflow Steps](workflow-steps.md) | [Configuration](configuration-options.md)

Best Practices

Before Running

1. validate clean working directory 2. Pull latest changes from remote 3. Confirm PR is still open 4. Check for merge conflicts

During Execution

1. Review proposed fixes before applying 2. Monitor for unexpected side effects 3. Keep detailed logs of changes made 4. Verify tests still pass after each batch

After Completion

1. Push changes to remote 2. **VERIFY all threads have replies** - each addressed comment must have a response 3. **Threads auto-resolved via Phase 7** - `/resolve-threads` runs automatically 4. **POST SUMMARY COMMENT (MANDATORY)** - See Phase 6. This step is NOT optional. 5. Check CI pipeline status 6. Notify reviewers of updates 7. If any threads couldn't be resolved, document them in a PR comment

Troubleshooting

GitHub API Limits

Error: GitHub API rate limit exceeded
Solution: Wait and retry, or use --dry-run mode

Complex Review Comments

Warning: Unable to auto-generate fix for comment
Manual review required: "Consider broader architectural implications"

Merge Conflicts

Error: Fix conflicts with recent changes
Solution: Pull latest, resolve conflicts, re-run the command

Thread Resolution Failures

Review in PENDING State (Cannot Resolve Threads)

**Problem:** Thread resolution fails or threads can't be queried because the review is still in PENDING state.

**Symptoms:**

• GraphQL thread queries may return empty or incomplete data
• Thread resolution mutations fail silently
• Pre-check script detects PENDING reviews and exits

**Root Cause:** When a reviewer starts a review but hasn't submitted it (clicked "Submit review"), the review remains in PENDING state. Threads associated with pending reviews:

• May not be visible via the GraphQL API
• Cannot be resolved until the review is submitted
• Are in a draft/limbo state

**Diagnosis:**

# Check for pending reviews
gh pr view --json reviews -q '.reviews[] | {author: .author.login, state: .state}'

# If you see state: "PENDING", the review hasn't been submitted

**Solution:** 1. **If you are the reviewer:** Submit or discard your pending review in the GitHub UI 2. **If waiting on someone else:** Ask them to submit their review 3. **After review is submitted:** Re-run `/fix-pr` to process the now-resolved threads

**Prevention:**

• The pre-check in Step 6 now detects PENDING reviews and provides clear instructions
• Always verify review state before attempting thread resolution

---

Threads Not Being Commented On or Resolved

**Problem:** After running `/fix-pr`, review threads are not commented on and remain unresolved.

**Root Cause:** Step 6.3 (Thread Resolution) is documented but not being executed during workflow.

**Diagnosis:** 1. Check if TodoWrite items were created for thread resolution:

   # Look for these todos in the session:
   # - fix-pr:thread-preflight
   # - fix-pr:thread-reply
   # - fix-pr:thread-resolve
   # - fix-pr:thread-validate

2. Verify threads actually exist:

   gh api graphql -f query='...' | jq '.data.repository.pullRequest.reviewThreads.nodes | length'

**Solution:** 1. **Manual execution** - Run Step 6.3 manually from `workflow-steps.md` 2. **Use standalone command** - Run `/resolve-threads <pr-number>` as fallback 3. **Verify enforcement** - Step 6.3 now includes validation checkpoint that blocks proceeding if threads aren't resolved

**Prevention:**

• Step 6.3 now includes TodoWrite items to track execution
• Validation checkpoint prevents skipping thread resolution
• Pre-flight check confirms threads exist before attempting resolution

Validation Checkpoint Failing

**Problem:** Step 6.3 validation reports threads still unresolved after attempting to resolve them.

**Diagnosis:**

# Check which threads are still unresolved
gh api graphql -f query='...' | jq -r '.data.repository.pullRequest.reviewThreads.nodes[] | select(.isResolved == false) | "\(.path):\(.line)"'

**Common Causes:** 1. **GraphQL mutation failed silently** - Check for API errors 2. **Wrong thread ID used** - Verify using `PRRT_*` format, not numeric comment ID 3. **Permissions issue** - Token may lack `repo` scope for thread resolution 4. **Wrong mutation name** - Use `resolveReviewThread` NOT `resolvePullRequestReviewThread` (which doesn't exist)

**Solution:** 1. Re-run thread resolution with verbose output:

   gh api graphql -f query='mutation { resolveReviewThread(...) }' --include

2. Check token permissions:

   gh auth status
   # Ensure "repo" scope is granted

3. Use `/resolve-threads` command which handles errors better:

   /resolve-threads <pr-number>

Known Issues and Workarounds

Bash Command Substitution in gh Commands

**Problem:** Using `$()` substitution inside `gh api` commands causes shell syntax errors.

# WRONG - This FAILS with syntax errors
REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner)
gh api repos/$REPO/pulls/40/comments  # Breaks due to escaping issues

**Solution:** Get repo info separately, then use literal values:

# CORRECT - get info first, then use literals
gh repo view --json nameWithOwner -q .nameWithOwner
# Returns: owner/repo

# Then use the actual values directly in the query
gh api repos/owner/repo/pulls/40/comments

Wrong Mutation for Thread Replies

**Problem:** `addPullRequestReviewComment` mutation doesn't accept `pullRequestReviewThreadId`.

# WRONG - This FAILS
gh api graphql -f query='
mutation {
  addPullRequestReviewComment(input: {
    pullRequestReviewThreadId: "PRRT_xxx"  # Not a valid field!
    body: "Fixed"
  }) { comment { id } }
}'

**Solution:** Use `addPu