opensearch-project · ahkcs · Apr 30, 2026
@@ -0,0 +1,162 @@
+---
+allowed-tools: Agent, Read, Bash(gh:*), Bash(git:*)
+description: Run the PPL bugfix harness for a GitHub issue or follow up on an existing PR
+---
+
+Fix a PPL bug or follow up on an existing PR using the harness in `.claude/harness/ppl-bugfix-harness.md`.
+
+## Input
+
+Accepts one or more issue/PR references. Multiple references are processed in parallel (each gets its own subagent + worktree).
+
+- `/ppl-bugfix #1234` — single issue
+- `/ppl-bugfix PR#5678` — single PR
+- `/ppl-bugfix #1234 #5678 PR#9012` — multiple in parallel
+- `/ppl-bugfix https://github.com/opensearch-project/sql/issues/1234` — URL
+
+Optional mode flag (append to any of the above):
+- `--safe` — `acceptEdits` mode. Auto-approve file edits only, Bash commands require manual approval. (Most conservative)
+- `--yolo` — `bypassPermissions` mode. Fully trusted, no prompts. Subagent runs in an isolated worktree so this is safe. (Default)
+
+> **Note**: `bypassPermissions` skips the interactive prompt but still respects the allow-list in `~/.claude/settings.json`. Ensure git/gh write commands are in the global allow-list.
+
+Examples:
+- `/ppl-bugfix #1234` — single issue, defaults to yolo
+- `/ppl-bugfix #1234 #5678 --yolo` — two issues in parallel
+- `/ppl-bugfix PR#5293 PR#5300` — two PRs in parallel
+- `/ppl-bugfix #1234 PR#5678 --safe` — mix of issue and PR
+
+If no argument given, ask for an issue or PR number.
+
+## Step 0: Resolve Permission Mode
+
+Parse the mode flag from the input arguments:
+
+| Flag | Mode |
+|------|------|
+| `--safe` | `acceptEdits` |
+| `--yolo` | `bypassPermissions` |
+| _(no flag)_ | `bypassPermissions` (default) |
+
+Use the resolved mode as the `mode` parameter when dispatching the subagent in Step 2A/2B.
+
+## Step 1: Resolve Each Reference
+
+For each issue/PR reference in the input, resolve its state. Run these lookups in parallel when there are multiple references.
+
+```bash
+# Issue → PR (check multiple closing keyword variants)
+gh pr list --search "Resolves #<issue_number>" --json number,url,state --limit 5
+gh pr list --search "Fixes #<issue_number>" --json number,url,state --limit 5
+gh pr list --search "Closes #<issue_number>" --json number,url,state --limit 5
+
+# PR → Issue
+gh pr view <pr_number> --json body | jq -r '.body' | grep -oiE '(resolves|fixes|closes) #[0-9]+' | grep -oE '[0-9]+'
+```
+
+| State | Action |
+|-------|--------|
+| Issue exists, no PR | **Initial Fix** (Step 2A) |
+| Issue exists, open PR found | **Follow-up** (Step 2B) |
+| PR provided directly | **Follow-up** (Step 2B) |
+
+## Step 2: Dispatch Subagents
+
+Dispatch one subagent per reference. When there are multiple references, dispatch all subagents in a single message (parallel execution).
+
+### 2A: Initial Fix
+
+```
+Agent(
+  mode: "<resolved_mode>",
+  isolation: "worktree",
+  name: "bugfix-<issue_number>",
+  description: "PPL bugfix #<issue_number>",
+  prompt: "Read .claude/harness/ppl-bugfix-harness.md and follow it to fix GitHub issue #<issue_number>.
+           Follow Phase 0 through Phase 3 in order.
+           Phase 0.3 defines TDD execution flow. Do NOT skip any phase.
+           CRITICAL: If Phase 0.1 determines the bug is already fixed on main, HARD STOP.
+           Do NOT write tests, do NOT create a PR — just comment/close the issue and report back.
+           If the bug IS reproducible, post the Decision Log (Phase 3.4) before completing."
+)
+```
+
+### 2B: Follow-up
+
+Before dispatching, check if an existing worktree already has the PR branch checked out:
+
+```bash
+# List worktrees and find one on the PR branch
+for wt in .claude/worktrees/agent-*/; do
+  branch=$(git -C "$wt" branch --show-current 2>/dev/null)
+  if [ "$branch" = "<pr_branch>" ]; then
+    echo "REUSE: $wt (branch: $branch)"
+  fi
+done
+```
+
+**If existing worktree found**: Do NOT use `isolation: "worktree"`. Pass the worktree path in the prompt so the subagent works there directly.
+
+```
+Agent(
+  mode: "<resolved_mode>",
+  name: "bugfix-<issue_number>",
+  description: "PPL bugfix #<issue_number> followup",
+  prompt: "cd <worktree_path> first, then read .claude/harness/ppl-bugfix-followup.md and follow it.
+           PR: <pr_number> (<pr_url>), Issue: #<issue_number>
+           Working directory: <worktree_path>"
+)
+```
+
+**If no existing worktree**: Create a new one.
+
+```
+Agent(
+  mode: "<resolved_mode>",
+  isolation: "worktree",
+  name: "bugfix-<issue_number>",
+  description: "PPL bugfix #<issue_number> followup",
+  prompt: "Read .claude/harness/ppl-bugfix-followup.md and follow it.
+           PR: <pr_number> (<pr_url>), Issue: #<issue_number>"
+)
+```
+
+## Step 3: Report Back
+
+After all subagents complete, report a summary for each:
+- Classification, fix summary, PR URL, worktree path and branch, items needing human attention (2A)
+- What was addressed, current PR state, whether another round is needed (2B)
+
+**Always include the worktree→PR mapping** from the subagent's output, e.g.:
+
+```
+Worktree: /path/to/.claude/worktrees/agent-xxxx
+Branch: bugfix-1234
+PR: #5678
+```
+
+**Important**: After reporting, the main agent must remember this mapping. When the user later asks to make changes to the PR (e.g., "commit this to PR #5678"), operate in the worktree directory — not the main session directory.
+
+## Subagent Lifecycle
+
+Subagents are task-scoped. They complete and release context — they cannot poll for events.
+
+```
+Agent A (Phase 0-3) → creates PR → completes
+  (CI runs, reviewers comment, conflicts arise)
+Agent B (Phase 3.5) → handles feedback → completes
+  (repeat as needed)
+Agent N (Phase 3.5) → gh pr ready → done
+```
+
+Context is preserved across agents via:
+- **Decision Log** (PR comment) — single source of truth for rejected alternatives, pitfalls, design rationale
+- **GitHub state** (PR diff, review comments, CI logs) — reconstructed by each follow-up agent
+
+## Rules
+
+- Subagent reads `.claude/harness/ppl-bugfix-harness.md` and fetches issue/PR details itself — do NOT inline content into the prompt
+- If bug is not reproducible (Phase 0.1), stop and report — do not proceed
+- Issue ↔ PR auto-resolution means the user never needs to track PR numbers manually
+- **Do NOT use `mode: "auto"` for subagents** — `auto` mode does not work for subagents; Bash commands still require manual approval. Only `bypassPermissions` reliably skips permission checks.
+- **Always dispatch subagent** — even for trivial follow-ups (remove co-author, force push). Do NOT run commands directly in the main session; subagents with `bypassPermissions` skip permission prompts, the main session does not.
@@ -0,0 +1,125 @@
+# PPL Bugfix Follow-up
+
+## Rules
+
+- Do NOT add `Co-Authored-By` lines in commits — only DCO `Signed-off-by`
+
+---
+
+## Report Working Directory
+
+```bash
+echo "Worktree: $(pwd)"
+echo "Branch: $(git branch --show-current)"
+```
+
+Include this in your output so the caller knows where changes are happening.
+
+## Reconstruct Context
+
+First checkout the PR branch, then load state:
+
+```bash
+# Checkout the PR branch in this worktree
+gh pr checkout <pr_number>
+
+# Resolve fork remote — the worktree may only have origin (upstream)
+git remote -v
+# If no fork remote exists, add it:
+git remote add fork https://github.com/<fork_owner>/sql.git
+
+# Load PR state — reviews, CI, mergeability
+gh pr view <pr_number> --json title,body,state,reviews,statusCheckRollup,mergeable
+gh pr checks <pr_number>
+
+# Load ALL comments — includes bot comments (Code-Diff-Analyzer, PR Reviewer Guide, Code Suggestions) and human comments
+gh pr view <pr_number> --json comments --jq '.comments[] | {author: .author.login, body: .body}'
+```
+
+Categorize ALL signals — not just CI and human reviews:
+
+| Signal | Type |
+|--------|------|
+| `statusCheckRollup` has failures | CI failure |
+| `reviews` has CHANGES_REQUESTED | Review feedback |
+| `mergeable` is CONFLICTING | Merge conflict |
+| Bot comments with actionable suggestions | Review feedback (treat like human review) |
+| All pass + approved | Ready — run `gh pr ready` |
+
+## Handle Review Feedback
+
+For each comment (human OR bot), **cross-check against the Decision Log first**:
+
+| Type | Action |
+|------|--------|
+| Code change | If already rejected in Decision Log, reply with reasoning. Otherwise make the change, new commit, push |
+| Question | Reply with explanation — Decision Log often has the answer |
+| Nit | Fix if trivial |
+| Disagreement | Reply with Decision Log reasoning; if reviewer insists, escalate to user |
+
+```bash
+git add <files> && git commit -s -m "Address review feedback: <description>"
+git push -u fork <branch_name>
+```
+
+## Clean Up Commit History
+
+When you need to amend a commit (e.g. remove Co-Authored-By, reword message) and the branch has a merge commit on top, don't try `git reset --soft origin/main` — it will include unrelated changes if main has moved. Instead cherry-pick the fix onto latest main:
+
+```bash
+git checkout -B clean-branch origin/main
+git cherry-pick <fix_commit_sha>
+git commit --amend -s -m "<updated message>"
+git push fork clean-branch:<pr_branch> --force-with-lease
+```
+
+## Handle CI Failures
+
+```bash
+gh pr checks <pr_number>                  # Identify failures
+gh run view <run_id> --log-failed         # Read logs
+# Test failure → fix locally, push new commit
+# Spotless → ./gradlew spotlessApply, push
+# Flaky → gh run rerun <run_id> --failed
+```
+
+## Handle Merge Conflicts
+
+```bash
+git fetch origin && git merge origin/main  # Resolve conflicts
+./gradlew spotlessApply && ./gradlew test && ./gradlew :integ-test:integTest  # Re-verify
+git commit -s -m "Resolve merge conflicts with main"
+git push -u fork <branch_name>
+```
+
+## Mark Ready
+
+```bash
+gh pr ready <pr_number>
+```
+
+## Retrospective
+
+After handling follow-up, reflect on the feedback received and check if it reveals gaps in the harness or command:
+
+For each comment addressed (bot or human):
+- **Does the feedback point to a pattern the harness should have prevented?** → Add guidance to the relevant Phase in `ppl-bugfix-harness.md`
+- **Was this a repeated mistake across PRs?** → Add to Quick Reference or Case Index
+- **Did the harness template produce the problematic code?** → Fix the template directly
+- **Was a permission or tool missing?** → Add to `.claude/settings.json`
+- **Did the follow-up workflow itself miss this signal?** → Update this file
+
+If any improvement is needed, make the edit and include it in the same commit.
+
+## Completion Gate
+
+Before reporting "done":
+
+1. Run `git status --porcelain` — if any uncommitted changes remain, commit and push them. This includes harness edits from Retrospective.
+2. Report in your final output:
+
+```
+Worktree: <absolute path>
+Branch: <branch name>
+PR: <pr_number>
+```