edercnj/x-fix-pr

Skill: Fix PR Comments

Purpose

Automates the process of addressing PR review comments for {{PROJECT_NAME}}. Reads all review comments from a pull request, classifies them by type, implements fixes for actionable feedback, and validates CI status before finishing.

Triggers

• /x-fix-pr — fix comments on current branch's PR
• /x-fix-pr 123 — fix comments on PR #123

Parameters

| Parameter | Required | Description | |-----------|----------|-------------| | PR-number | No | PR number to process. If omitted, detect from current branch. |

Workflow

1. DETECT     -> Identify PR (argument or branch)
2. FETCH      -> Get all review comments via GitHub CLI
3. CLASSIFY   -> Categorize each comment (actionable/suggestion/question/praise/resolved)
4. FIX        -> Implement fixes for actionable comments
5. VERIFY     -> Compile and test after each fix
6. REPLY      -> Reply to each comment thread in PT-BR (fix summary or rejection reason)
7. COMMIT     -> Commit with conventional commit message
8. CI_WATCH   -> Run x-watch-pr-ci and loop remediation when checks are not green
9. REPORT     -> Summarize actions taken
10. REMEDIATION-> Update remediation tracker, specialist reports, and dashboard with Fixed status

Step 1 — Detect PR

Determine which PR to process:

# If argument is a number, use it directly
PR_NUMBER=$1

# If no argument, detect from current branch
if [ -z "$PR_NUMBER" ]; then
  gh pr view --json number --jq '.number'
fi

If no PR found, abort: No PR found for current branch. Provide a PR number as argument.

Step 2 — Fetch Review Comments

# Get all review comments (not issue comments)
gh api repos/{owner}/{repo}/pulls/{PR_NUMBER}/comments \
  --jq '.[] | {id: .id, path: .path, line: .line, body: .body, user: .user.login, created_at: .created_at}'

# Also get PR review threads for context
gh api repos/{owner}/{repo}/pulls/{PR_NUMBER}/reviews \
  --jq '.[] | {id: .id, state: .state, body: .body, user: .user.login}'

Step 3 — Classify Comments

For each comment, classify into one of:

| Type | Description | Action | |------|-------------|--------| | Actionable | Clear request to change code (fix bug, rename, refactor) | Implement the fix | | Suggestion | Optional improvement with rationale | Implement if aligns with project standards | | Question | Reviewer asking for clarification | Skip (requires human response) | | Praise | Positive feedback | Skip | | Resolved | Already addressed or outdated | Skip |

Classification rules:

• Contains "please change", "should be", "must", "fix", "bug", "wrong" — Actionable
• Contains "consider", "maybe", "could", "suggestion", "nit" — Suggestion
• Contains "?", "why", "what", "how does" — Question
• Contains "LGTM", "nice", "good", "great" — Praise
• Thread is marked as resolved — Resolved

Step 4 — Implement Fixes

For each actionable/suggestion comment:

1. Read the file at the specified path and line:

   # Comment metadata provides path and line
   cat -n {path} | sed -n '{line-5},{line+5}p'
   

2. Understand the reviewer's request

3. Implement the fix using Edit tool

4. If the fix requires understanding broader context, read surrounding code first

Ordering: Process comments file-by-file to minimize context switching. Within a file, process top-to-bottom to avoid line number shifts.

Step 5 — Verify

After each fix (or batch of fixes per file):

{{COMPILE_COMMAND}}
{{TEST_COMMAND}}

If compilation fails, revert the last change and try an alternative approach. If tests fail, analyze the failure and adjust the fix.

Step 6 — Reply to Comments (PT-BR)

After each comment is processed (fixed, skipped, or rejected), reply to the review comment thread in Portuguese (pt-BR) explaining the action taken.

Reply command:

# Reply to an inline review comment thread
gh api repos/{owner}/{repo}/pulls/{PR_NUMBER}/comments/{comment_id}/replies \
  -f body="{message_in_portuguese}"

Reply templates by classification:

| Classification | Reply Template (PT-BR) | |---------------|----------------------| | Actionable (fixed) | Corrigido. {descricao da alteracao feita}. Commit: {short_hash} | | Suggestion (accepted) | Sugestao aceita. {descricao da alteracao feita}. Commit: {short_hash} | | Suggestion (rejected) | Sugestao analisada, mas nao aplicada. Motivo: {razao tecnica pela qual nao faz sentido no contexto atual} | | Actionable (rejected) | Observacao analisada, mas nao faz sentido neste contexto. Motivo: {explicacao tecnica detalhada} | | Actionable (failed) | Tentei corrigir, mas a alteracao causou falha na compilacao/testes. Necessita intervencao manual. | | Question | (no reply — requires human response) | | Praise | (no reply) | | Resolved | (no reply — already resolved) |

Rules:

• ALL replies MUST be in Portuguese (pt-BR)
• Be specific: describe exactly what was changed and why
• When rejecting, provide technical justification (reference project rules, architecture constraints, or coding standards)
• Include commit hash when a fix was applied
• Never reply to praise or already-resolved comments

Examples:

Fix applied:

Corrigido. Renomeei a variavel `d` para `elapsedTimeInMs` conforme padrao de naming do projeto. Commit: abc1234

Suggestion rejected:

Sugestao analisada, mas nao aplicada. Motivo: o metodo precisa ser publico porque implementa a interface Assembler, que define o contrato do pipeline. Tornar package-private quebraria o polimorfismo.

Comment doesn't make sense:

Observacao analisada, mas nao faz sentido neste contexto. Motivo: o null check sugerido e desnecessario aqui — o parametro vem de um Optional.orElseThrow() na linha 42, garantindo que nunca sera null neste ponto.

Step 7 — Commit

After all fixes for a logical group are verified:

git add {modified-files}
git commit -m "fix({scope}): address PR review comments

- {summary of change 1}
- {summary of change 2}

Addresses review comments on PR #{PR_NUMBER}"

Scope should match the module/layer affected (e.g., domain, api, config).

Step 8 — CI Watch (MANDATORY)

After pushing the fix commit(s), the skill MUST validate the PR pipeline:

Skill(skill: "x-watch-pr-ci", args: "--pr-number {PR_NUMBER}")

Decision policy:

• SUCCESS (exit 0) or PR_ALREADY_MERGED (exit 40): proceed.
• CI_FAILED (20), TIMEOUT (30), or CI_PENDING_PROCEED (10): return to Step 2 (FETCH) and run another fix cycle.

Use up to 3 cycles (FETCH -> CLASSIFY -> FIX -> VERIFY -> REPLY -> COMMIT -> CI_WATCH) per invocation. If the third cycle still does not converge to green CI, stop with explicit failure summary.

When analyzing checks[] from x-watch-pr-ci, prioritize actionable failures from SonarQube and Veracode jobs when present.

Step 9 — Report

Output a summary table:

## PR Review Comments — Fix Report

**PR:** #{PR_NUMBER}
**Total comments:** N
**Processed:** M

| # | File | Line | Type | Action | Status | Reply |
|---|------|------|------|--------|--------|-------|
| 1 | src/main/Foo.java | 42 | Actionable | Renamed variable | Fixed | Replied |
| 2 | src/main/Bar.java | 15 | Suggestion | Added null check | Fixed | Replied |
| 3 | src/main/Baz.java | 20 | Actionable | — | Rejected | Replied |
| 4 | src/main/Baz.java | 88 | Question | — | Skipped | — |
| 5 | src/main/Qux.java | 3 | Praise | — | Skipped | — |

### Questions Requiring Human Response

- **src/main/Baz.java:88** (@reviewer): "Why is this method public?"

Step 10 — Update Remediation Reports

After Step 9, propagate fix status back to the review artifacts so all reports stay in sync.

10.1 — Detect Story Context

Determine story ID from the PR branch name:

gh pr view {PR_NUMBER} --json headRefName --jq '.headRefName'
# Expected pattern: story-XXXX-YYYY or feature/story-XXXX-YYYY

Extract story ID (pattern story-\d{4}-\d{4}). If no story ID can be extracted, log warning No story ID found for PR #{PR_NUMBER}. Skipping remediation tracker update. and exit Step 10 gracefully (no abort).

Derive paths:

• FEATURE_DIR = .aikittools/features/feature-XXXX/reviews/
• REMEDIATION_FILE = {FEATURE_DIR}remediation-story-XXXX-YYYY.md
• DASHBOARD_FILE = {FEATURE_DIR}dashboard-story-XXXX-YYYY.md

10.2 — Match Fixed Comments to Findings

For each comment marked Fixed in the Step 9 report:

1. Build a search phrase from the comment body: extract the first 8+ meaningful words, removing code fences, markdown formatting, and action prefixes such as "Fix:", "Bug:", "Please:".
2. Read REMEDIATION_FILE. Search the Description column of each finding row:
   • Primary match: Description contains ≥ 6 consecutive words from the search phrase (case-insensitive).
   • Fallback match: Description contains the file path from the comment metadata (e.g., path/to/File.java).
3. Record matched finding IDs (e.g., FIND-001).

10.3 — Update Remediation Tracker

For each matched finding (only when current status is Open):

1. Update Status column: Open → Fixed.
2. Update Fix Commit SHA column with the short commit hash from Step 7.
3. Recompute Remediation Summary counts (Open, Fixed, Deferred, Accepted, Total).

Write(file_path: "{REMEDIATION_FILE}", content: "{updated_content}")

Idempotency: If Status is already Fixed, Deferred, or Accepted, skip — do NOT overwrite.

10.4 — Update Individual Specialist Reports

For each matched finding, identify which specialist reported it (Engineer column in the remediation tracker). Open the corresponding report:

• If Engineer is a specialist name (QA, Security, Performance, etc.): open .aikittools/features/feature-XXXX/reviews/review-{specialist}-story-XXXX-YYYY.md
• If Engineer is Tech Lead: open .aikittools/features/feature-XXXX/reviews/review-tech-lead-story-XXXX-YYYY.md

Locate the finding row in the "Failed Items" table (match by Description ≥ 6 words) and update:

• Status column → Fixed
• Fix Commit column → short commit hash

Edit(file_path: "{specialist_or_tech_lead_report}", ...)

Skip if report does not exist or the "Failed Items" table has no Status column (report generated before template v1.1 was applied).

10.5 — Update Consolidated Dashboard

If DASHBOARD_FILE exists:

1. Read the dashboard.
2. In the Critical Issues Summary table, update the Status column for matched findings: Open → Fixed.
3. Recompute the Remediation Status section counts.

Edit(file_path: "{DASHBOARD_FILE}", ...)

10.6 — Commit Artifact Updates

After all review artifact writes/edits (Steps 10.3–10.5), commit the changes so the updated Fixed statuses persist in the branch:

git add \
  ".aikittools/features/feature-XXXX/reviews/remediation-story-XXXX-YYYY.md" \
  ".aikittools/features/feature-XXXX/reviews/dashboard-story-XXXX-YYYY.md" \
  ".aikittools/features/feature-XXXX/reviews/review-*.md"
git commit -m "chore(review): mark {FIXED_COUNT} finding(s) as Fixed in review artifacts

Addresses remediation tracking for PR #{PR_NUMBER}.

Co-authored-by: Copilot <[email protected]>"

Skip this commit if no review artifact files were actually modified (idempotent guard).

10.7 — Console Summary

After all updates, output:

Remediation tracker updated: {FIXED_COUNT} finding(s) marked Fixed.
Dashboard updated: {DASHBOARD_FILE}
Specialist reports updated: {UPDATED_SPECIALISTS}

If no remediation file was found: Remediation tracker not found — skipped.

Step 11 — Re-trigger Full Review Pipeline

After all fixes are applied and remediation artifacts updated (Steps 10.1–10.7), re-trigger the full review pipeline to validate that all issues are now resolved:

Skill(skill: "x-review-pr", args: "{PR_NUMBER} --no-auto-remediation [--agent {agent_name}]")

Decision policy:

• If x-review-pr returns GO: x-fix-pr finishes successfully with summary.
• If x-review-pr returns GO-WITH-RESERVATIONS: x-fix-pr finishes with a warning listing the reservations.
• If x-review-pr returns NO-GO: x-fix-pr records the NO-GO verdict and exits with a non-zero status code so the calling orchestrator (e.g., x-review-pr Phase 4 remediation loop) can decide whether to retry.

Important: The maximum cycle count is controlled by the calling x-review-pr Phase 4 loop. x-fix-pr itself does NOT loop — it defers to the parent orchestrator for cycle management.

11.1 — Console Summary

After Step 11, output:

=== Fix PR Summary ===
PR: #{PR_NUMBER}
Comments fixed: {FIXED_COUNT}
Comments skipped/rejected: {SKIPPED_COUNT}
Review pipeline result: {GO | GO-WITH-RESERVATIONS | NO-GO}
─────────────────────────────────────────────────────────────
{if NO-GO}
Remaining issues (see review reports):
  - [SPECIALIST/DEVELOPER]: {FAILED_ITEM} [{SEVERITY}]
  ...

Error Handling

| Scenario | Action | |----------|--------| | PR not found | Abort with message | | No comments on PR | Report "No review comments found" | | Comment references deleted file | Skip with warning | | Fix causes compilation failure | Revert and report as "Unable to fix automatically" | | Fix causes test failure | Revert and report as "Fix caused regression" | | CI watch fails after 3 cycles | Abort with "CI not green after max remediation cycles" | | API rate limit | Wait and retry (max 3 attempts) | | Story ID not extractable from branch name | Log warning; skip Step 10 gracefully (no abort) | | Remediation tracker not found | Log warning; skip Steps 10.2–10.5 gracefully (no abort) | | Finding match not found in tracker | Log WARNING: no matching finding for comment #{comment_id} and continue | | x-review-pr returns NO-GO after fixes | Exit non-zero; surface NO-GO verdict to calling orchestrator |

Integration Notes

| Skill | Relationship | Context | |-------|-------------|---------| | x-implement-story | called-by | Invoked during Phase 4 (fix review comments) | | x-watch-pr-ci | calls | Polls CI checks and Copilot review before finishing each remediation cycle | | x-push-branch | calls | Uses Conventional Commits format for fix commits | | x-review-pr | calls (Step 11) | Re-triggers full review pipeline after fixes to validate resolution | | x-review-specialist | reads | Processes comments produced by specialist reviews | | _TEMPLATE-REVIEW-REMEDIATION.md | updates (Step 10.3) | Marks findings Fixed with commit SHA | | _TEMPLATE-CONSOLIDATED-REVIEW-DASHBOARD.md | updates (Step 10.5) | Keeps Remediation Status in sync |