nathan13888/nice-skills/doc-n-fix

Doc-n-Fix

Gather PR review feedback, document it as a prioritized checklist, then fix issues one by one -- checking them off as you go.

Workflow

Follow all 7 steps sequentially.

Step 1: Identify the PR

1. Parse the invocation from everything after /doc-n-fix:

• /doc-n-fix (bare) -- auto-detect from current branch
• /doc-n-fix 42 or /doc-n-fix #42 -- specific PR number
• /doc-n-fix https://github.com/owner/repo/pull/42 -- PR URL
• /doc-n-fix --manual -- user will paste feedback directly (skip GitHub gathering)

1. Auto-detect (bare invocation or PR number):

``bash gh pr view --json number,title,url,body,headRefName,state ``

For a specific PR number, append the number: gh pr view {number} --json ...

1. PR state gate -- if state is MERGED or CLOSED, report "PR #{number} is {state} -- nothing to fix." and STOP.

1. Edge cases:

• Not a git repo -- report "Not a git repository." and stop.
• `gh` not installed or not authenticated -- suggest gh auth login and stop.
• No open PR for current branch -- use AskUserQuestion to ask for a PR number, URL, or --manual.

1. Store PR metadata: number, title, url, headRefName, state.

Step 2: Gather Review Feedback

GitHub path

Run a single Bash call to get repo info:

gh repo view --json owner,name

Then run 3 parallel Bash calls to collect all review types:

gh pr view {number} --json reviews

gh api --paginate repos/{owner}/{repo}/pulls/{number}/comments

gh pr view {number} --json comments

Error handling -- if any gh command fails, route by error:

Combine all feedback into a single list. Deduplicate using these explicit criteria:

1. Same `id` -- exact duplicate, keep one copy
2. Same `path` + `line` + `author` -- merge into one item, keep the newest body
3. Thread grouping -- comments linked via in_reply_to_id collapse to a single item

DO NOT deduplicate based on similar body text alone -- reviewers may intentionally leave similar comments on different locations.

Empty feedback gate -- if all 3 sources return zero comments/reviews, use AskUserQuestion: "No review feedback found. Options: (1) Switch to --manual mode and paste feedback, (2) Stop."

Manual path (--manual)

Use AskUserQuestion to ask the user to paste their review feedback. Parse using these rules:

• Split on numbered lists (1., 2.), bullet points (-, *), or blank-line-separated paragraphs
• Extract file/line references via patterns: file.ts:42, line 42, in foo.ts, at line N
• If the text is completely unstructured with no clear item boundaries, present as a single item and let the user split it during Step 3 validation

Step 3: Build the Deliverables List

Parse all feedback into fix items. For each item, extract:

Priority rules

• P1 -- Must Fix -- Correctness, bugs, security, blockers. Signal words: "must", "bug", "broken", "wrong", "blocker", "security", "critical", "fix this"
• P2 -- Should Fix -- Substantive improvements, refactoring, error handling, test gaps. This is the default for most comments.
• P3 -- Nice to Have -- Style, naming, optional suggestions. Signal words: "nit", "consider", "might want to", "optional", "minor", "style", "suggestion"

Grouping

Group related comments into single items:

• Thread replies to the same comment
• Multiple comments about the same logical issue
• Comments on the same code block

User validation

Present the list as a markdown table with columns: #, Description, Source, Location, Priority, Effort. Then use AskUserQuestion with these options:

• Looks good -- proceed as-is
• Adjust priorities -- user specifies which items to re-prioritize
• Add items -- user adds items not captured from review
• Remove items -- user removes items they don't want to fix
• Merge items -- user identifies items that should be combined

After each user edit, re-number items sequentially (no gaps). Repeat until the user confirms "Looks good."

Step 4: Choose Destination & Fix Order

Destination

Use AskUserQuestion to ask where to write the checklist:

1. GitHub PR description -- append a ## Review Checklist section (Recommended)
2. GitHub PR comment -- post as a new comment
3. Local file -- save to REVIEW-{PR#}.md
4. Other -- use AskUserQuestion to get the path, use Write to create the file, treat subsequent updates like a local file via Edit

Fix order

Use AskUserQuestion to ask what order to fix items:

1. Priority-first -- P1 > P2 > P3 (Recommended)
2. Quick wins first -- S > M > L within each priority tier
3. File-grouped -- group by file to minimize context switching

Write the initial checklist

Format the checklist using - [ ] items (renders as interactive checkboxes on GitHub):

## Review Checklist
 
**PR:** #{number} -- {title} | **Progress:** 0/{total}
 
### P1 -- Must Fix
 
-[ ] **#1** `src/auth.ts:42` -- Fix null check in auth middleware (@reviewer1, S)
 
### P2 -- Should Fix
 
-[ ] **#2** `src/api/users.ts:88` -- Extract validation to shared util (@reviewer2, M)
 
### P3 -- Nice to Have
 
-[ ] **#3** `src/api/users.ts:12` -- Rename variable for clarity (@reviewer1, S)

Write to the chosen destination:

• PR description: Read the current body with gh pr view {number} --json body --jq '.body'. If ## Review Checklist already exists, find it and replace everything from ## Review Checklist to the next ## heading or EOF. Otherwise append. Use Write to create /tmp/pr-body-{number}.md, then run gh pr edit {number} --body-file /tmp/pr-body-{number}.md.
• PR comment: Use Write to create /tmp/pr-comment-{number}.md, then run gh pr comment {number} --body-file /tmp/pr-comment-{number}.md. Parse the comment URL from the command output, extract the numeric comment ID (last segment of the URL), and store it for Step 6 updates.
• Local file: Use Write to create the file.

Important: Use Write tool for all temp files -- DO NOT use echo, cat <<EOF, or shell redirects. Always use --body-file or -F body=@file (capital F) for gh write commands.

Step 5: Fix Issues

Work through items in the chosen order, one at a time. For each item:

1. Read context -- Read the file(s) referenced in the comment. Use Grep to find related usages. Understand the surrounding code.

1. Apply fix:

• Simple fix (1-2 files, clear intent) -- use Read and Edit directly.
• Complex fix (touches 3+ files, requires understanding a call chain across 2+ modules, or reviewer references architectural concerns like refactor/redesign/extract) -- spawn a Task agent (subagent_type: general-purpose) with the fix description, relevant file paths, and reviewer comment as context.

1. Ambiguity gate -- if the reviewer's intent is unclear, use AskUserQuestion with options:

• Interpretation A -- {your best guess}
• Interpretation B -- {alternative reading}
• Skip -- skip this item for now (record { item_number, description, reason } -- used in Step 7)
• Ask reviewer -- post a clarifying question on the original comment

1. Ask reviewer option: Use Write to create /tmp/reply-{number}.md with the clarifying question, then post a reply:

``bash gh api repos/{owner}/{repo}/pulls/{number}/comments/{comment_id}/replies -F body=@/tmp/reply-{number}.md ``

If this returns 404 (the comment_id may be a top-level PR comment, not a review comment), fall back to:

``bash gh pr comment {number} --body-file /tmp/reply-{number}.md ``

1. Error recovery -- if a fix fails (edit produces errors, tests break, etc.): revert the affected files with git checkout -- {files}, record the item as skipped with reason "fix failed", and proceed to the next item.

Step 6: Update the Checklist

After each fix, immediately update the checklist:

1. Toggle the item: Find the line containing **#{item_number}** and change - [ ] to - [x].
2. Update the counter: Find the **Progress:** line and increment the first number.

Destination-specific update method:

• PR description: Re-read the full body with gh pr view {number} --json body --jq '.body', find and toggle the item, update the progress counter, use Write to create /tmp/pr-body-{number}.md, write back via gh pr edit {number} --body-file /tmp/pr-body-{number}.md.
• PR comment: Re-read the comment via gh api repos/{owner}/{repo}/issues/comments/{comment_id} --jq '.body', update, use Write to create /tmp/pr-comment-{number}.md, write back via gh api repos/{owner}/{repo}/issues/comments/{comment_id} -X PATCH -F body=@/tmp/pr-comment-{number}.md.
• Local file: Use Edit to toggle the checkbox and update the counter directly.

Update-failure recovery -- if the write fails (conflict, stale content), re-read the latest content and retry once. If it still fails, log the error and continue fixing remaining items -- bulk-update the checklist at the end.

Print brief progress after each update:

Fix #1 complete: Fix null check in auth middleware -- Progress: 1/5

Proceed to the next item automatically -- do NOT ask "continue?" between items.

Step 7: Completion Summary

After all items are processed, output:

## Doc-n-Fix Complete: PR #{number}
 
**Fixed:** {completed}/{total} | **Skipped:** {skipped}
 
### Completed
 
-[x] #1 {description} (P1, S)
-[x] #2 {description} (P2, M)
 
### Skipped (if any)
 
-[ ] #3 {description} -- {reason}
 
## What's Next?
 
1.**Push changes** -- commit and push all fixes
2.**Re-request review** -- notify reviewer that feedback is addressed
3.**Fix skipped items** -- revisit items that were skipped
4.**Run /check** -- verify the fixes are complete
5.**View diff** -- see all changes made

Guidelines