@torka/claude-workflows 0.4.0 → 0.5.0

package/commands/github-pr-resolve.md

@@ -27,12 +27,22 @@ Before any operations, verify the environment is safe:
    - For each branch, record if it's checked out in a worktree and where
 
 6. **Check for uncommitted changes**: Run `git status --porcelain`.
-   - If output is non-empty, WARN the user (but do NOT block)
-   - Note: We only block if we need to checkout branches later for review comment fixes
-
-7. **Initialize operation log**: Create an in-memory log to track all operations performed.
-    - Track: operation type, target (PR/branch), status (success/failed)
-    - Log each operation as it completes
+   - If output is non-empty, offer handling options:
+     ```
+     You have uncommitted changes in your working directory.
+
+     Options:
+     1. Stash changes now (I'll restore them at the end)
+     2. Proceed carefully (I'll warn before any checkout operation)
+     3. Let me commit/stash manually first (pause workflow)
+     ```
+   - If stash chosen: Run `git stash push -m "github-pr-resolve: auto-stash"` and track `stash_used = true`
+   - Track stash state for restoration in Phase 5
+
+7. **Initialize task tracking**: Use TodoWrite to create a task list for the session.
+   - Add tasks for each phase: PR assessment, review comments, CI fixes, merges, cleanup
+   - Update task status as work progresses (this ensures nothing is missed)
+   - The todo list provides visibility to the user and keeps the workflow on track
 
 If gh authentication fails, STOP and clearly explain what the user needs to do.
 
@@ -83,11 +93,52 @@ Gather comprehensive information about all open PRs:
 
 For each PR with pending reviews or requested changes:
 
-### Step 1: Fetch review data
+### Step 1: Fetch ALL review data (multiple sources required)
+
+GitHub stores review feedback in THREE separate places. You MUST check all three:
+
+1. **PR-level reviews** (approval/rejection decisions):
+   ```bash
+   gh pr view <number> --json reviews,reviewDecision
+   ```
+
+2. **PR conversation comments** (general discussion):
+   ```bash
+   gh pr view <number> --json comments
+   ```
+
+3. **Inline code review comments** (line-specific feedback - CRITICAL, OFTEN MISSED):
+   ```bash
+   gh api repos/{owner}/{repo}/pulls/{number}/comments
+   ```
+   This returns comments attached to specific lines of code. These are the most actionable!
+
+**CRITICAL**: The `--json comments` flag does NOT include inline code review comments.
+You MUST call the `/pulls/{number}/comments` API endpoint separately.
+
+Parse each source and combine into a unified list with:
+- Comment body/text
+- Author (check if bot - see Step 1.5)
+- File path and line number (for inline comments)
+- Whether it's resolved/outdated
+- Creation timestamp
 
-Run `gh pr view <number> --json reviews,reviewDecision,comments` and `gh api repos/{owner}/{repo}/pulls/{number}/comments` to get:
-- Review decision (APPROVED, CHANGES_REQUESTED, REVIEW_REQUIRED)
-- All review comments with file paths and line numbers
+### Step 1.5: Identify bot reviewers
+
+Before categorizing comments, identify automated reviewers:
+
+**Known CI/review bots:**
+- `github-actions[bot]`
+- `chatgpt-codex-connector[bot]` or similar Codex bots
+- `coderabbitai[bot]`
+- `dependabot[bot]`
+- `renovate[bot]`
+- `sonarcloud[bot]`
+
+**Bot comment handling:**
+- Bot comments are often MORE actionable than they appear (security suggestions, code quality)
+- ALWAYS expand/check bot comments even if they seem informational
+- Display bot comments separately in the summary
 
 ### Step 2: Categorize comments
 
@@ -146,8 +197,20 @@ If user chooses auto-address:
 3. **After all accepted changes**:
    - Show consolidated diff
    - Ask for confirmation before committing
-   - Commit: `git commit -am "fix: address review comments"`
-   - Push: `git push`
+   - **Stage ONLY modified files explicitly** (NEVER use `git add .` or `git commit -a`):
+     ```bash
+     git add <file1> <file2> ...  # Only files that were actually modified
+     ```
+   - Verify staging is correct: `git status --short`
+   - If unexpected files are staged, warn user and ask how to proceed
+   - Commit: `git commit -m "fix: address review comments"`
+   - **Check upstream tracking before push**:
+     ```bash
+     # If no upstream set, use -u flag
+     git rev-parse --abbrev-ref --symbolic-full-name @{upstream} 2>/dev/null || git push -u origin <branch>
+     # Otherwise just push
+     git push
+     ```
 
 ### Step 5: Guided resolution for complex comments
 
@@ -211,6 +274,28 @@ For each open PR that needs CI verification:
 - Max 5 minute wait per CI run
 - 30 second polling interval
 
+### CI Wait Strategy
+
+At the start of Phase 3, if multiple PRs have CI running, ask user:
+
+```
+Multiple PRs have CI in progress:
+- PR #39: CI running (2 min elapsed)
+- PR #40: CI running (1 min elapsed)
+- PR #41: CI running (just started)
+
+Options:
+1. Wait for all CIs before proceeding (slower but complete)
+2. Process PRs as their CI completes (faster, may revisit)
+3. Only process PRs with CI already complete
+4. Check back in X minutes (pause workflow)
+```
+
+If a PR is created during the workflow (e.g., a CI fix PR), ask:
+- "Wait for this PR's CI before continuing"
+- "Continue with other ready PRs, check back later"
+- "This PR is a prerequisite - wait for it, then re-check dependent PRs"
+
 **Process:**
 
 1. **Check CI status**: `gh pr view <pr-number> --json statusCheckRollup`
@@ -234,7 +319,9 @@ For each open PR that needs CI verification:
      - Run the fix command
      - Show the diff to user
      - Ask for confirmation before committing
+     - **Stage ONLY files that were actually fixed** (use explicit paths, never `git add .`)
      - Commit with message: "fix: auto-fix lint errors"
+     - **Check upstream tracking before push** (use `-u` flag if needed)
      - Push and decrement retry counter
    - If manual fix chosen:
      - Inform user and pause for this PR
@@ -252,6 +339,38 @@ For each open PR that needs CI verification:
 
 For each PR that passed CI (and has no pending review comments):
 
+### Merge Order Strategy
+
+When multiple PRs are ready to merge, order matters:
+
+1. **Check for file overlap** between PRs:
+   ```bash
+   gh pr diff <pr1> --name-only > /tmp/pr1_files
+   gh pr diff <pr2> --name-only > /tmp/pr2_files
+   comm -12 <(sort /tmp/pr1_files) <(sort /tmp/pr2_files)
+   ```
+
+2. **Recommended merge order**:
+   | Priority | Criteria | Rationale |
+   |----------|----------|-----------|
+   | 1 | CI/infrastructure fixes | Unblocks other PRs |
+   | 2 | PRs with no file overlap | Independent, safe in any order |
+   | 3 | Dependency PRs first | If PR B depends on PR A's changes |
+   | 4 | Oldest PRs | Reduce stale PR backlog |
+   | 5 | Smallest PRs | Quick wins |
+
+3. **Present merge plan to user**:
+   ```
+   Recommended merge order:
+   1. PR #41 "Fix CI" (infrastructure - may unblock others)
+   2. PR #40 "Add feature X" (no conflicts)
+   3. PR #39 "Update component Y" (no conflicts)
+
+   Proceed with this order? [Yes / Let me reorder / Merge one at a time]
+   ```
+
+4. **Between merges**: Re-check remaining PRs for new conflicts after each merge
+
 ### Pre-merge checks
 
 1. Re-verify CI status (avoid race condition): `gh pr view <pr-number> --json statusCheckRollup`
@@ -301,6 +420,18 @@ For each PR that passed CI (and has no pending review comments):
 
 ## Phase 5: Final Cleanup & Summary
 
+### Step 0: Restore stashed changes (if applicable)
+
+If changes were stashed in Phase 0:
+1. After returning to original branch (Step 4), run `git stash pop`
+2. If pop fails (conflicts), warn user:
+   ```
+   Could not automatically restore your stashed changes.
+   Your changes are still in the stash. Run `git stash list` to see them.
+   Restore manually with: `git stash pop` or `git stash apply`
+   ```
+3. Show `git status` to confirm restoration
+
 ### Step 1: Handle orphaned worktrees from merged PRs
 
 For any worktrees whose branches were merged in Phase 4:
@@ -439,6 +570,13 @@ If the workflow fails at any point, display:
 - NEVER use force push (`--force` or `-f`)
 - ALWAYS preserve the user's working context (return to original branch)
 
+### Commit Safety Rules
+- NEVER use `git commit -a` or `git add .` without first reviewing what will be staged
+- ALWAYS use explicit file paths when staging: `git add <specific-file>`
+- ALWAYS run `git status` before committing to verify staged files
+- If the commit includes unexpected files, STOP and ask user before proceeding
+- ALWAYS check upstream tracking before push (use `-u` flag if no upstream)
+
 ### Worktree Safety Rules
 - NEVER remove a worktree with uncommitted changes without explicit user confirmation
 - ALWAYS check worktree status before operations

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@torka/claude-workflows",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Claude Code workflow helpers: epic automation, git cleanup, agents, and design workflows",
   "keywords": [
     "claude-code",