Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
refactor(skills): extract inline workflow prompts into skill files (#1535)
Maximilian Roos880a787d305d
diff --git a/.claude/skills/fix-ci/SKILL.md b/.claude/skills/fix-ci/SKILL.mdnew file mode 100644index 000000000..dc0985849--- /dev/null+++ b/.claude/skills/fix-ci/SKILL.md@@ -0,0 +1,68 @@+---+name: fix-ci+description: Debug and fix failing CI on main. Use when CI or docs workflow fails on main branch.+argument-hint: "[run-id and context]"+metadata:+ internal: true+---++# Fix CI on Main++CI has failed on the main branch. Diagnose the root cause, fix it, and create+a PR.++**Failed run:** $ARGUMENTS++## Workflow++### 1. Check for existing fixes++```bash+gh pr list --state open --label "automated-fix" --json number,title,headRefName+gh pr list --state open --head "fix/ci-" --json number,title,headRefName+```++If an existing PR addresses the same failure, comment on it linking the new run+and stop.++### 2. Diagnose and fix++1. Get failure logs: `gh run view <run-id> --log-failed`+2. Identify the failing job and root cause β don't just fix the symptom+3. Search for the same pattern elsewhere in the codebase+4. Reproduce locally using test commands from CLAUDE.md+5. Fix at the right level (shared helper > per-file fix)++### 3. Create PR++Re-check for existing fix PRs (one may have been created while you worked).++```bash+git checkout -b fix/ci-<run-id>+git add <files>+git commit -m "fix: <description>++Co-Authored-By: Claude <[email protected]>"+git push -u origin fix/ci-<run-id>+```++Create the PR with `gh pr create --label "automated-fix"`. PR body format:++```+## Problem+[What failed and the root cause]++## Solution+[What was fixed and why this is the right level]++## Testing+[How the fix was verified]++---+π€ Automated fix for [failed run](run-url)+```++### 4. Monitor CI++Poll CI using the approach from `/running-in-ci`. If CI fails, diagnose with+`gh run view <run-id> --log-failed`, fix, commit, push, and repeat.diff --git a/.claude/skills/nightly-cleaner/SKILL.md b/.claude/skills/nightly-cleaner/SKILL.mdnew file mode 100644index 000000000..2264d413e--- /dev/null+++ b/.claude/skills/nightly-cleaner/SKILL.md@@ -0,0 +1,94 @@+---+name: nightly-cleaner+description: Nightly code quality sweep β resolves bot PR conflicts, reviews recent commits, surveys existing code, and closes resolved issues.+metadata:+ internal: true+---++# Nightly Code Quality Sweep++Three phases: resolve conflicts on bot PRs, review recent commits, and survey+a slice of existing code/docs.++## Step 1: Resolve conflicts on bot PRs++```bash+gh pr list --author worktrunk-bot --json number,title,mergeable,headRefName \+ --jq '.[] | select(.mergeable == "CONFLICTING")'+```++For each conflicted PR, dispatch a subagent to:++1. Check out the PR: `gh pr checkout <number>`+2. Merge main: `git merge origin/main`+3. Resolve conflicts (read files, understand both sides), `git add`,+ `git commit --no-edit`+4. Push and poll CI using the approach from `/running-in-ci`+5. If conflicts are too complex, `git merge --abort` and comment explaining+ manual resolution is needed++Run subagents in parallel. Each must work in isolation+(`git worktree add /tmp/pr-<number> <branch>`). After all complete, clean up+temp worktrees and `git checkout main`.++Skip if no PRs have conflicts.++## Step 2: Review recent commits++```bash+git log --since='24 hours ago' --oneline main+```++If no commits in the past 24 hours, skip to Step 4.++Get the aggregate diff:++```bash+OLDEST=$(git log --since='24 hours ago' --format='%H' main | tail -1)+git diff ${OLDEST}^..HEAD+git log --since='24 hours ago' --format='%h %s' main+```++Review for: bugs, inconsistencies with existing patterns, missing/outdated+documentation (does `--help` still match?), missing test coverage, dead code,+non-canonical patterns, CLAUDE.md/skill drift.++## Step 3: Check existing issues and close resolved ones++```bash+gh issue list --state open --json number,title+gh pr list --state open --json number,title,headRefName+```++For each open issue, check whether recent commits already resolve it. If+resolved, comment briefly and close with `gh issue close`. Skip feature+requests, discussions, and partially unresolved issues.++## Step 4: Rolling survey++Run `.github/scripts/todays-survey-files.sh` for today's file list (~10 files).++For each file, look for: bugs, stale documentation, dead code, simplification+opportunities, missing tests, CLAUDE.md/skill drift. Spend roughly equal time+per file.++## Step 5: Report findings++Before creating issues, check for duplicates:++```bash+gh issue list --state open --label nightly-cleanup --json number,title+```++For each finding (from both recent-commit review and rolling survey):++1. **Create a GitHub issue** with label `nightly-cleanup` β clear actionable+ title, include file location and suggested fix+2. **For confident fixes** (clear bugs, stale docs, obvious missing tests):+ branch `nightly/clean-$GITHUB_RUN_ID`, fix, test+ (`cargo run -- hook pre-merge --yes`), commit, push, create PR, poll CI++## Step 6: Summary++Report: commits reviewed, files surveyed, findings, actions taken, assessment+(clean / minor issues / needs attention).diff --git a/.claude/skills/review-reviewers/SKILL.md b/.claude/skills/review-reviewers/SKILL.mdnew file mode 100644index 000000000..4a95ed0ba--- /dev/null+++ b/.claude/skills/review-reviewers/SKILL.md@@ -0,0 +1,86 @@+---+name: review-reviewers+description: Hourly analysis of Claude CI session logs β identifies behavioral problems, skill gaps, and workflow issues.+metadata:+ internal: true+---++# Review Reviewers++Analyze Claude-powered CI runs from the past hour. Identify behavioral problems,+skill gaps, and workflow issues β then create PRs or issues to fix them.++## Step 1: Find recent runs++Run `.github/scripts/list-recent-runs.sh` for recently completed Claude CI runs.+If empty, report "no runs to review" and exit.++## Step 2: Download and analyze session logs++```bash+gh run download <run-id> --name claude-session-logs --dir /tmp/logs/<run-id>/+```++Skip runs without artifacts. Find JSONL files under `/tmp/logs/` and extract:++```bash+# Tool calls+jq -c 'select(.type == "assistant") | .message.content[]? |+ select(.type == "tool_use") | {tool: .name, input: .input}' < file.jsonl++# Assistant reasoning+jq -r 'select(.type == "assistant") | .message.content[]? |+ select(.type == "text") | .text' < file.jsonl+```++Trace decision chains: what did Claude decide, what evidence did it use, what+was the outcome?++## Step 3: Cross-check review sessions++For `claude-review` runs, compare what the bot said against what happened next:++```bash+HEAD_BRANCH=$(gh run view <run-id> --json headBranch --jq '.headBranch')+PR_NUMBER=$(gh pr list --head "$HEAD_BRANCH" --state all --json number --jq '.[0].number')+```++Check for subsequent commits that undid something the bot approved (gap in+review), and human review comments flagging issues the bot missed. Pull in the+full PR context β not just changes from the past hour.++CI polling time is expected and acceptable β do not flag it.++## Step 4: Deduplicate++Before creating issues or PRs, check exhaustively for existing ones:++```bash+gh issue list --state open --label claude-behavior --json number,title,body+gh issue list --state open --json number,title,body # also check unlabeled issues+gh pr list --state open --json number,title,headRefName,body+gh issue list --state closed --label claude-behavior --json number,title,closedAt --limit 30+```++Search titles AND bodies for related keywords. Only comment on existing issues+if you have material new cases that would change the approach or increase+prioritization. Do not comment with progress updates, fix-PR status, or+re-statements of evidence already in the issue.++## Step 5: Act on findings++**Prefer PRs over issues.** A PR with a clear description is immediately+actionable.++- **PR** (default): Branch `hourly/review-$GITHUB_RUN_ID`, fix, commit, push,+ create with label `claude-behavior`. Put full analysis in PR description (run+ ID, log excerpts, root cause). Don't also create a separate issue.+- **Issue** (fallback): Only for problems too large or ambiguous to fix+ directly. Include run ID, log excerpts, root cause analysis.++Group multiple findings by broad theme.++## Step 6: Summary++If no problems found, report "all clear" with: runs analyzed, sessions reviewed,+brief quality assessment.diff --git a/.claude/skills/running-in-ci/SKILL.md b/.claude/skills/running-in-ci/SKILL.mdindex c69a843f6..5c0ec0a6d 100644--- a/.claude/skills/running-in-ci/SKILL.md+++ b/.claude/skills/running-in-ci/SKILL.md@@ -38,77 +38,44 @@ comments.## PR Creation-When the triggering comment asks for a PR (e.g., "make a new PR", "open a PR",-"create a PR"), create it directly with `gh pr create`. The comment is the-user's explicit request β don't downgrade it to a compare link.+When asked to create a PR, use `gh pr create` directly.-### Before creating a PR--**Check for existing work.** Before creating a new branch or PR, check whether-someone (including the bot) has already opened a PR for the same issue or topic:+Before creating a branch or PR, check for existing work:```bash-# Check open PRs β look for related titles and branchesgh pr list --state open --json number,title,headRefName --jq '.[] | "#\(.number) [\(.headRefName)]: \(.title)"'--# Check for fix branchesgit branch -r --list 'origin/fix/*'```-If an existing PR addresses the same problem, work on that PR instead of-creating a duplicate. Comment on the existing PR or the issue linking to it.+If an existing PR addresses the same problem, work on that PR instead.## Pushing to PR Branches-**Always use `git push` without specifying a remote.** The workflow uses-`gh pr checkout` which configures branch tracking to the correct remote β-including for fork PRs. Specifying `origin` explicitly bypasses this and can-push to the wrong place.--If pushing fails (e.g., fork PR with "Allow edits from maintainers" disabled),-fall back to posting suggested changes as code snippets in a comment.+Always use `git push` without specifying a remote β `gh pr checkout` configures+tracking to the correct remote, including for fork PRs. Specifying `origin`+explicitly can push to the wrong place.-When posting code from work you did locally, do not reference commit SHAs from-temporary or deleted branches β those links will 404. Post the code inline-instead.+If pushing fails (fork PR with edits disabled), fall back to posting code+snippets in a comment. Don't reference commit SHAs from temporary branches β+post code inline.## CI Monitoring-After pushing changes to a PR branch, you **must** wait for CI before saying-"done" or reporting completion. A push without green CI is not finished work.--1. Push your changes-2. Run `gh pr checks <number> --required` once-3. If checks are still running, poll with `gh pr checks <number> --required`- every 60 seconds until all required checks complete (this may take up to- 10 minutes). Non-required checks (e.g., benchmarks) are ignored β do not- wait for them.-4. If a required check fails, diagnose with `gh run view <run-id> --log-failed`,- fix issues, commit, push, and repeat from step 2-5. After all required checks pass, also check `codecov/patch`. Although it is- marked non-required in GitHub, this repo treats it as mandatory (see- CLAUDE.md). Run `gh pr checks <number>` (without `--required`) and look for- the `codecov/patch` row. If it hasn't completed yet, continue polling every- 60 seconds. If it fails, investigate and fix the coverage gap before- reporting completion.-6. Only after all required checks **and** `codecov/patch` pass, report- completion--**Never** post a "done" or "fixed" comment before CI passes. Local tests alone-are not sufficient β CI runs on Linux, Windows, and macOS. If you report-completion and CI later fails, the user has to come back and ask you to fix it-again.+After pushing, wait for CI before reporting completion.-Avoid `gh run watch` and `gh pr checks --watch` β both can hang indefinitely.-Use the poll loop above instead, which has a natural bound on CI completion-time.+1. Poll `gh pr checks <number> --required` every 60 seconds until all required+ checks complete (up to ~10 minutes). Ignore non-required checks (benchmarks).+2. If a required check fails, diagnose with `gh run view <run-id> --log-failed`,+ fix, commit, push, repeat.+3. After required checks pass, also poll `codecov/patch` via+ `gh pr checks <number>` (without `--required`) β this repo treats it as+ mandatory despite being marked non-required. Fix coverage gaps if it fails.+4. Report completion only after all required checks **and** `codecov/patch` pass.-### Verifying local test failures before pushing+Never report "done" before CI passes β CI runs on Linux, Windows, and macOS.+Avoid `gh run watch` and `gh pr checks --watch` β both can hang indefinitely.-When running local tests before pushing and some tests fail, do **not**-characterize them as "pre-existing" or "environment-dependent" without-evidence. The same grounded-analysis rule from the Thoroughness section applies-here β check main branch CI history before dismissing failures:+Before dismissing local test failures as "pre-existing", check main branch CI:```bashgh api "repos/{owner}/{repo}/actions/runs?branch=main&status=completed&per_page=3" \@@ -116,15 +83,13 @@ gh api "repos/{owner}/{repo}/actions/runs?branch=main&status=completed&per_page=```If you cannot verify, say "I haven't confirmed whether these failures are-pre-existing" rather than asserting they are.+pre-existing."## Replying to Comments-Prefer replying in context rather than creating a new top-level comment:+Reply in context rather than creating new top-level comments:-- **Inline review comments** (URLs containing `#discussion_r`): Reply in the- review thread using `gh api`, not as a top-level conversation comment. Use the- review comment ID from the prompt:+- **Inline review comments** (`#discussion_r`): Reply in the review thread:```bashcat > /tmp/reply.md << 'EOF'Your response here@@ -132,50 +97,15 @@ Prefer replying in context rather than creating a new top-level comment:gh api repos/{owner}/{repo}/pulls/{number}/comments/{comment_id}/replies \-F body=@/tmp/reply.md```- This keeps the discussion co-located with the code it references.-- **Conversation comments** (URLs containing `#issuecomment-`): Post a regular- comment β GitHub doesn't support threading for these, so a new comment is- correct.+- **Conversation comments** (`#issuecomment-`): Post a regular comment (GitHub+ doesn't support threading).## Comment Formatting-Keep comments concise. Put detailed analysis inside `<details>` tags with a-short summary. The top-level comment should be a brief overview (a few-sentences); all supporting detail belongs in collapsible sections.--Use `<details>` tags when a comment has supporting detail that isn't the main-point β multi-section analyses, diagnostic breakdowns, or supplementary context-around a short conclusion. The reader should get the gist without expanding.-Don't collapse content that *is* the answer: if someone asked for a survey or-detailed analysis, the full response is the substance, not boilerplate, and-should stay inline.--### Use Links--When referencing files, issues, PRs, or docs, always use markdown links so-readers can click through β never leave them as plain text.--Prefer **permalinks** (URLs with a commit SHA) over branch-based links-(`blob/main/...`). Permalinks stay valid even when files move or lines shift.-This is especially important for line references β a `blob/main/...#L42` link-breaks as soon as the line numbers change. On GitHub, pressing `y` on any file-view copies the permalink.--- **Repository files** β link to the file on GitHub:- [`docs/content/hook.md`](https://github.com/max-sixty/worktrunk/blob/main/docs/content/hook.md),- not just `docs/content/hook.md`-- **Issues and PRs** β use `#123` shorthand (GitHub auto-links these)-- **Specific lines** β link with a line fragment:- [`src/cli/mod.rs#L42`](https://github.com/max-sixty/worktrunk/blob/main/src/cli/mod.rs#L42)-- **External resources** β always use `[text](url)` format--For file-level links, `blob/main/...` is acceptable since file paths are stable.-For **line references**, always use a permalink with a commit SHA-(`blob/<sha>/...#L42`) β line numbers shift frequently and branch-based line-links go stale fast.--Example:+Keep comments concise. Put supporting detail inside `<details>` tags β the+reader should get the gist without expanding. Don't collapse content that *is*+the answer (e.g., a requested analysis).```<details><summary>Detailed findings (6 files)</summary>@@ -185,37 +115,38 @@ Example:</details>```-Do not add job links, branch links, or other footers at the bottom of your-comment. `claude-code-action` automatically adds these to the comment header.-Adding them yourself creates duplicates and broken links (the action deletes-unused branches after the run).+Always use markdown links for files, issues, PRs, and docs. Prefer permalinks+(commit SHA URLs) over branch-based links for line references β line numbers+shift and `blob/main/...#L42` links go stale.++- **Files**: link to GitHub (`blob/main/...` for file-level,+ `blob/<sha>/...#L42` for lines)+- **Issues/PRs**: `#123` shorthand+- **External**: `[text](url)` format-## Shell Quoting in `gh` Commands+Don't add job links or footers β `claude-code-action` adds these automatically.-Shell expansion corrupts `$` and `!` in command arguments. **This is a Claude-Code bug** β bash history expansion mangles `!` in double-quoted strings (e.g.,-`format!` becomes `format\!`) and it's the most common source-of broken bot comments.+## Shell Quoting-**Rule: always use a temp file for comment/reply bodies and other shell-sensitive-arguments.** Never pass the body directly as a `-f body="..."` argument.+Shell expansion corrupts `$` and `!` in arguments (bash history expansion+mangles `!` in double-quoted strings). Always use a temp file for comment bodies+and shell-sensitive arguments:```bash-# Posting a comment β ALWAYS use a file+# Comments β ALWAYS use a filecat > /tmp/comment.md << 'EOF'Fixed β the `format!` macro needed its arguments on separate lines.-CI is now green across all platforms.EOFgh pr comment 1286 -F /tmp/comment.md-# Replying to a review comment β ALWAYS use a file+# Review replies β ALWAYS use a filecat > /tmp/reply.md << 'EOF'Good catch! Updated to use `assert_eq!` instead.EOFgh api repos/{owner}/{repo}/pulls/{number}/comments/{id}/replies \-F body=@/tmp/reply.md-# GraphQL with $ β write query to a file, pass with -F+# GraphQL β write query to a filecat > /tmp/query.graphql << 'GRAPHQL'query($owner: String!, $repo: String!) { ... }GRAPHQL@@ -228,21 +159,14 @@ EOFgh api ... --jq "$(cat /tmp/jq_filter)"```-**Key details:**-- Use `<< 'EOF'` (single-quoted delimiter) to prevent all shell expansion-- Use `-F body=@/tmp/reply.md` (capital `-F` with `@` prefix) to read from file-- For `gh pr comment` and `gh issue comment`, use `-F /tmp/comment.md` (the- `-F` flag reads body from file)+Use `<< 'EOF'` (single-quoted delimiter) to prevent expansion. For file-based+bodies: `gh pr comment` uses `-F /tmp/file` (path directly), while `gh api`+uses `-F body=@/tmp/file` (field assignment with `@` prefix).## Keeping PR Titles and Descriptions Current-When you revise a PR's code in response to review feedback, check whether the-title and description still accurately describe the changes. If the approach-changed (e.g., from "exclude all X" to "add targeted exclusions for X"), update-the title and body to match. A reviewer reading the description before the diff-should not be confused by stale framing.--Use the GitHub API to update:+When revising code after review feedback, update the title and description if+the approach changed:```bashgh api repos/{owner}/{repo}/pulls/{number} -X PATCH \@@ -251,37 +175,21 @@ gh api repos/{owner}/{repo}/pulls/{number} -X PATCH \## Atomic PRs-When creating PRs, split unrelated changes into separate PRs β one concern per-PR. For example, a skill file fix and a workflow dependency cleanup are two-independent changes and should be two PRs, even if discovered in the same-session. This makes PRs easier to review, revert, and bisect.--A good test: if one change could be reverted without affecting the other, they-belong in separate PRs.+Split unrelated changes into separate PRs β one concern per PR. If one change+could be reverted without affecting the other, they belong in separate PRs.## Investigating Other CI Runs-When asked to diagnose what a bot did in a previous CI run, the primary evidence-is the session log artifact β not the console output. Console output-(`gh run view <id> --log`) contains only workflow boilerplate because-`show_full_output` defaults to `false`. The actual conversation is in the-artifact.--### Downloading session logs--All Claude workflows upload session logs as artifacts named-`claude-session-logs`. Download with:+The primary evidence for diagnosing bot behavior is the session log artifact β+not console output (`show_full_output` defaults to `false`).```bashgh run download <run-id> -n claude-session-logs -D /tmp/session-logs-<run-id>```-The artifact contains JSONL files under a path like-`-home-runner-work-worktrunk-worktrunk/<session-id>.jsonl`.--### Parsing session logs--Each JSONL line is a message with a `type` field (`user`, `assistant`, `system`).+The artifact contains JSONL files (path like+`-home-runner-work-worktrunk-worktrunk/<session-id>.jsonl`). Each line has a+`type` field (`user`, `assistant`, `system`).```bash# Skills loaded@@ -298,9 +206,7 @@ jq -r 'select(.type == "assistant") | .message.content[]? |select(.type == "text") | .text' <FILE>.jsonl```-### Finding the right run--Multiple workflows may trigger on the same event. Use the event type to narrow:+Find the right run among multiple workflows:```bashgh api 'repos/{owner}/{repo}/actions/runs?per_page=30' \@@ -308,7 +214,7 @@ gh api 'repos/{owner}/{repo}/actions/runs?per_page=30' \{id, name, event, head_branch, created_at, conclusion}'```-Check which runs have artifacts before downloading:+Check for artifacts before downloading:```bashgh api repos/{owner}/{repo}/actions/runs/<run-id>/artifacts \@@ -319,43 +225,23 @@ Review-response runs triggered by `pull_request_review` or`pull_request_review_comment` events sometimes produce no artifact when thesession is very short.-## Thoroughness β Grounded Analysis--CI runs are not interactive chat. There is no back-and-forth β the user reads-your output after the session ends. Every claim must be grounded in evidence you-actually examined.--- **Do the work, don't speculate.** If you have access to logs, code, or API- data, read it before drawing conclusions. "This suggests X may be the cause"- is not acceptable when you can check whether X is actually the cause.-- **Never claim a CI failure is "pre-existing" or "unrelated" without- evidence.** Before characterizing any failure this way, check main branch CI- history (e.g., `gh api "repos/{owner}/{repo}/actions/runs?branch=main&status=completed&per_page=5"`)- to verify the same test fails there. If you cannot verify, say "I haven't- confirmed whether this is pre-existing" rather than asserting it is.-- **Show evidence.** Cite specific log lines, file paths, commit SHAs, or API- responses. A conclusion without evidence is speculation.-- **Trace causation, don't guess at correlation.** If two things co-occur, find- the mechanism β don't say "this may be related."-- **Distinguish what you verified from what you inferred.** If you couldn't- verify something (e.g., logs weren't available), say so explicitly rather than- hedging with "may" or "suggests."-- **Check artifacts, not just console logs.** Console output from Claude runs is- hidden by default. Session log artifacts are the primary evidence source β see- "Investigating Other CI Runs" above.--The user can't ask follow-up questions in the same session. Treat every response-as your final answer.+## Grounded Analysis++CI runs are not interactive β every claim must be grounded in evidence. The user+can't ask follow-up questions; treat every response as your final answer.++Read logs, code, and API data before drawing conclusions. Show evidence: cite+log lines, file paths, commit SHAs. Trace causation β if two things co-occur,+find the mechanism rather than saying "this may be related." Never claim a+failure is "pre-existing" without checking main branch CI history. Distinguish+what you verified from what you inferred.## Tone-You are a helpful reviewer raising observations, not a manager assigning work.-Never create checklists or task lists for the PR author. Instead, note what you-found and let the author decide what to act on.+Raise observations, don't assign work. Never create checklists or task lists+for the PR author.## PR Review Comments-For PR review comments on specific lines (shown as `[Comment on path:line]` in-`<review_comments>`), ALWAYS read that file and examine the code at that line-before answering. The question is about that specific code, not the PR in-general.+For review comments on specific lines (`[Comment on path:line]`), read that file+and examine the code at that line before answering.diff --git a/.github/workflows/claude-ci-fix.yaml b/.github/workflows/claude-ci-fix.yamlindex 2d41a74a5..ff6e64692 100644--- a/.github/workflows/claude-ci-fix.yaml+++ b/.github/workflows/claude-ci-fix.yaml@@ -49,79 +49,12 @@ jobs:additional_permissions: |actions: read- # Provide Claude with context about the failure and instructionsprompt: |- CI has failed on main branch. Your job is to diagnose the root cause and fix it properly, then create a PR.-- ## Failed workflow information- - Run ID: ${{ github.event.workflow_run.id }}+ fix-ci ${{ github.event.workflow_run.id }}- Run URL: ${{ github.event.workflow_run.html_url }}- Commit: ${{ github.event.workflow_run.head_sha }}- Commit message: ${{ github.event.workflow_run.head_commit.message }}- ## Instructions-- 1. **Check for existing fix PRs**:- - Run `gh pr list --state open --label "automated-fix" --json number,title,body,headRefName` to see open fix PRs- - Also check `gh pr list --state open --head "fix/ci-"` for PRs on fix branches- - If an open PR already addresses this same failure (same root cause), STOP HERE:- - Comment on that PR: `gh pr comment NNN --body "Run ${{ github.event.workflow_run.id }} also failed with this issue β this PR should fix it."`- - Do not create a duplicate PR- - If no existing PR addresses this issue, continue-- 2. **Diagnose the failure**:- - Run `gh run view ${{ github.event.workflow_run.id }} --log-failed` to see the failure logs- - Identify which job(s) failed and why- - Look for specific error messages, test failures, or lint errors-- 3. **Find the root cause**:- - Don't just fix the symptom β investigate WHY the failure occurred- - Check if there's a shared helper, constant, or pattern that should be updated- - Look for similar code that might have the same issue- - Ask: "If this broke here, could it break elsewhere for the same reason?"-- 4. **Reproduce locally** using the test commands documented in CLAUDE.md-- 5. **Fix at the right level**:- - Fix the underlying cause, not just the immediate symptom- - If a value should be in a shared constant, add it there- - If a helper is missing functionality, extend the helper- - Avoid duplicating fixes across multiple files when a single shared fix would work-- 6. **Create a fix branch and PR**:- - BEFORE creating a PR, re-check for existing fix PRs (step 1) β one may have been created while you were working- - If an existing PR now addresses this issue, comment on it (as in step 1) and STOP- - Otherwise: create a new branch: `git checkout -b fix/ci-${{ github.event.workflow_run.id }}`- - Commit your changes with a clear message explaining the fix- - Push the branch: `git push -u origin fix/ci-${{ github.event.workflow_run.id }}`- - Create a PR with `gh pr create --label "automated-fix"`-- 7. **PR description format**:- ```- ## Problem- [What failed and the root cause]-- ## Solution- [What you fixed and why this is the right level to fix it]-- ## Alternatives considered- [If there were tradeoffs between a narrow fix vs broader fix, explain them here]- [Example: "Could also fix this by adding X to each test file individually, but fixing the shared helper prevents similar issues elsewhere"]-- ## Testing- [How you verified the fix]-- ---- π€ Automated fix for [failed run](${{ github.event.workflow_run.html_url }})- ```-- 8. **Iterate until CI passes**:- - After pushing, monitor CI with `gh run list --branch fix/ci-${{ github.event.workflow_run.id }}`- - Poll CI with `gh pr checks <number>` every 60 seconds until all checks complete- - If CI fails, diagnose with `gh run view <run-id> --log-failed`- - Fix issues, commit, push, repeat- - Don't return until CI passes or you've exhausted reasonable fixes-claude_args: |--model opus--allowedTools Bash,Edit,Read,Write,Glob,Grep,WebSearch,WebFetch,Task,Skilldiff --git a/.github/workflows/claude-hourly-review-reviewers.yaml b/.github/workflows/claude-hourly-review-reviewers.yamlindex 844c2d0dc..67ddfeeb7 100644--- a/.github/workflows/claude-hourly-review-reviewers.yaml+++ b/.github/workflows/claude-hourly-review-reviewers.yaml@@ -48,98 +48,7 @@ jobs:additional_permissions: |actions: read- prompt: |- You are running as an hourly job that reviews the behavior of all Claude-powered CI workflows from the past hour. Your goal is to identify behavioral problems, skill gaps, and workflow issues β then create issues and/or PRs to fix them.-- ## Step 1: Find recent Claude CI runs-- Run `.github/scripts/list-recent-runs.sh` to get a JSON array of recently completed Claude CI runs (filters out in-progress runs and keeps only those that finished in the past hour β see script comments for details).-- If the output is an empty array, report "no runs to review" and exit.-- ## Step 2: Download session logs-- For each run found, download the session log artifact:-- ```- gh run download <run-id> --name claude-session-logs --dir /tmp/logs/<run-id>/- ```-- Some runs may not have artifacts (e.g., skipped runs). That's fine β skip them.-- ## Step 3: Analyze session logs-- For each session log, analyze using jq extraction and gap analysis:- - Find JSONL files: `find /tmp/logs/ -name '*.jsonl' -type f`- - Extract conversation turns: `jq -c 'select(.type == "assistant" or .type == "tool_result")' < file.jsonl`- - Extract tool calls: `jq -c 'select(.type == "assistant") | .message.content[]? | select(.type == "tool_use") | {tool: .name, input: .input}' < file.jsonl`- - Look for tool calls, decisions, and outcomes- - Trace decision chains: what did Claude decide, what evidence did it use, what was the outcome?-- ## Step 4: Cross-check review sessions against PR outcomes-- For `claude-review` runs, compare what the bot said against what happened next on the PR. Get the PR number from the run's head branch:-- ```- HEAD_BRANCH=$(gh run view <run-id> --json headBranch --jq '.headBranch')- PR_NUMBER=$(gh pr list --head "$HEAD_BRANCH" --state all --json number --jq '.[0].number')- ```-- Then check:- - **Subsequent commits**: Were files removed, reverted, or fixed after the review? If the author undid something the bot approved without comment, the bot missed it.- - **Human review comments**: Did human reviewers flag issues the bot didn't? These are gaps in the review process.-- This is the strongest signal β it shows what the reviewer actually missed, not just whether it followed process.-- **Important**: Although you only look at runs from the past hour, always pull in the **full context** of the PR or issue when assessing a session. Read the complete PR description, all comments, all reviews, and all commits β not just the ones from the past hour. You need the full history to judge whether the bot's response was appropriate.-- ## Step 5: Identify problems-- Compare each session against CLAUDE.md and project conventions. Flag anything where Claude's behavior diverged from the guidelines or produced a poor outcome. Include findings from the cross-check in Step 4.-- **Not a problem:** CI polling time (waiting for checks to complete) is expected and acceptable, even if it takes 10-30 minutes. Do NOT flag sessions for spending time polling CI status. The `running-in-ci` skill instructs Claude to poll β this is working as intended.-- ## Step 6: Check for existing issues and PRs (deduplication)-- Because this job runs hourly, deduplication is critical. Before creating any new issue or PR, thoroughly check for existing ones that cover the same problem:-- ```- gh issue list --state open --label claude-behavior --json number,title,body- gh issue list --state open --json number,title,body- gh pr list --state open --json number,title,headRefName,body- ```-- For each finding, search issue titles AND bodies for related keywords. If an existing issue or PR already covers the same behavioral problem β even partially or with different wording β do NOT create a duplicate. Only comment on an existing issue if you have material new cases that would change the approach to fixing it or increase its prioritization (e.g., the same bug manifesting in a new workflow, or evidence that the impact is worse than originally reported). Do NOT comment with progress updates, fix-PR status, or re-statements of evidence already in the issue.-- Also check recently closed issues (past 7 days) to avoid re-filing problems that were already addressed:- ```- gh issue list --state closed --label claude-behavior --json number,title,closedAt --limit 30- ```-- ## Step 7: Act on findings-- Prefer PRs over issues. A PR with a clear description is more useful than an issue describing the same problem β it's immediately actionable and reviewable.-- **Default: Create a PR** for problems you can fix (skill edits, workflow tweaks, CLAUDE.md updates, prompt adjustments):- - Create a branch: `git checkout -b hourly/review-${{ github.run_id }}`- - Make the changes- - Commit and push- - Create a PR with label `claude-behavior`. Put the full analysis in the PR description: run ID, specific log excerpts, root cause, and what the fix does. The PR description replaces what would have been the issue body β make it thorough.- - Do NOT also create a separate issue. The PR is the issue.-- **Fallback: Create an issue** only for problems that are too large or ambiguous to fix directly β e.g., architectural concerns, unclear root causes, or changes that need maintainer judgment on the approach:- - Title: Clear description of the behavioral problem- - Body: Include the run ID, specific log excerpts showing the problem, analysis of root cause, and what makes it hard to fix directly- - Label: `claude-behavior`-- When you have multiple findings, group PRs by **broad theme**-- ## Step 8: Summary-- If no problems were found, report "all clear" with summary statistics:- - Number of runs analyzed- - Number of sessions reviewed- - Brief quality assessment+ prompt: review-reviewersclaude_args: |--model opusdiff --git a/.github/workflows/claude-nightly-cleaner.yaml b/.github/workflows/claude-nightly-cleaner.yamlindex f1e5db5c7..e49aeacbb 100644--- a/.github/workflows/claude-nightly-cleaner.yaml+++ b/.github/workflows/claude-nightly-cleaner.yaml@@ -50,148 +50,7 @@ jobs:additional_permissions: |actions: read- prompt: |- You are running as a nightly code quality sweep. Your job has three phases: resolve conflicts on bot PRs, review recent commits, and survey a slice of existing code/docs.-- ## Step 0: Resolve conflicts on bot PRs-- Check for open PRs authored by `worktrunk-bot` that have merge conflicts:-- ```- gh pr list --author worktrunk-bot --json number,title,mergeable,headRefName \- --jq '.[] | select(.mergeable == "CONFLICTING")'- ```-- If there are conflicted PRs, resolve each one using a subagent (use the Task tool). For each conflicted PR, dispatch a subagent with these instructions:-- 1. Check out the PR branch: `gh pr checkout <number>`- 2. Merge the default branch: `git merge origin/main`- 3. If there are conflicts, resolve them by reading the conflicting files, understanding both sides, and making the correct resolution. Use `git diff` and read the files to understand the conflict context. After resolving, `git add` the resolved files and `git commit --no-edit`.- 4. Push the result: `git push`- 5. Comment on the PR with a brief summary of what was resolved (e.g., `gh pr comment <number> --body "..."`).- 6. If the conflicts are too complex to resolve confidently, abort with `git merge --abort` and comment on the PR explaining that manual resolution is needed.- 7. After pushing, poll CI with `gh pr checks <number>` every 60 seconds until all checks complete. If CI fails, investigate and fix.-- Run subagents in parallel for independent PRs. Each subagent must work in an isolated directory to avoid checkout conflicts (e.g., `git worktree add /tmp/pr-<number> <branch>` or `git clone . /tmp/pr-<number>`). After all subagents complete, clean up temp directories and switch back to main before proceeding:-- ```- git checkout main- ```-- If no PRs have conflicts, skip this step.-- ## Step 1: Find recent commits-- ```- git log --since='24 hours ago' --oneline main- ```-- If no commits were merged in the past 24 hours, skip Steps 2β3 and continue with the- remaining steps (issue management, rolling survey, reporting).-- ## Step 2: Review the aggregate diff-- Get the oldest commit from the past 24 hours and review the full diff:-- ```- OLDEST=$(git log --since='24 hours ago' --format='%H' main | tail -1)- git diff ${OLDEST}^..HEAD- ```-- Also review the individual commit messages to understand intent:- ```- git log --since='24 hours ago' --format='%h %s' main- ```-- ## Step 3: Analyze the changes-- Review the changes for:-- 1. **Bugs or logic errors** in new code- 2. **Inconsistencies** with existing patterns in the codebase- 3. **Missing or outdated documentation**:- - Does `--help` still describe what the code does?- - Do CLAUDE.md instructions match current behavior?- 4. **Missing test coverage** for new code paths- 5. **Refactoring opportunities**:- - Duplicate code that should be shared- - Dead code that should be removed- - Non-canonical patterns (compatibility layers, parallel implementations)- 6. **CLAUDE.md or skill files** that need updating based on code changes-- ## Step 4: Check for existing issues-- Before creating any new issues, check for duplicates:- ```- gh issue list --state open --json number,title- ```-- Also check for any open PRs that already address the same files or issues:- ```- gh pr list --state open --json number,title,headRefName- ```-- ## Step 5: Close resolved issues-- For each open issue found in Step 4, check whether the recent commits (or earlier- unlinked merges) already resolve it. An issue is resolved when the code change it- describes has landed on main β look at the diff, linked PRs, and commit messages.-- For each resolved issue:- - Comment briefly explaining which commit or PR resolved it- - Close the issue with `gh issue close <number>`-- Skip issues that are feature requests, discussions, or still partially unresolved.-- ## Step 6: Rolling survey of existing code/docs-- Every day, a different slice of the repo is surveyed so that all code and docs- are reviewed on a 28-day cycle β not just recently changed files.-- Run `.github/scripts/todays-survey-files.sh` to get today's file list (typically ~10 files).- If the script outputs no files (shouldn't happen, but possible), skip this step.-- For each file, read it and look for:-- 1. **Bugs or latent issues** β logic errors, off-by-ones, race conditions, panics in fallible paths- 2. **Stale documentation** β comments, docstrings, or docs that no longer match behavior- 3. **Dead code** β unused functions, unreachable branches, obsolete feature flags- 4. **Simplification opportunities** β code that can be replaced by a simpler pattern,- unnecessary abstractions, duplicated logic that should be shared- 5. **Missing tests** β public functions or important branches with no test coverage- 6. **CLAUDE.md / skill drift** β do the project guidelines still match the code?-- This is a survey, not a line-by-line audit. Spend roughly equal time per file β- don't rabbit-hole on one file at the expense of others. Note findings and move on.-- Combine findings from this step with findings from the recent-commit review (Steps 1β3)- before proceeding to deduplication and reporting.-- ## Step 7: Report findings-- For each finding (from both recent-commit review and rolling survey):-- 1. **Create a GitHub issue** with label `nightly-cleanup`:- - Title: Clear, actionable description- - Body: Include the relevant commit(s) or file location (file:line), description of the problem, and suggested fix- - For survey findings, note the file path and what was found- - Use `gh issue create --label "nightly-cleanup"`-- 2. **For confident fixes** (clear bugs, obvious missing tests, stale docs):- - Create a branch: `git checkout -b nightly/clean-${{ github.run_id }}`- - Make the changes- - Run tests to verify: use the test commands from CLAUDE.md- - Commit and push- - Create a PR referencing the issue(s)- - Poll CI with `gh pr checks <number>` every 60 seconds until all checks complete-- ## Step 8: Summary-- Report a brief summary:- - Number of commits reviewed (recent-commit phase)- - Number of files surveyed (rolling survey phase)- - Findings and actions taken- - Assessment: clean / minor issues / needs attention+ prompt: nightly-cleanerclaude_args: |--model opus