resolve-pr-parallel

name	resolve-pr-parallel
description	Resolve all PR comments using parallel processing, then extract reusable conventions

Resolve all PR comments using parallel processing, then extract lasting conventions from the review.

The active agent runtime should detect and understand the git context:

• Current branch detection
• Associated PR context
• All PR comments and review threads
• Can work with any PR by specifying the PR number, or ask it.

Workflow

1. Analyze

Get all unresolved comments for PR

gh pr status
gh pr view PR_NUMBER --json reviewRequests,reviews,comments
gh api repos/{owner}/{repo}/pulls/PR_NUMBER/comments

2. Plan

Create a todo/progress tool list of all unresolved items grouped by type:

• code_change — specific code fix requested
• pattern_change — applies same fix across multiple files
• architecture_feedback — structural or design-level change
• nit — style or formatting preference
• question — reviewer asking for clarification (may need code comment or doc update)

3. Implement (PARALLEL)

Spawn a general-purpose agent for each unresolved item in parallel.

So if there are 3 comments, spawn 3 agents in parallel:

1. Launch subagent general-purpose with prompt (comment1)
2. Launch subagent general-purpose with prompt (comment2)
3. Launch subagent general-purpose with prompt (comment3)

Always run all in parallel subagents for each Todo item.

For pattern_change comments: the agent MUST list every affected file, apply to ALL locations, and grep/search to confirm no instances were missed. One commit for the entire pattern change.

4. Commit & Resolve

• Commit changes
• Push to remote
• Reply to resolved threads with a brief summary of changes made

Last, check gh pr view PR_NUMBER --json comments again to see if all comments are resolved. They should be, if not, repeat the process from 1.

5. Extract Conventions

After all comments are resolved, extract reusable conventions from the review. This is the most valuable long-term output — every review comment is a signal about how this codebase/team expects things done.

5.1 Identify Conventions

For each resolved comment, determine if it reveals a reusable convention:

Is a convention if:

• Reviewer says "always do X" or "we do X this way"
• Reviewer corrects a naming pattern (implies the convention applies everywhere)
• Reviewer asks for a structural change that would apply to all similar code
• Reviewer flags a missing practice that should be standard
• The change is about consistency with existing code, not a one-off fix
• Reviewer references a team standard, style guide, or established pattern

Is NOT a convention if:

• One-off bug fix specific to this code
• Reviewer preference that contradicts established codebase patterns
• Factual correction (wrong variable name, typo)
• Removing dead code or fixing a mistake unique to this PR

5.2 Write Each Convention as a Rule

### [Convention Title]

**Source:** PR #[number], comment by @[reviewer] on [file]
**Added:** [date]

**Rule:** [Clear, specific instruction — not vague. Should be copy-pasteable into a spec.]

**Example (before):**

```[language]
[code before]
```

**Example (after):**

```[language]
[code after]
```

**Rationale:** [Why this convention exists]

5.3 Write to Layer Files

Conventions accumulate in docs/conventions/ — one file per layer, growing over time across PRs:

• docs/conventions/frontend.md — hooks, components, state, UI patterns, data fetching, forms, error handling
• docs/conventions/backend.md — routes, controllers, services, database, auth, middleware, API design, validation
• docs/conventions/general.md — project-wide: naming, DTO structure, git practices, testing strategy, file organisation

If the layer file doesn't exist: create it with category headings relevant to that layer.

If it already exists — merge and dedupe:

1. Read the existing file
2. For each new convention, check for semantic duplicates:
   • Same rule about same pattern → duplicate, skip
   • Same category but different rule → not duplicate, add
   • Same rule but better example from new PR → update existing entry, add new PR as additional source
   • Contradicts existing convention → flag to user with structured user-question tool
3. Append new conventions at the end of the correct category section
4. Preserve existing conventions exactly — don't rewrite or reorganise

Dedupe heuristic: Two conventions are duplicates if they would produce the same code change when applied to the same codebase. Compare by effect, not wording.

5.4 Commit Convention Files

git add docs/conventions/
git commit -m "docs(conventions): extract [N] conventions from PR #[number]

Layers updated: [frontend, backend, general — whichever were touched]
New conventions: [count]
Updated conventions: [count]
Duplicates skipped: [count]"

Separate commit from code changes — conventions are documentation, not code fixes.

6. Report

## PR Review Comments Addressed

**PR #[number]:** [title]
**Comments addressed:** [N] of [M] actionable
**Comments skipped:** [list with reasons, if any]

## Conventions Extracted

**New conventions:** [count]
**Updated conventions:** [count]
**Duplicates skipped:** [count]
**Layer files updated:** [list]