Update to the PR manager

Author: timothyfroehlich

.gemini/skills/jules-pr-manager/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: Jules PR Manager
 description: Manage Google Jules PR lifecycle - batch processing, priority sorting, and serial decision making.
-version: 1.0.0
+version: 1.3.0
 ---
 
 # Jules PR Manager
@@ -10,140 +10,216 @@ version: 1.0.0
 
 **Manage the lifecycle of PRs created by Google's Jules agent (Gemini 2.5 Pro).**
 
-This skill orchestrates a **Fetch-Analyze-Batch-Execute** loop to manage multiple PRs efficiently in a single-threaded CLI environment. It enforces strict prioritization (merges first) and handles automated maintenance (timeouts) before asking for user input.
+This skill orchestrates a **Fetch-Analyze-Batch-Execute** loop to manage multiple PRs efficiently in a single-threaded CLI environment. It strictly prioritizes **finishing work** (merging) before **starting work** (vetting/reviewing).
 
 **Core Principle**: **One decision per turn.** Automate everything else in batch.
 
 ## Execution Model
 
 1.  **Fetch (Batch)**: Retrieve state of _all_ Jules PRs in one `gh` command.
-2.  **Analyze**: Parse JSON to assign Tiers (1-6) and identify "Stalled" PRs.
-3.  **Automate (Batch)**: Execute non-blocking updates (labeling stalled PRs, removing waiting labels) immediately.
-4.  **Decide**: Select the _single_ highest-priority PR requiring user input.
-5.  **Execute**: Present context and ask for _one_ decision.
-
-## PR Priority Tiers
-
-Process PRs in this order. Stop at the first tier that has candidates.
-
-1.  **Tier 1: Pre-Merge Validation** (Ready to merge)
-    - _Condition_: No stage labels, CI passed, Reviews approved.
-    - _Action_: Present Merge Confirmation.
-2.  **Tier 2: Copilot Comments Addressed**
-    - _Condition_: `jules:copilot-comments` + recent commits.
-    - _Action_: Review changes, then validation.
-3.  **Tier 6: Missing Vetting** (High Priority Filtering)
-    - _Condition_: Missing `jules:vetted`.
-    - _Action_: Duplicate check -> Manual Vetting.
-4.  **Tier 3: Waiting for Copilot**
-    - _Condition_: `jules:copilot-review`.
-    - _Action_: Poll/Wait (or skip if waiting).
-5.  **Tier 4: Waiting for Jules**
-    - _Condition_: `jules:changes-requested`.
-    - _Action_: Check timeout -> Stalled?
-6.  **Tier 5: Draft Review**
-    - _Condition_: `jules:draft-review` + `jules:vetted`.
-    - _Action_: Initial code review.
+2.  **Analyze**: Parse JSON to assign Priorities and identify "Stalled" PRs.
+3.  **Automate (Batch)**: Execute non-blocking updates (timeouts, label cleanup) immediately.
+4.  **Prioritize**: Select the _single_ highest-priority PR requiring user input.
+5.  **Execute**: Apply the specific **Workflow** for that PR's state.
 
-## Workflow Commands
+---
 
-### 1. Batch Fetch (The "State of the World")
+## Priority Logic: "Clear Exits, Vet Entrances, Then Grind"
 
-Always start by fetching ALL relevant data in one go to minimize tool calls.
+Process PRs in this strict order. Stop at the first group that has candidates.
 
-```bash
-gh pr list \
-  --search "author:app/google-labs-jules is:open" \
-  --json number,title,labels,createdAt,updatedAt,headRefName,mergeable,reviews,statusCheckRollup,isDraft \
-  > .gemini/tmp/jules_prs.json
-```
+### 1. The Exit Ramp (High Value)
 
-### 2. Timeout Analysis & Automation
+- **Priority 1: Ready to Merge**
+  - _Condition_: Vetted + CI Passed + Copilot Approved + No Conflicts.
+  - _Goal_: Ship finished code.
+- **Priority 2: Copilot Comments Addressed**
+  - _Condition_: `jules:copilot-comments` + Recent Jules commits.
+  - _Goal_: Validate fixes and move to Merge.
 
-Check timestamps to detect stalled agents (>30 mins silence) _only when the agent is expected to act_.
+### 2. The Gatekeeper (Vetting + Initial Review)
 
-**Definition of Stalled:**
+- **Priority 3: Unvetted PRs**
+  - _Condition_: **Missing** `jules:vetted` label.
+  - _Goal_: Filter duplicates -> Review Code -> Move to next stage (Copilot or Changes Requested).
+  - _Note_: Combines "Vetting" and "Stage 1 Draft Review".
 
-- **Time**: `updatedAt` > 30 mins ago.
-- **State**: Label is `jules:changes-requested` OR `jules:copilot-comments`.
-- **Actor**: The last timeline event was _NOT_ from the agent bot (`app/google-labs-jules`).
+### 3. The Grind (In-Flight)
 
-**Pattern:**
+- **Priority 4: Stalled Agents**
+  - _Condition_: `jules:agent-stalled`.
+  - _Goal_: Manual intervention to unblock.
+- **Priority 5: Copilot Reviews**
+  - _Condition_: `jules:copilot-review` (Check if review finished).
+  - _Goal_: Bridge Copilot comments to Jules.
+- **Priority 6: Waiting**
+  - _Condition_: `jules:changes-requested` (and not stalled).
+  - _Goal_: Wait (no action).
 
-1.  Filter `.gemini/tmp/jules_prs.json` for PRs matching the **Time** and **State** criteria.
-2.  **Verify last actor** (MANDATORY):
-    For each candidate, fetch the timeline to confirm the agent hasn't already responded.
-    ```bash
-    gh pr view <PR> --json timelineItems --jq '.timelineItems[-1].actor.login'
-    ```
-    _If the last actor is `google-labs-jules`, do NOT label as stalled._
-3.  **Batch Update**:
-    Only label confirmed stalled PRs.
-    ```bash
-    gh pr edit <ID> --add-label "jules:agent-stalled"
-    ```
+---
 
-### 3. Duplicate Detection (Tier 6)
+## Execution Guidelines
 
-Before vetting, check for duplicates. **Only runs for PRs missing `jules:vetted`.**
+### ⚠️ Critical: Interaction with Jules
 
-```bash
-# 1. Identify potential duplicates (same title/files)
-gh pr list --search "is:open author:app/google-labs-jules <keywords>" --json number,title
+Jules **ignores** regular comments. You must use **Reviews** to trigger action.
+
+- **Requesting Changes**:
+  ```bash
+  gh pr review <ID> --request-changes --body "..."
+  ```
+- **Approving**:
+  ```bash
+  gh pr review <ID> --approve --body "..."
+  ```
+- **Do NOT use**: `gh pr comment` (unless you are reposting Copilot comments for _your own_ tracking, but even then, a review is safer).
+
+## Decision Templates
 
-# 2. Compare diffs (efficiently)
-gh pr diff <New_PR> > new.diff
-gh pr diff <Existing_PR> > existing.diff
-diff -u new.diff existing.diff | head -n 20 # Check for significant overlap
+**CRITICAL**: You MUST use these templates when asking for user confirmation. Do not deviate.
+
+### 1. Vetting Template (Stage 6)
+
+Use this when asking to approve a new PR (`jules:vetted`).
+
+```markdown
+## 🛡️ Vetting Request: PR #<ID>
+
+**Title**: <Title>
+**Type**: <Sentinel/Bolt/Palette>
+**Summary**: <Brief summary of changes>
+**Duplicates**: <None | List duplicates found and closed>
+**CI**: <Passing/Failing/Running>
+**Risk**: <High/Medium/Low based on files touched>
+
+**Approve for processing?** (y/n)
 ```
 
-### 4. Merge Confirmation (Tier 1)
+### 2. Ready for Copilot Template (Stage 3)
+
+Use this when moving from Human Review to Copilot Review.
+
+```markdown
+## 🤖 Hand off to Copilot: PR #<ID>
+
+**Title**: <Title>
+**Status**: Code reviewed, initial issues resolved.
+**Next Step**: Label `jules:copilot-review`
+**Validation**:
+
+- [ ] Non-negotiables checked
+- [ ] Basic logic verified
+
+**Send to Copilot?** (y/n)
+```
 
-Present full context before asking "y/n".
+### 3. Merge Template (Tier 1)
 
-**Template:**
+Use this for the final merge decision.
 
 ```markdown
-## Ready to Merge: PR #<ID>
+## 🚀 Ready to Merge: PR #<ID>
 
 **Title**: <Title>
 **Type**: <Sentinel/Bolt/Palette>
-**Changes**: <Summary>
+**Changes**: <Summary of impact>
 **CI**: ✅ Passed
 **Conflicts**: None
 **Recommendation**: MERGE
 
 **Confirm auto-merge?** (y/n)
 ```
 
-## Common Mistakes
+## Workflows
+
+### 🏁 The Exit Ramp: Merging (Priority 1)
+
+**Trigger**: CI passed, Reviews passed, No conflicts.
+
+1.  **Final Check**: Ensure `NON_NEGOTIABLES.md` compliance.
+2.  **Context**: Gather summary of changes + "Why".
+3.  **Action**: **Use Merge Template** to ask user.
+
+### 🛡️ The Gatekeeper: Vetting & Review (Priority 3)
+
+**Trigger**: PR is missing `jules:vetted`.
+
+1.  **Duplicate Check**:
+    ```bash
+    gh pr list --search "is:open author:app/google-labs-jules <keywords>"
+    gh pr diff <ID> > new.diff
+    gh pr diff <EXISTING> > old.diff
+    diff -u new.diff old.diff | head
+    ```
+2.  **Analyze**: Duplicate? Junk? Good?
+3.  **Code Review**: If unique, review code _now_. Check that **Prettier**, **ESLint**, and **Unit Tests** pass.
+4.  **Action**:
+    - **Duplicate**: Comment on winner with code from loser, close loser.
+    - **Bad**: Close with feedback.
+    - **Good**: **Use Vetting Template** to ask user. (If approved AND CI passes, add `jules:vetted` -> `jules:copilot-review`).
+    - **Issues (or CI Failure)**: **Use Vetting Template** (noting issues/failing checks). If approved, add `jules:vetted` -> Request Changes -> Add `jules:changes-requested`.
 
-- **Asking "What next?"**: You are the manager. You decide what's next based on priority tiers.
-- **Processing Tier 5 before Tier 1**: Always clear the exit ramp (merges) before filling the entrance (drafts).
-- **Ignoring `jules:vetted`**: Processing un-vetted PRs wastes tokens on duplicates or hallucinations.
-- **Manual Conflict Resolution in Shell**: Complex conflicts are hard to fix via CLI. Instruct user to fix locally if `git merge` fails cleanly.
+### 🌉 The Bridge: Copilot Handling (Priority 5)
+
+**Trigger**: `jules:copilot-review`.
+
+**CRITICAL**: Jules cannot see Copilot reviews.
+
+1.  **Check Status**: Has Copilot finished? (State: `COMMENTED` / `CHANGES_REQUESTED`).
+2.  **Fetch**: Get comments via `gh api`.
+3.  **Repost**: Post each comment as a new comment from YOU, tagging `@google-labs-jules`.
+4.  **Label**: Swap `jules:copilot-review` -> `jules:copilot-comments`.
+
+---
+
+## Workflow Commands
+
+### 1. Batch Fetch (The "State of the World")
+
+Always start by fetching ALL relevant data.
+
+```bash
+gh pr list \
+  --search "author:app/google-labs-jules is:open" \
+  --json number,title,labels,createdAt,updatedAt,headRefName,mergeable,reviews,statusCheckRollup,isDraft \
+  > .gemini/tmp/jules_prs.json
+```
+
+### 2. Timeout Automation (Batch)
+
+Check for stalled agents (>30 mins silence) _before_ interacting with user.
+
+**Logic:**
+
+- **Target**: Labels `jules:changes-requested` OR `jules:copilot-comments`.
+- **Condition**: `updatedAt` > 30 mins ago AND Last Actor != `app/google-labs-jules`.
+- **Action**: Add `jules:agent-stalled`.
+
+### 3. Conflict Check
+
+If `mergeable: "CONFLICTING"`, apply `jules:merge-conflicts`.
+**Note**: Do NOT attempt to fix conflicts automatically in the CLI. Ask user to resolve locally.
 
 ## GitHub Labels Reference
 
-| Label                     | Meaning                   | Action                  |
-| :------------------------ | :------------------------ | :---------------------- |
-| `jules:draft-review`      | Initial Review            | Review code             |
-| `jules:changes-requested` | Waiting for Jules         | Check timeout           |
-| `jules:copilot-review`    | Waiting for Copilot       | Wait/Poll               |
-| `jules:copilot-comments`  | Copilot comments reposted | Wait for Jules          |
-| `jules:merge-conflicts`   | Conflicts                 | **User** fixes (manual) |
-| `jules:agent-stalled`     | >30m silence              | Manual intervention     |
-| `jules:vetted`            | Approved for processing   | Required for work       |
+| Label                     | Category | Meaning                                    |
+| :------------------------ | :------- | :----------------------------------------- |
+| `jules:vetted`            | **Gate** | **REQUIRED**. Approved for processing.     |
+| `jules:draft-review`      | Stage    | (Legacy) Initial human review.             |
+| `jules:changes-requested` | Wait     | Waiting for Jules to fix human feedback.   |
+| `jules:copilot-review`    | Wait     | Waiting for Copilot.                       |
+| `jules:copilot-comments`  | Wait     | Waiting for Jules to fix Copilot feedback. |
+| `jules:agent-stalled`     | Alert    | >30m silence. Needs help.                  |
+| `jules:merge-conflicts`   | Alert    | Git conflict. Needs manual fix.            |
 
-## Anti-Patterns
+## Common Mistakes
 
-- **❌ Checking out PR branches**: Switching branches is disruptive to the user's worktree and often unnecessary. **Fix**: Use `gh pr diff` and `gh pr view` for analysis. If checks fail, report the failure or repost the logs for the agent.
-- **❌ The "Wall of Text"**: Listing status for 10 PRs and asking "What first?". **Fix**: Pick the winner, present only that.
-- **❌ Serial Fetching**: `gh pr view 101`, then `102`, then `103`. **Fix**: `gh pr list --json ...`
-- **❌ Assuming Jules reads Copilot**: Jules is blind to Copilot. You must repost comments.
-- **❌ Silent Merging**: Never merge without explicit "y" from user in that specific turn.
+- **Reviewing Unvetted PRs**: Wastes time on duplicates. Vet first.
+- **Ignoring the Exit Ramp**: Don't start new drafts if you have PRs ready to merge.
+- **Silent Merging**: Always get explicit "y" confirmation.
+- **Assuming Jules Reads Copilot**: It doesn't. You must be the bridge.
 
 ## Agent Search Optimization (ASO)
 
-**Description**: Manage Google Jules PR lifecycle - batch processing, priority sorting, and serial decision making.
-**Keywords**: jules, google-labs-jules, pr manager, batch, prioritization, timeout, stalled, merge
+**Description**: Manage Google Jules PR lifecycle - gatekeeper vetting, batch processing, and priority sorting.
+**Keywords**: jules, google-labs-jules, pr manager, batch, prioritization, timeout, stalled, merge, vetting, gatekeeper