fix-pr

name	fix-pr
description	Dùng khi user runs `/fix-pr <PR-number>` sau khi `/check-pr` flagged issues. Determines fix strategy (Case A: PR open → amend on branch; Case B: merged → follow-up PR), then addresses brainstorm/test/doc/methodology gaps.
disable-model-invocation	true

Fix PR Quality Issues

Portable workflow skill — adapt {module} placeholders + project doc paths.

Usage: /fix-pr <PR-number>

Example: /fix-pr 95

Prerequisite: Run /check-pr <number> first to identify issues

---

Instructions

Khi user invoke /fix-pr $ARGUMENTS:

Bước 1: Get PR Status & Check Results

# Check if PR is merged
gh pr view $ARGUMENTS --json state,mergedAt,headRefName

# Get the check-pr results (from previous run or re-run)

Bước 2: Determine Fix Strategy

Case A: PR Still Open (chưa merge)

Strategy: Sửa trực tiếp trên branch

# Checkout PR branch
gh pr checkout $ARGUMENTS

# Or if local branch exists
git checkout <branch-name>

Actions:

1. Bổ sung artifacts thiếu (brainstorm, breakdown)
2. Thêm tests nếu thiếu
3. Update PR description
4. Amend commits nếu cần (chưa push)
5. Push updates

Case B: PR Already Merged

Strategy: Tạo follow-up PR

# Create follow-up branch
git checkout main
git pull origin main
git checkout -b fix/PR-$ARGUMENTS-quality-improvements

Actions:

1. Tạo documentation cho methodology gaps
2. Thêm tests còn thiếu
3. Tạo PR mới với reference đến PR gốc

---

Bước 3: Fix Each Category

Fix 1: Brainstorm Gaps

Nếu thiếu brainstorm:

## Retroactive Brainstorm: PR-$ARGUMENTS

> Note: This brainstorm was created retroactively to document design decisions.

### Scope
[Analyze from PR changes - what was actually built]

### Risks Identified (Post-hoc)
[What risks existed, were they handled?]

### Edge Cases
[What edge cases exist in the implementation?]

### Alternatives Considered
[What other approaches could have been taken?]

### Decision Rationale
[Why was this approach chosen?]

Output location:

• PR chưa merge → Update PR description
• PR đã merge → Add to project docs (vd documents/) or follow-up PR description

Fix 2: Task Breakdown Gaps

Nếu thiếu breakdown:

## Retroactive Task Breakdown: PR-$ARGUMENTS

> Note: This breakdown was created retroactively.

### Tasks Completed

| # | Task | Actual Time | Type |
|---|------|-------------|------|
| 1 | [Infer from commits] | ~X min | Test/Code |
| 2 | [Infer from commits] | ~X min | Test/Code |

### Lessons for Future
- [What should have been planned differently]

Fix 3: TDD Gaps

Nếu tests thiếu hoặc sai order:

Option A: Add missing tests (recommended)

# Create test files for untested code
# Follow existing test patterns in codebase

Option B: Document why tests not needed

## Test Coverage Note: PR-$ARGUMENTS

**Files without tests:**
- `file1.ts` - Config only, no logic
- `file2.ts` - [Reason]

**Existing coverage:**
- [Related test files that cover this code]

Fix 4: Code Review Gaps

Nếu thiếu review evidence:

## Retroactive Code Review: PR-$ARGUMENTS

### Self-Review Checklist
- [x] Code follows project conventions
- [x] No security vulnerabilities
- [x] Error handling adequate
- [x] Performance acceptable
- [ ] [Items that should be improved]

### Test Plan (Retroactive)
- [x] [Test that was run]
- [x] [Test that was run]

### Notes
[Any issues found during retroactive review]

---

Bước 4: Handle Dependencies

Khi fix ảnh hưởng PR khác

Detect Dependencies:

# Find PRs that depend on this one
gh pr list --search "base:main" --json number,title,body | jq '.[] | select(.body | contains("PR-$ARGUMENTS"))'

# Find PRs this one depends on
# (Check PR description for references)

Dependency Matrix:

## Dependency Analysis: PR-$ARGUMENTS

### This PR depends on:
| PR | Status | Impact |
|----|--------|--------|
| #X | Merged | None - already integrated |
| #Y | Open | Must merge first |

### PRs that depend on this:
| PR | Status | Impact of Fix |
|----|--------|---------------|
| #A | Open | Need to rebase after fix |
| #B | Merged | May need follow-up fix |

### Recommended Fix Order:
1. Fix PR-$ARGUMENTS first
2. Then update PR-#A (rebase)
3. Create follow-up for PR-#B if needed

Actions based on dependencies:

1. No dependencies → Fix directly
2. Depends on open PR → Wait or coordinate
3. Other PRs depend on this →
   • Notify in those PRs
   • Create issues for follow-up fixes
   • Update dependency documentation

---

Bước 5: Execute Fix

For Open PRs:

# 1. Checkout branch
gh pr checkout $ARGUMENTS

# 2. Make fixes
# [Add tests, update docs, etc.]

# 3. Commit fixes
git add .
git commit -m "fix(quality): Add missing methodology artifacts for PR-$ARGUMENTS

Changes:
- Add retroactive brainstorm documentation
- Add missing test coverage
- Update PR description with task breakdown"

# 4. Push
git push origin <branch>

# 5. Update PR description
gh pr edit $ARGUMENTS --body "$(cat <<'EOF'
[Updated PR description with methodology artifacts]
EOF
)"

For Merged PRs:

# 1. Create follow-up branch
git checkout -b fix/PR-$ARGUMENTS-quality

# 2. Add missing artifacts
# - Tests
# - Documentation
# - Any code improvements identified

# 3. Commit
git add .
git commit -m "fix(quality): Add missing artifacts for PR-$ARGUMENTS

Retroactive quality improvements:
- Add tests for [feature]
- Document design decisions

Follows up on PR #$ARGUMENTS."

# 4. Create PR
gh pr create --title "fix(quality): Quality improvements for PR-$ARGUMENTS" --body "$(cat <<'EOF'
## Summary

Retroactive quality improvements for PR #$ARGUMENTS.

### Original PR Issues
- [ ] Missing brainstorm → Added to docs
- [ ] Missing tests → Added X test files
- [ ] Missing breakdown → Documented

### Changes
- Add test coverage for [feature]
- Document design decisions

### Related
- Follows up: #$ARGUMENTS
- Depends on: #X (if any)
- Blocks: #Y (if any)

---

**Quality Score Impact:**
- Before: X/100
- After: Y/100 (estimated)
EOF
)"

---

Bước 6: Verify Fix

Sau khi fix, chạy lại /check-pr $ARGUMENTS để verify:

## Fix Verification: PR-$ARGUMENTS

### Before Fix
| Category | Score |
|----------|-------|
| Brainstorm | X/25 |
| Task Breakdown | X/25 |
| TDD | X/25 |
| Code Review | X/25 |
| **Total** | **X/100** |

### After Fix
| Category | Score |
|----------|-------|
| Brainstorm | Y/25 |
| Task Breakdown | Y/25 |
| TDD | Y/25 |
| Code Review | Y/25 |
| **Total** | **Y/100** |

### Improvement: +Z points

---

Output Summary

## Fix Plan: PR-$ARGUMENTS

### Status
- PR State: Open/Merged
- Current Score: X/100 (Grade)
- Target Score: 80+ (Grade B)

### Fix Strategy
- [ ] Strategy: Direct fix / Follow-up PR

### Actions Required

| # | Category | Issue | Fix Action | Effort |
|---|----------|-------|------------|--------|
| 1 | Brainstorm | Missing | Add retro brainstorm | 15 min |
| 2 | TDD | No tests | Add X test files | 1 hour |
| 3 | Review | No test plan | Update PR description | 10 min |

### Dependencies
- Blocks: [None / PR #X, #Y]
- Blocked by: [None / PR #Z]

### Estimated Total Effort: X hours

### Next Steps
1. [First action]
2. [Second action]
3. Run `/check-pr $ARGUMENTS` to verify

---

Quick Reference

Scenario	Strategy
PR Open, minor issues	Update PR directly
PR Open, major issues	May need to close and recreate
PR Merged, missing tests	Follow-up PR with tests
PR Merged, missing docs	Add to docs folder
Multiple PRs affected	Create dependency graph, fix in order

---

Gotchas

• Case A gh pr checkout strips local commits — if working tree has uncommitted changes the checkout fails; git stash first OR use Case B (follow-up PR) instead — never --force over local work
• Case B follow-up PR must NOT amend a closed gap to DONE — if the project uses a gap pipeline and the original PR closed GAP-NNN as PARTIAL with deferred items, the follow-up PR adds the missing pieces and only THEN flips Status (per gap-done-discipline.md §2 — banned phrases like "deferred to follow-up" + DONE in same diff are blocked)
• Retroactive brainstorm is NOT a free pass — adding a ## Retroactive Brainstorm section after-the-fact does not satisfy output-review-mandate.md §3 review standard; if the original PR shipped without methodology artifacts, the gap is in the process not the doc — surface that in commit message
• Docs-only fix PRs may still trip audit gates — even pure-docs follow-ups can trigger the project's audit-gate hook (if present) when file patterns match; per post-wave-audit-mandate.md §3 the docs-only exception applies only when ALL paths are docs/config-doc shape
• Commit messages follow project convention — match the repo's commit-trailer policy (some projects include Co-Authored-By, some strip it) — verify before push