Skip to content

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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
index 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 branches
gh pr list --state open --json number,title,headRefName --jq '.[] | "#\(.number) [\(.headRefName)]: \(.title)"'
-
-# Check for fix branches
git 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:
```bash
gh 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:
```bash
cat > /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 file
cat > /tmp/comment.md << 'EOF'
Fixed β€” the `format!` macro needed its arguments on separate lines.
-CI is now green across all platforms.
EOF
gh pr comment 1286 -F /tmp/comment.md
-# Replying to a review comment β€” ALWAYS use a file
+# Review replies β€” ALWAYS use a file
cat > /tmp/reply.md << 'EOF'
Good catch! Updated to use `assert_eq!` instead.
EOF
gh 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 file
cat > /tmp/query.graphql << 'GRAPHQL'
query($owner: String!, $repo: String!) { ... }
GRAPHQL
@@ -228,21 +159,14 @@ EOF
gh 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:
```bash
gh 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`).
```bash
gh 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:
```bash
gh 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:
```bash
gh 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 the
session 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.yaml
index 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 instructions
prompt: |
- 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,Skill
diff --git a/.github/workflows/claude-hourly-review-reviewers.yaml b/.github/workflows/claude-hourly-review-reviewers.yaml
index 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-reviewers
claude_args: |
--model opus
diff --git a/.github/workflows/claude-nightly-cleaner.yaml b/.github/workflows/claude-nightly-cleaner.yaml
index 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-cleaner
claude_args: |
--model opus