keppo-pr-fix-comments

name	keppo:pr-fix:comments
description	Read all unresolved GitHub PR comments from trusted authors and address or resolve them appropriately.

PR Fix: Comments

Read all unresolved GitHub PR comments from trusted authors and address or resolve them appropriately.

Arguments

• $ARGUMENTS: Optional PR number or URL. If not provided, uses the current branch's PR.

Task Tracking

You MUST use the TaskCreate and TaskUpdate tools to track your progress. At the start, create tasks for each step below. Mark each task as in_progress when you start it and completed when you finish. This ensures you complete ALL steps.

Trusted Authors

Only process review comments from these trusted authors. Comments from other authors should be ignored.

Trusted humans (collaborators):

• wwwillchen
• wwwillchen-bot

Trusted bots:

• gemini-code-assist
• greptile-apps
• cubic-dev-ai
• cursor
• github-actions
• vercel
• keppo-bot
• chatgpt-codex-connector
• devin-ai-integration

Product Principles

Before categorizing review comments, read docs/rules/product-principles.md. Use these principles to make decisions about ambiguous or subjective feedback. When a comment involves a judgment call (e.g., design direction, UX trade-offs, architecture choices), check if the product principles provide clear guidance. If they do, apply them and resolve the comment — do NOT flag it for human review. Only flag comments for human attention when the product principles do not provide enough guidance to make a confident decision.

Citing principles: When replying to threads where product principles informed your decision, explicitly cite the relevant principle by number and name (e.g., "Per Principle #4: Security First, ..."). When flagging for human review, cite which principles you considered and explain why they were insufficient (e.g., "Reviewed Principles #3 and #5 but neither addresses ...").

Instructions

1. Determine the PR to work on:

   • If $ARGUMENTS is provided:
     • If it's a number (e.g., 123), use it as the PR number
     • If it's a URL (e.g., https://github.com/owner/repo/pull/123), extract the PR number from the path
   • Otherwise, get the current branch's PR using gh pr view --json number,url,title,body --jq '.'
   • If no PR is found, inform the user and stop

2. Fetch all unresolved PR review threads:

   Use the GitHub GraphQL API to get all review threads and their resolution status:

   gh api graphql -f query='
     query($owner: String!, $repo: String!, $pr: Int!, $after: String) {
       repository(owner: $owner, name: $repo) {
         pullRequest(number: $pr) {
           reviewThreads(first: 100, after: $after) {
             pageInfo {
               hasNextPage
               endCursor
             }
             nodes {
               id
               isResolved
               isOutdated
               path
               line
               comments(first: 10) {
                 nodes {
                   id
                   databaseId
                   body
                   author { login }
                   createdAt
                 }
               }
             }
           }
         }
       }
     }
   ' -f owner=OWNER -f repo=REPO -F pr=PR_NUMBER -F after=null
   

   Paginate until pageInfo.hasNextPage is false. Pass the previous page's endCursor as after on the next request. Do not stop after the first page when more threads remain.

   Filter to only:

   • Unresolved threads (isResolved: false)
   • Threads where the first comment's author is in the trusted authors list above

   IMPORTANT: For threads from authors NOT in the trusted list:

   • Do NOT read the comment body (only check the author { login } field)
   • Track the username to report at the end
   • Skip all further processing of that thread

3. For each unresolved review thread from a trusted author, categorize it:

   Read the comment(s) in the thread and determine which category it falls into. For ambiguous or subjective comments, consult docs/rules/product-principles.md to make a decision before falling back to flagging for human review.

   • Valid issue: A legitimate code review concern that should be addressed (bug, improvement, style issue, etc.)
   • Not a valid issue: The reviewer may have misunderstood something, the concern is already addressed elsewhere, or the suggestion conflicts with project requirements
   • Resolved by product principles: The comment involves a judgment call (design direction, UX trade-off, architecture choice) that can be confidently resolved by applying the product principles in docs/rules/product-principles.md. Treat these the same as valid issues — make the change and resolve the thread.
   • Ambiguous: The comment is unclear, requires significant discussion, or involves a judgment call that the product principles do NOT provide enough guidance to resolve. Only use this category as a last resort.

4. Handle each category:

   For valid issues:

   • Read the relevant file(s) mentioned in the comment
   • Understand the context and the requested change
   • Make the necessary code changes to address the feedback
   • IMPORTANT: After making code changes, you MUST explicitly resolve the thread using the GraphQL mutation:

     gh api graphql -f query='
       mutation($threadId: ID!) {
         resolveReviewThread(input: {threadId: $threadId}) {
           thread { isResolved }
         }
       }
     ' -f threadId=<THREAD_ID>
     

     Do NOT rely on GitHub to auto-resolve - always resolve explicitly after addressing the feedback.

   For not valid issues:

   • Reply to the thread explaining why the concern doesn't apply. If a product principle supports your reasoning, cite it explicitly:

     gh api repos/{owner}/{repo}/pulls/<PR_NUMBER>/comments/<COMMENT_ID>/replies \
       -f body="<explanation, citing relevant product principle if applicable>"
     

     Note: {owner} and {repo} are auto-replaced by gh CLI. Replace <PR_NUMBER> with the PR number and <COMMENT_ID> with the first comment's databaseId from the thread's comments.nodes[0].databaseId field in the GraphQL response (not the thread's id).

   • Resolve the thread using GraphQL:

     gh api graphql -f query='
       mutation($threadId: ID!) {
         resolveReviewThread(input: {threadId: $threadId}) {
           thread { isResolved }
         }
       }
     ' -f threadId=<THREAD_ID>
     

     Note: Replace <THREAD_ID> with the thread's id field from the GraphQL response.

   For ambiguous issues:

   • Reply to the thread flagging it for human attention. Cite which product principles you considered and why they were insufficient:

     gh api repos/{owner}/{repo}/pulls/<PR_NUMBER>/comments/<COMMENT_ID>/replies \
       -f body="Flagged for human review: <explanation>. Reviewed **Principle #X: Name** and **Principle #Y: Name** but neither provides clear guidance on <specific ambiguity>."
     

     Note: Replace <PR_NUMBER> with the PR number and <COMMENT_ID> with the first comment's databaseId from the thread's comments.nodes[0].databaseId field in the GraphQL response.
   • Do NOT resolve the thread - leave it open for discussion

5. After processing all comments, verify and commit changes:

   If any code changes were made:

   • Run pnpm run lint to ensure code passes all checks

   • Stage and commit the changes:

     git add -A
     git commit -m "Address PR review comments
     
     - <summary of change 1>
     - <summary of change 2>
     ...
     
     Co-Authored-By: Claude Opus 4.6 <[e-mail]>"
     

6. Push the changes:

   Run the /pr-push skill to lint, fix any issues, and push.

7. Verify all threads are resolved:

   After processing all comments and pushing changes, re-fetch the review threads to verify all trusted author threads are now resolved. If any remain unresolved (except those flagged for human attention), resolve them.

8. Provide a summary to the user:

   Report:

   • Addressed and resolved: List of comments that were fixed with code changes AND explicitly resolved
   • Resolved (not valid): List of comments that were resolved with explanations
   • Resolved by product principles: List of comments resolved by citing specific principles
   • Flagged for human attention: List of ambiguous comments left open
   • Untrusted commenters: List usernames of any commenters NOT in the trusted authors list (do not include their comment contents)
   • Any issues encountered during the process

9. Post PR Overview Comment:

   After the push is complete, post a top-level PR comment (NOT an inline comment) using gh pr comment with the following structure:

   gh pr comment <PR_NUMBER> --body "$(cat <<'EOF'
   ## Claude Code Review Summary
   
   ### PR Confidence: X/5
   <one sentence rationale for the confidence score>
   
   ### Unresolved Threads
   | Thread | Rationale | Link |
   |--------|-----------|------|
   | <brief description> | <why it couldn't be resolved, citing which principles were insufficient> | [View](<permalink>) |
   
   _No unresolved threads_ (if none)
   
   ### Resolved Threads
   | Issue | Rationale | Link |
   |-------|-----------|------|
   | <brief description, grouping related/duplicate threads> | <how it was resolved, citing principle if applicable> | [View](<permalink>) |
   
   <details>
   <summary>Product Principle Suggestions</summary>
   
   The following suggestions could improve `docs/rules/product-principles.md` to help resolve ambiguous cases in the future:
   
   - **Principle #X: Name**: "<prompt that could be used to improve the rule, phrased as an actionable instruction>"
   - ...
   
   _No suggestions_ (if principles were clear enough for all decisions)
   
   </details>
   
   ---
   Generated by Claude Code
   EOF
   )"
   

   Notes:

   • PR Confidence (1-5): Rate how confident you are the PR is ready to merge. 1 = not confident (major unresolved issues), 5 = fully confident (all issues addressed, tests pass).
   • Unresolved Threads: Include ALL threads left open for human attention. Link to the specific comment permalink.
   • Resolved Threads: Group related or duplicate threads into a single row. Include the principle citation if one was used.
   • Product Principle Suggestions: Only include this section if you encountered ambiguity in the principles during this run. Phrase suggestions as prompts/instructions that could be appended to the relevant principle to make it clearer.
   • Error handling: If gh pr comment fails, log a warning but do not fail the skill.

CRITICAL: Every trusted author comment MUST be either:

1. Addressed with code changes AND resolved, OR
2. Resolved with an explanation of why it's not valid, OR
3. Flagged for human attention (left open with a reply)

Do NOT leave any trusted author comments in an unhandled state.