pr-fix

PR Fix Skill

Purpose

Full triage, fix, and pre-flight for a PR. Diagnoses all issues (merge conflicts, CI failures, bot comments, review requests), fixes them, enforces /pre-commit before pushing, then hands off to /pr-merge for the actual merge and post-merge workflow.

Usage

/pr-fix <pr-number>

Relationship with other skills:

• /pr-fix = triage problems + fix them + pre-flight validation (you stay on the PR branch)
• /pr-merge = validate readiness + execute merge + post-merge workflow (docs, milestone, release)
• Use /pr-fix first when you know there are issues. Use /pr-merge when you expect the PR is ready.

Phase 1: Full Triage

Checkout the PR branch first:

gh pr checkout <pr-number>

Then run ALL four sources in parallel:

REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner)
PR=<pr-number>

# 1. PR metadata — mergeability, draft state, review decision
gh pr view $PR --json mergeable,isDraft,state,reviewDecision,additions,deletions

# 2. CI check status
gh pr checks $PR --repo $REPO

# 3. Bot inline comments (Codex, Gemini, etc.)
gh api repos/$REPO/pulls/$PR/comments \
  --jq '.[] | "[\(.path):\(.line // .original_line // "?")]\n\(.body)\n---"'

# 4. Top-level reviews (approval/request-changes state)
gh pr view $PR --repo $REPO --json reviews \
  --jq '.reviews[] | "\(.author.login) [\(.state)]: \(.body)"'

# 5. Forgejo CI status (if dual-remote)
  SHA=$(gh pr view $PR --json headRefOid --jq '.headRefOid')
fi

If bot reviews are still pending, poll until complete (max 3 attempts, 30s apart):

for i in 1 2 3; do
  STATE=$(gh pr checks $PR --repo $REPO 2>&1)
  echo "$STATE"
  echo "$STATE" | grep -q "pending" && sleep 30 || break
done

Phase 2: Triage Decision

Hard Stops — Report and Exit

Condition	Action
mergeable: CONFLICTING	"Merge conflicts detected. Resolve first: gh api -X PUT repos/O/R/pulls/N/update-branch or rebase locally, then re-run /pr-fix."
isDraft: true	"PR is a draft. Mark as ready for review first."
state != OPEN	"PR is not open (state: X). Nothing to fix."

Soft Issues — Proceed to Fix Loop

Condition	Route
CI failing	→ Phase 3 fix loop
Bot comments (P1/P2)	→ Phase 3 fix loop
CHANGES_REQUESTED	→ Phase 3 fix loop (address review comments)
REVIEW_REQUIRED (zero reviews)	Note it — addressed at Phase 6 handoff
All passing, no issues	Skip Phase 3 → go directly to Phase 4 pre-flight

Phase 3: Fix Loop

Fix one category at a time. Verify locally after each fix before moving to the next.

Common Fix Patterns

Build/Dependency Issues:

rm -rf node_modules package-lock.json || rm -rf __pycache__ .pytest_cache
npm ci || pip install -r requirements.txt
npm run build || python -m build

Test Failures:

npm run test -- --verbose || pytest -v --tb=short -m "not integration and not e2e"
npm run test:integration || pytest tests/integration/  # CI runs full suite; run locally only if diagnosing integration failures

Code Quality Issues:

npm run lint -- --fix || ruff format . && ruff check --fix .
npm run format || prettier --write .
npm run typecheck || mypy .

Security Issues:

npm audit fix || safety check && pip-audit --fix
npx audit-ci --moderate || bandit -r src/

Implementation by Failure Type

Test Failures:

• Unit tests: Fix broken logic, update mocks, handle edge cases
• Integration tests: Update API contracts, fix database setup
• Security tests: Address input validation, auth issues

Quality Issues:

• TypeScript: Fix type errors, add missing types
• Linting: Address code style violations
• Documentation: Update JSDoc, README, API docs

Bot Review Comments (Codex P1/P2, Gemini):

• Address each inline comment with its file:line reference
• Prioritize P1 (blocking) before P2 (advisory)

Human Review (CHANGES_REQUESTED):

• Address all requested changes before proceeding
• Reply to review comments after fixing

Quick Reference by Stack

JavaScript/TypeScript:

npm audit fix && npm run build
npm run test -- --updateSnapshot
npm run test:coverage -- --coverageThreshold='{"global":{"branches":80}}'
npx eslint . --fix && npx prettier --write .
npx tsc --noEmit

Python:

pip install -r requirements.txt && safety check
pytest -m "not integration and not e2e"  # coverage threshold enforced on CI, not locally
ruff format . && ruff check --fix . && mypy src/

Docker/Infrastructure:

docker build -t test-image .
terraform validate && terraform plan

Phase 4: Pre-flight Before Push (MANDATORY)

Always run /pre-commit before pushing any fix to the PR. This enforces the same checks CI will run — catching failures locally before they hit the pipeline and breaking the push→CI-fail→fix→repeat cycle.

/pre-commit

Runs: quality check → tests → coverage → security scan → changelog → companion gate.

For large diffs (additions + deletions > 200 lines), also run first:

/review changes --quick

External AI second opinion on the code changes. Address any BLOCK-level findings before pushing. --quick skips the deeper audits (silent-failures, types, comments) for speed.

Do not proceed to Phase 5 until /pre-commit passes.

Phase 5: Push + Monitor

git add .
git commit -m "fix(pr): resolve PR #<pr-number> issues

- Fixed: [specific issue description]
- Tests: [test fixes applied if any]
- Security: [security issues resolved if any]"

git push

# Monitor GitHub CI
gh pr checks <pr-number> --watch

# Monitor Forgejo CI (dual-remote projects)
  SHA=$(git rev-parse HEAD)
  TOKEN=$(cat ~/.config/forgejo/token)
  sleep 60
  for i in 1 2 3; do
    RESULT=$(curl -s \
      -H "Authorization: token $TOKEN")
    STATE=$(echo "$RESULT" | python3 -c "import json,sys; print(json.load(sys.stdin)['state'])" 2>/dev/null)
    echo "Forgejo CI: $STATE (attempt $i)"
    [ "$STATE" = "pending" ] && sleep 30 || break
  done
  echo "$RESULT" | python3 -c "
import json,sys; d=json.load(sys.stdin)
print(f'Forgejo CI: {d[\"state\"]} ({d[\"total_count\"]} checks)')
for s in (d.get('statuses') or []):
    print(f'  {s[\"context\"]}: {s[\"status\"]}')
"
  # If Forgejo CI failed, loop back to Phase 3
  [ "$STATE" = "failure" ] && echo "FORGEJO CI FAILED — return to Phase 3 fix loop"
fi

# Re-check bot reviews after pushing fixes
gh api repos/$REPO/pulls/<pr-number>/comments \
  --jq '.[] | "[\(.path):\(.line // .original_line // "?")]\n\(.body)\n---"'

Phase 6: Handoff

If REVIEW_REQUIRED (no human reviews on this PR):

PR has no reviews yet. Consider getting a second opinion before requesting merge:

  /review pr <N>   — external AI review (MERGE/BLOCK verdict, ~5 min)

Then run the merge orchestrator:

  /pr-merge <N>

If all checks passing and reviews satisfied:

All issues resolved. Run the merge orchestrator:

  /pr-merge <N>

/pr-merge owns the merge decision, branch cleanup, milestone check, and release readiness. Do not auto-merge here.

Tips

• Fix one category at a time (CI, then lint, then security)
• Verify fixes locally before running pre-flight
• /pre-commit is mandatory — it prevents the push→CI-fail→fix→repeat cycle
• Use gh pr checks --watch to monitor CI progress after push