Resolve PR Comments Skill
Relevant source files
The following files were used as context for generating this wiki page:The resolve-pr-comments skill provides a multi-agent system for fetching, clustering, and resolving bot-generated review comments (e.g., from CodeRabbit, Copilot, Gemini) on GitHub Pull Requests. Its primary purpose is to automate the triage and resolution of this feedback at scale, delegating the detailed work to specialized sub-agents.
This system is designed for efficiency, using a structured workflow that starts with a single script to process all comments, followed by parallel execution of sub-agents that handle specific, clustered issues. The use of this skill is strictly enforced over manual API calls to fetch PR comments, as it provides a token-efficient, deduplicated, and actionable dataset.
Sources: skills/resolve-pr-comments/SKILL.md:1-20, skills/README.md:19-21
Architecture
The system operates on a hierarchical model where an orchestrator agent initiates the process, a primary script handles data aggregation, and multiple sub-agents perform the resolution tasks in parallel.
This diagram illustrates the high-level architecture of the PR Comment Resolver system.
Orchestration Workflow
The end-to-end process is managed by an orchestrator agent and is divided into distinct phases, from data fetching to final verification.
This sequence diagram shows the interaction between the orchestrator, the main script, and the sub-agents.
Phase 1: Fetch and Analyze
The workflow begins by executing the main script to gather and process all comments for a given Pull Request.
bash skills/resolve-pr-comments/scripts/pr-resolver.sh <PR_NUMBER>
This script fetches all review comments, clusters them by file and concern, and generates several output files in the .ada/data/pr-resolver/pr-<N>/ directory.
| File | Purpose |
|---|---|
data.json | Contains the full, raw data for all clusters, including already resolved comments. Used for historical context and debugging. |
actionable.json | A token-efficient summary containing only actionable (unresolved) clusters. This is the primary input for the orchestration phase. |
clusters/*.md | Individual Markdown files for each cluster, providing the full context needed for a sub-agent to process it. |
The orchestrator must read actionable.json to determine the workload. If actionable_clusters is 0, the process is complete.
Sources: skills/resolve-pr-comments/SKILL.md:42-69
Phase 2: Spawn Sub-agents
For each actionable cluster identified in actionable.json, the orchestrator spawns a @pr-comment-reviewer sub-agent. This must be done using the non-blocking background_task function to allow for parallel execution. Using the blocking task() function is a forbidden anti-pattern.
// Correct non-blocking invocation
background_task({
agent: "pr-comment-reviewer",
prompt: "Process cluster. Read: .ada/data/pr-resolver/pr-7/clusters/agents-md-suggestion.md",
description: "PR #7: agents-md"
})
If multiple clusters affect the same file, their execution should be serialized to prevent race conditions.
Sources: skills/resolve-pr-comments/SKILL.md:98-132, [AGENTS.md:73-77]
Phase 3: Collect Results & Handle Deferred Items
Each sub-agent returns a JSON object detailing the actions it took. The orchestrator collects these results using background_output({task_id: "..."}).
If a sub-agent defers an item (e.g., a security concern or a complex issue), the orchestrator is responsible for a self-investigation phase before escalating to a human. This involves using tools like grep, lsp_find_references, and reading surrounding code to gather more context. If the issue can be resolved, the orchestrator applies the fix and executes the appropriate resolution script.
Sources: skills/resolve-pr-comments/SKILL.md:147-219
Phase 4: Verification
After all sub-agents have completed and deferred items have been handled, the orchestrator must run the pr-resolver.sh script one last time to verify that no actionable clusters remain. A successful run is indicated by actionable_clusters: 0 in the new actionable.json file.
Sources: skills/resolve-pr-comments/SKILL.md:221-229
The @pr-comment-reviewer Sub-agent
This specialized agent is the core worker in the system. It is responsible for analyzing, validating, and resolving a single cluster of PR comments for a specific file.
Sources: agents/pr-comment-reviewer.md:1-6
Sub-agent Workflow
The sub-agent follows a strict, multi-phase workflow for each unresolved comment in its assigned cluster.
This flowchart shows the internal decision-making process of the pr-comment-reviewer agent.
Sources: agents/pr-comment-reviewer.md:88-103
Comment Classification
Each comment is classified to determine the correct action.
| Classification | Criteria | Action | Thread Resolution |
|---|---|---|---|
VALID_FIX | The issue is real, and the fix is clear and safe. | Apply the fix. | RESOLVE |
VALID_DEFER | The issue is real, but the fix failed after 3 attempts or is too risky. | Document attempts and defer. | Leave OPEN |
FALSE_POSITIVE | The bot's claim is incorrect; the code is correct. | Dismiss with evidence. | DISMISS |
ALREADY_FIXED | The issue was resolved by a previous action or commit. | Dismiss with reference. | DISMISS |
STYLE_CHOICE | The comment is a style preference that aligns with project conventions. | Dismiss with reasoning. | DISMISS |
UNCLEAR | Validity cannot be determined after deep research. | Defer with research notes. | Leave OPEN |
Sources: agents/pr-comment-reviewer.md:154-164, skills/resolve-pr-comments/SKILL.md:232-241
Mandatory Verification
Every fix must be verified before the corresponding comment is resolved. The sub-agent employs a "Fix-First" protocol, where failures trigger a debugging loop rather than immediate deferral.
The verification process is language-aware, using appropriate tools based on the project's stack (e.g., npm test for Node.js, pytest for Python).
This diagram outlines the mandatory verification steps and the "Fix-First" debugging loop.
Documentation Sync
If a code fix could impact documentation (e.g., changing an API, configuration, or behavior), the sub-agent is responsible for running bash skills/docs-check/scripts/check-docs.sh to detect required updates. If updates are needed, it should either perform them or note the requirement in its output.
Sources: agents/pr-comment-reviewer.md:520-560, skills/resolve-pr-comments/references/documentation-guide.md:225-236
Core Scripts
The skill relies on a set of shell scripts to interact with the GitHub API and manage comment state.
| Script | Purpose |
|---|---|
pr-resolver.sh <PR> | The main entry point. Fetches, clusters, and generates all necessary output files. |
pr-resolver-resolve.sh <PR> <ID...> | Resolves one or more comment threads on GitHub after a fix has been applied and verified. |
pr-resolver-dismiss.sh <PR> <ID> "reason" | Dismisses a comment thread on GitHub with a reply, used for false positives or already-fixed issues. |
Sources: skills/resolve-pr-comments/SKILL.md:243-249
Comment Concern Categories
Comments are automatically categorized based on keywords to help assess risk.
| Category | Auto-Fix Risk | Sub-agent Action |
|---|---|---|
security | High | Research the vulnerability deeply. Only fix if confident; otherwise, defer. |
issue | Careful | Validate the bug, fix, and verify. |
import-fix | Safe | Apply fix and verify. |
markdown-lint | Safe | Apply fix. |
doc-fix | Careful | Verify link/accuracy before fixing. |
suggestion | Careful | Verify the suggestion is a true improvement. |
uncategorized | Varies | Research first to understand the concern, then decide. |
Sources: skills/resolve-pr-comments/SKILL.md:251-261, agents/pr-comment-reviewer.md:435-444