npm - @torka/claude-workflows - Versions diffs - 0.5.0 → 0.6.0 - Mend

@torka/claude-workflows 0.5.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (2) hide show

package/commands/github-pr-resolve.md +225 -467
package/package.json +1 -1

package/commands/github-pr-resolve.md CHANGED Viewed

@@ -1,5 +1,5 @@
 ---
-description: 'Assess open PRs, handle review comments, run CI, and merge'
+description: 'Autonomously process, fix, and merge all open PRs with minimal user interaction'
 ---
 IT IS CRITICAL THAT YOU FOLLOW THIS WORKFLOW EXACTLY.
@@ -16,569 +16,327 @@ Before any operations, verify the environment is safe:
 3. **Detect default branch**: Run `gh repo view --json defaultBranchRef -q .defaultBranchRef.name`. Fallback to `main` if this fails.
-4. **Record current branch and worktree**:
+4. **Detect repository merge strategy**:
+   - Run: `gh repo view --json squashMergeAllowed,mergeCommitAllowed,rebaseMergeAllowed`
+   - Determine preferred strategy in order: squash > merge > rebase
+   - Store for use in Phase 4 merge commands
+   - Default to `--squash` if detection fails
+5. **Record current branch and worktree**:
    - Run `git branch --show-current` to get current branch name
    - **If empty (detached HEAD)**: Run `git rev-parse HEAD` to save the commit SHA instead
    - Run `git rev-parse --show-toplevel` to record the current worktree path
-   - Track whether we started in detached HEAD state for Phase 5 restoration
-5. **Build worktree inventory**: Run `git worktree list --porcelain` to detect all worktrees.
-   - Parse the output to build a map: `{ branch_name -> worktree_path }`
-   - 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, offer handling options:
-     ```
-     You have uncommitted changes in your working directory.
+6. **Build worktree inventory**: Run `git worktree list --porcelain` to detect all worktrees.
-     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. **Check for uncommitted changes**: Run `git status --porcelain`.
+   - If output is non-empty, WARN the user but continue
-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
+8. **Initialize tracking**:
+   - Create counters: merged=0, skipped=0, failed=0, auto_fixed=0
+   - Create lists: merged_prs[], skipped_prs[], failed_prs[]
 If gh authentication fails, STOP and clearly explain what the user needs to do.
 ---
-## Phase 1: PR Discovery & Assessment
-Gather comprehensive information about all open PRs:
+## Phase 1: PR Discovery & Batch Planning
-1. **Fetch all open PRs**: Run `gh pr list --state open --json number,title,headRefName,baseRefName,statusCheckRollup,reviewDecision,isDraft,createdAt,url`
+**Goal**: Assess all PRs and start batch processing immediately.
-2. **For each PR, gather additional details**:
-   - Review status: `gh pr view <number> --json reviews,reviewDecision`
-   - CI status: Parse `statusCheckRollup` from the list query
-   - Mergeable status: `gh pr view <number> --json mergeStateStatus,mergeable`
+1. **Fetch all open PRs**:
+   ```bash
+   gh pr list --state open --json number,title,headRefName,baseRefName,statusCheckRollup,reviewDecision,isDraft,url,author,mergeStateStatus,mergeable,state
+   ```
-3. **Categorize PRs**:
+2. **For each PR, categorize**:
-   | Category | Description | Action |
-   |----------|-------------|--------|
-   | Ready to Merge | CI passed, approved, no conflicts | Phase 4 |
-   | Needs Review Comments | Has pending/requested changes | Phase 2 |
-   | CI Running | Checks in progress | Phase 3 |
-   | CI Failed | Checks failed | Phase 3 |
-   | Draft | Marked as draft | Skip unless user requests |
-   | Conflicts | Has merge conflicts | Warn user |
+   | Category | Detection | Auto-Action |
+   |----------|-----------|-------------|
+   | Ready to Merge | CI passed, mergeable=true | Merge immediately |
+   | CI Pending | statusCheckRollup has IN_PROGRESS | Wait and poll |
+   | CI Failed - Lint | Failed with lint/format errors | Auto-fix |
+   | CI Failed - Other | Tests/types/build failed | Skip with log |
+   | Behind Main | mergeStateStatus=BEHIND | Update branch, wait for CI |
+   | Conflicts | mergeable=CONFLICTING | Skip, warn user |
+   | Draft | isDraft=true | Skip |
+   | Already Merged | state=MERGED | Log and skip |
-4. **Present summary table**:
+3. **Present summary** (informational only, no blocking):
    ```
-   Open PRs Assessment:
-   | # | Title | Branch | Status | Reviews | CI | Mergeable |
-   |---|-------|--------|--------|---------|----|-----------|
-   | 42 | Add auth | feature-auth | Ready | Approved | ✓ | Yes |
-   | 43 | Fix bug | bugfix-123 | Review | Changes Requested | ✓ | Yes |
-   | 44 | New API | api-v2 | CI | - | Running | Yes |
-   | 45 | Refactor | refactor | Conflicts | - | ✓ | No |
+   Processing X open PRs...
+   | # | Title | Author | Status | Action |
+   |---|-------|--------|--------|--------|
+   | 42 | bump cross-env | dependabot | CI Passed | Will merge |
+   | 35 | bump sharp | dependabot | CI Pending | Will wait |
+   | 32 | bump linting | dependabot | CI Failed | Will auto-fix |
+   | 28 | new feature | user | Draft | Will skip |
+   | 25 | refactor auth | user | Conflicts | Will skip |
    ```
-5. **Ask user how to proceed**:
-   - "Process all PRs in order"
-   - "Let me select which PRs to process"
-   - "Skip to specific phase" (if user only wants merging)
----
-## Phase 2: Review Comments Handling
-For each PR with pending reviews or requested changes:
+4. **Check for blockers** - ONLY pause if:
+   - There are PRs with merge conflicts (warn user which ones will be skipped)
+   - There are draft PRs (inform user they will be skipped)
+   - All PRs have non-auto-fixable failures
-### Step 1: Fetch ALL review data (multiple sources required)
+   Otherwise, proceed automatically.
-GitHub stores review feedback in THREE separate places. You MUST check all three:
+5. **Sort PRs by priority**:
+   1. Infrastructure PRs first (CI/workflow changes)
+   2. PRs with passing CI
+   3. PRs with pending CI
+   4. PRs needing fixes
-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
-   ```
+## Phase 2: Review Comments Handling
-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!
+**Note**: This phase only runs if PRs have pending review comments. For batch processing of simple dependency bumps, this phase is typically skipped.
-**CRITICAL**: The `--json comments` flag does NOT include inline code review comments.
-You MUST call the `/pulls/{number}/comments` API endpoint separately.
+For PRs with `reviewDecision: CHANGES_REQUESTED`:
-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
+1. Fetch review comments
+2. If all comments are trivial (typos, formatting, docstrings) - auto-fix
+3. If comments require logic changes - skip PR and inform user
+4. Push fixes without asking for confirmation
-### Step 1.5: Identify bot reviewers
+---
-Before categorizing comments, identify automated reviewers:
+## Phase 3: CI Loop (Autonomous)
-**Known CI/review bots:**
-- `github-actions[bot]`
-- `chatgpt-codex-connector[bot]` or similar Codex bots
-- `coderabbitai[bot]`
-- `dependabot[bot]`
-- `renovate[bot]`
-- `sonarcloud[bot]`
+**Configuration:**
+- Polling interval: 30 seconds
+- Max wait per PR: 10 minutes
+- Max fix attempts: 2 per PR
-**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
+**For each PR, process in a loop:**
-### Step 2: Categorize comments
+### Step 1: Check Current State
+```bash
+gh pr view <number> --json state,statusCheckRollup,mergeStateStatus,mergeable
+```
-Analyze each comment and categorize:
+- If `state=MERGED`: Log `[X/N] PR #<number> - Already merged`, continue to next
+- If `state=CLOSED`: Log and skip
-| Category | Auto-addressable? | Examples |
-|----------|-------------------|----------|
-| Add comment/docstring | Yes | "Please add a comment explaining this", "Add JSDoc" |
-| Rename variable/function | Yes | "Rename `x` to `count`", "Use more descriptive name" |
-| Add type annotation | Yes | "Add type for this parameter" |
-| Fix typo | Yes | "Typo: 'recieve' -> 'receive'" |
-| Logic change | No - guided | "This should handle the null case" |
-| Refactor request | No - guided | "Extract this into a separate function" |
-| Question/clarification | No - guided | "Why is this needed?" |
-| Approval/praise | Skip | "LGTM", "Nice work" |
+### Step 2: Handle Branch Behind Main
-### Step 3: Display summary and ask user
+If `mergeStateStatus=BEHIND`:
+```
+      -> Updating branch to latest main...
+```
+```bash
+gh api repos/{owner}/{repo}/pulls/{number}/update-branch -X PUT
+```
+Then wait 30s and re-check CI.
-For each PR with comments:
+### Step 3: Wait for CI
+While CI is pending and elapsed < 10 minutes:
 ```
-PR #42: "Add user authentication"
-Review status: Changes Requested
-Reviewer: @reviewer-name
-Comments: 5 total
-  - 3 auto-addressable (add docstring, rename var, fix typo)
-  - 2 need guidance (logic change, refactor request)
-Options:
-1. Auto-address 3 simple comments (Recommended)
-2. Guide me through all 5 comments
-3. View all comments first
-4. Skip this PR
+      -> Waiting for CI... (Xs)
 ```
+- Sleep 30 seconds
+- Re-check status
-### Step 4: Auto-address simple comments
-If user chooses auto-address:
-1. **Checkout the PR branch** (if not already):
-   - Check if branch is in a worktree - if so, operate there with `git -C`
-   - Otherwise: `git checkout <branch>`
-2. **For each auto-addressable comment**:
-   - Read the file at the specified path
-   - Identify the exact location (line number from review comment)
-   - Make the change based on the comment type:
-     - **Add comment/docstring**: Generate appropriate documentation
-     - **Rename**: Use find/replace for the identifier
-     - **Add type annotation**: Infer or use suggested type
-     - **Fix typo**: Apply the correction
-   - Show diff to user: "Change X to Y in file.ts:42"
-   - Ask: "Apply this change?" / "Skip" / "Edit manually"
-3. **After all accepted changes**:
-   - Show consolidated diff
-   - Ask for confirmation before committing
-   - **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 4: Handle CI Results
-### Step 5: Guided resolution for complex comments
+**If CI passes**: Proceed to Phase 4 (merge)
+**If CI fails**:
+1. Get failure logs:
+   ```bash
+   gh run list --branch <branch> --status failure --limit 1 --json databaseId -q '.[0].databaseId'
+   gh run view <id> --log-failed 2>&1 | head -100
+   ```
-If user chooses guided resolution or has complex comments remaining:
+2. Analyze failure type:
-For each complex comment:
-1. Display the comment with full context:
+   **Lint/Formatting errors** (auto-fixable):
    ```
-   File: src/auth/login.ts
-   Line: 42-45
-   Reviewer: @reviewer-name
-   Comment: "This should handle the null case - what happens if user is undefined?"
-   Current code:
-   40 |   const user = getUser(id);
-   41 |   return user.name;  // <- reviewer's concern
-   42 | }
+      X CI failed (lint errors)
+      -> Auto-fixing lint errors...
    ```
+   - Checkout branch (handle worktree)
+   - Run `npm install && npm run lint -- --fix`
+   - If changes exist:
+     ```bash
+     git add -A
+     git commit -m "fix: auto-fix lint errors"
+     git push
+     ```
+   - Wait for CI to re-run
+   - Decrement retry counter
+   - If this is the 2nd consecutive failure with same error: skip PR
-2. Ask user with `AskUserQuestion`:
+   **Type errors / Test failures / Build errors** (NOT auto-fixable):
    ```
-   How would you like to address this?
-   1. Show me the file (I'll make the fix)
-   2. Suggest a fix (Claude will propose code)
-   3. Mark as resolved with reply
-   4. Skip for now
+      X CI failed (type errors) - skipping
    ```
+   - Add to skipped_prs with reason
+   - Continue to next PR immediately
-3. **If "Suggest a fix"**:
-   - Analyze the code and comment
-   - Propose a code change
-   - Show diff and ask for confirmation
-   - Apply if accepted
-4. **If "Mark as resolved with reply"**:
-   - Ask user for reply text
-   - Post reply: `gh api repos/{owner}/{repo}/pulls/{number}/comments/{comment_id}/replies -f body="<reply>"`
-### Step 6: Post-comment handling
-After addressing comments:
-- Ask: "Re-request review from @reviewer?" / "Mark ready for review?" / "Leave as-is"
-- If re-request: `gh pr ready <number>` (if was draft) or comment @-mentioning reviewer
-### Safety Guardrails
-- NEVER auto-address comments that involve logic changes
-- ALWAYS show diff before committing auto-addressed changes
-- ALWAYS confirm before pushing
-- Track which comments were addressed vs skipped for summary
-- NEVER modify code that the comment doesn't directly reference
----
-## Phase 3: CI Loop
-For each open PR that needs CI verification:
-**Configuration:**
-- Max 3 fix attempts per PR
-- Max 5 minute wait per CI run
-- 30 second polling interval
-### CI Wait Strategy
+   **Secrets unavailable** (Dependabot):
+   - Try updating branch first (may get new CI workflow)
+   - If still fails after update: skip with note
-At the start of Phase 3, if multiple PRs have CI running, ask user:
+### Step 5: Timeout Handling
+If 10 minutes elapsed and CI still pending:
 ```
-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)
+      ! CI timed out after 10 minutes - skipping
 ```
-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`
-2. **If CI is running**:
-   - Display: "Waiting for CI on PR #<number>... (attempt X/3, Xs elapsed)"
-   - Wait 30 seconds
-   - Re-check (up to 5 minutes total)
-3. **If CI passes**: Mark PR as ready for merge, proceed to Phase 4
-4. **If CI fails**:
-   - Fetch and display the failure output
-   - Categorize the failure:
-     - **Lint/Formatting errors**: Offer to run `npm run lint -- --fix` automatically
-     - **Type errors**: Show errors, ask user: "Skip this PR", "I'll fix manually"
-     - **Test failures**: Show test output, ask user: "Skip this PR", "I'll fix manually"
-     - **Build errors**: Show error, ask user: "Skip this PR", "I'll fix manually"
-   - If auto-fix chosen (lint only):
-     - Checkout branch (handle worktree if needed)
-     - 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
-     - Ask: "Continue with other PRs?" or "Wait for manual fix?"
-5. **If max retries exceeded**:
-   - Ask user: "Skip this PR", "Abort workflow", or "I'll fix manually"
-   - Handle accordingly
-**IMPORTANT**: NEVER auto-fix test failures or type errors. Only lint/formatting issues are safe to auto-fix.
+- Add to skipped_prs
+- Continue to next PR
 ---
-## Phase 4: Merge PRs
-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 |
+## Phase 4: Merge (No Confirmation Needed)
-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]
-   ```
+For each PR that passed CI:
-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`
-2. Check merge state: `gh pr view <pr-number> --json mergeStateStatus,mergeable`
+### Pre-merge Verification
+```bash
+gh pr view <number> --json state,mergeStateStatus,mergeable
+```
-### Handle branch behind default branch
+- If `state=MERGED`: Log and continue (already merged)
+- If `mergeable=CONFLICTING`: Skip (conflicts appeared)
-**If `mergeStateStatus` is `BEHIND`:**
-- Ask user: "Update branch via GitHub" or "Skip this PR"
-- If update chosen:
-  - Run: `gh api repos/{owner}/{repo}/pulls/{pr-number}/update-branch -X PUT`
-  - If the API call fails (e.g., merge conflicts), inform user and offer to skip
-- Wait for CI to re-run after update
-- Re-check merge state
+### Execute Merge
-### Handle merge conflicts
+```bash
+gh pr merge <number> --squash --delete-branch
+```
-**If `mergeable` is `CONFLICTING`:**
-- STOP - cannot auto-merge
-- Show the PR URL
-- Ask user: "Skip this PR" or "I'll resolve conflicts manually"
-- If manual resolution, wait for user confirmation then re-check
+(Use detected strategy from Phase 0: --squash, --merge, or --rebase)
-### Merge
+**Handle results:**
+- Success: Log `Merged`, increment counter
+- "Already merged" error: Log as success, continue
+- Other error: Log error, add to failed_prs, continue to next PR
-- Present merge summary before proceeding:
-  ```
-  Ready to merge:
-  PR #42: "Add user authentication" (feature-auth -> main)
+**Output format:**
+```
+[1/8] PR #42 "bump cross-env"
+      -> CI passed -> merged
-  This will:
-  - Merge the PR using repository's merge strategy
-  - Delete the remote branch
+[2/8] PR #35 "bump sharp"
+      -> Waiting for CI... (45s)
+      -> CI passed -> merged
-  Proceed? [Yes / Skip / Abort]
-  ```
-- Run `gh pr merge <pr-number> --delete-branch`
-- This respects the repository's merge strategy settings
-- The `--delete-branch` flag removes the remote branch after merge
+[3/8] PR #32 "bump linting group"
+      X CI failed (lint errors)
+      -> Auto-fixing lint errors...
+      -> Pushed fix, waiting for CI... (30s)
+      -> CI passed -> merged
-### Handle merge failure
+[4/8] PR #28 "new feature"
+      - Skipped (draft PR)
-- Report the error
-- Ask user how to proceed
+[5/8] PR #25 "refactor auth"
+      - Skipped (merge conflicts)
+```
 ---
-## Phase 5: Final Cleanup & Summary
+## Phase 5: Cleanup & Summary (Automatic)
-### Step 0: Restore stashed changes (if applicable)
+### Step 1: Auto-cleanup (no prompts)
-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`
+1. Prune remote refs:
+   ```bash
+   git fetch --prune
    ```
-3. Show `git status` to confirm restoration
-### Step 1: Handle orphaned worktrees from merged PRs
+2. For each merged PR's branch, delete local if exists:
+   ```bash
+   git branch -d <branch> 2>/dev/null || true
+   ```
-For any worktrees whose branches were merged in Phase 4:
-- The remote branch is now deleted, but the local worktree may still exist
-- For each such worktree, ask user:
-  ```
-  Worktree at '<path>' is now on merged branch '<branch>'.
+3. Prune worktrees:
+   ```bash
+   git worktree prune
+   ```
-  Options:
-  1. Remove worktree (Recommended)
-  2. Keep worktree (switch to <default-branch>)
-  ```
-- If remove: `git worktree remove <path>`
-- If keep: `git -C <path> checkout <default-branch>`
+### Step 2: Return to original context
-### Step 2: Clean up local branches
+- If original branch exists: `git checkout <original-branch>`
+- If it was merged: checkout default branch
+- If was detached HEAD: `git checkout <original-sha>`
-For each PR merged in Phase 4:
-- Delete local branch if it exists: `git branch -d <branch>`
-- Skip if branch is checked out in a remaining worktree
+### Step 3: Display Final Summary
-### Step 3: Clean up stale refs
+```
+=====================================================
+        PR Resolution Complete
+=====================================================
-1. Run `git fetch --prune` to clean up all stale remote refs
-2. Run `git worktree prune` to clean up stale worktree admin entries
+RESULTS:
+  Merged: X PRs
+  - #42 "bump cross-env"
+  - #35 "bump sharp"
+  - #32 "bump linting group" (auto-fixed lint)
-### Step 4: Return to original context
+  Skipped: X PRs
+  - #28 "new feature" (draft)
+  - #25 "refactor auth" (merge conflicts)
-- **If original state was a branch**: Run `git checkout <original-branch>` (if it still exists, otherwise stay on default branch)
-- **If original state was detached HEAD**: Run `git checkout <original-commit-sha>` to restore exact position
-- If the original branch was merged and deleted, inform user: "Your original branch '<branch>' was merged. You are now on '<default-branch>'."
+  Failed: X PRs
+  - #20 "breaking change" (type errors - needs manual fix)
-### Step 5: Display final summary
+AUTO-FIXES APPLIED:
+  - X lint errors fixed automatically
-```
-=====================================================
-        GitHub PR Resolution Complete!
-=====================================================
+REMAINING WORK:
+  - PR #25 has merge conflicts at: src/auth.ts
+  - PR #20 needs manual fix for type errors
-PRs PROCESSED:
-✓ Merged X PRs
-  - PR #42: "Add user authentication"
-  - PR #43: "Fix login bug"
-○ Skipped X PRs (CI failed / conflicts)
-  - PR #45: "Refactor" (merge conflicts)
-REVIEW COMMENTS:
-✓ Auto-addressed X comments
-✓ Manually resolved X comments
-○ Skipped X comments
-CI FIXES:
-✓ Auto-fixed X lint issues
-○ X PRs need manual fixes
-CLEANUP:
-✓ Deleted X remote branches
-✓ Deleted X local branches
-✓ Removed X worktrees
-CURRENT STATE:
-  Branch: <current-branch>
-  Worktree: <current-worktree-path>
-REMAINING OPEN PRs:
-  - PR #45: "Refactor" - merge conflicts, needs manual resolution
-  - PR #46: "Draft feature" - draft, skipped
-WARNINGS (if any):
-  - PR #45 has merge conflicts at src/auth/login.ts
 =====================================================
 ```
 </workflow>
-## Error Recovery
-If the workflow fails at any point, display:
-1. **Operations completed successfully** (from the operation log)
-2. **The operation that failed** and the error message
-3. **Current repository state**:
-   - Current branch: `git branch --show-current`
-   - Uncommitted changes: `git status --porcelain`
-   - Any in-progress operations: check for rebase/merge/cherry-pick
+## Safety Rules
-4. **Recovery guidance based on failure point**:
+### ALWAYS Auto-fix
+- Lint errors (`npm run lint -- --fix`)
+- Formatting errors
-   **If failed during review comment fix:**
-   - Changes may be uncommitted
-   - Check: `git status` and `git diff`
-   - Either commit or stash the changes
-   - PR is still open (safe)
+### NEVER Auto-fix
+- Type errors (TypeScript)
+- Test failures
+- Build errors
+- Logic changes in review comments
-   **If failed during CI fix commit:**
-   - Changes may be uncommitted
-   - Check: `git status`
-   - Commit manually: `git commit -am "fix: ..."`
-   - Push: `git push`
+### Branch Safety
+- NEVER use force push
+- ALWAYS preserve user's starting context
+- ALWAYS use detected merge strategy
-   **If failed during merge:**
-   - PR still exists, not merged
-   - Check PR status: `gh pr view <number>`
-   - Retry via GitHub UI or: `gh pr merge <number>`
+### Timing
+- 30 second polling interval
+- 10 minute max wait per PR
+- 2 max fix attempts before skipping
-   **If failed during worktree cleanup:**
-   - Worktree may be partially removed
-   - Run: `git worktree prune` to clean up
-   - Check: `git worktree list`
+### Error Handling
+- "Already merged" is a success, not an error
+- Continue to next PR on any error
+- Log all failures for summary
+- Never block on a single PR failure
-   **If failed during branch deletion:**
-   - Local branch may be deleted but remote still exists (or vice versa)
-   - Check: `git branch -a | grep <branch>`
-   - Manual cleanup if needed
+---
-5. **Always safe to re-run**: The workflow is idempotent - running it again will skip already-completed operations.
+## Error Recovery
----
+If the workflow fails at any point:
-## Safety Rules
+1. **Show completed operations**
+2. **Show current state**: `git branch --show-current`, `git status --porcelain`
+3. **Re-run is safe**: The workflow is idempotent - merged PRs show as "Already merged"
-### PR Safety Rules
-- NEVER merge without CI passing
-- NEVER force merge when conflicts exist
-- ALWAYS verify merge state before merging
-- ALWAYS respect retry limits
-### Review Comment Safety Rules
-- NEVER auto-address comments that involve logic changes
-- ALWAYS show diff before committing changes
-- ALWAYS confirm before pushing
-- NEVER modify code that the comment doesn't directly reference
-- ALWAYS track which comments were addressed for summary
-### Branch Safety Rules
-- 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
-- ALWAYS run `git worktree prune` after removing worktrees
-- ALWAYS use `git -C <path>` for operations in linked worktrees
+**Common issues:**
+- "Already merged" - Normal, PR was auto-merged externally
+- CI timeout - Re-run later or check GitHub Actions
+- Merge conflicts - Resolve manually, then re-run

package/package.json CHANGED Viewed

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