tobihagemann/turbo

# Apply Findings

Apply evaluated findings from the conversation context. Findings must have been through `/evaluate-findings` first.

## Step 1: Identify Findings

Collect all findings from the conversation context. Findings should have Verdict columns (Apply, Skip, Escalate) from `/evaluate-findings`.

If findings are unevaluated (raw output without verdicts), stop and say to run `/evaluate-findings` first.

## Step 2: Apply in File Order

Group Apply findings by file path and apply in file order to minimize context switching. For each finding:

# Assess Technical Debt

Surface the structural debt that routine review keeps out of scope: long-lived complexity, deprecated APIs, duplication, tangled architecture, and low-value tests that need deliberate refactoring. Project-wide, analysis-only. Ranks each finding by impact and effort and writes `.turbo/technical-debt.md` and `.turbo/technical-debt.html`.

## Task Tracking

At the start, use `TaskCreate` to create a task for each phase:

1. Scope and partition
2. Run debt analysis agents
3. Run `/evaluate-findings` skill
4. Resolve escalated findings
5. Rank and write markdown report
6. Generate HTML report

# Changelog Rules

The changelog is kept in `CHANGELOG.md` at the project root. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and projects using these conventions adhere to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## File Structure

```markdown
# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

# Code Style: Exist, Reuse, Mirror, Symmetry

When writing new code in an existing codebase, work through these in order. When two pull in different directions, the earlier one wins.

1. **Establish that the code needs to exist**: Drop work the request does not need — an abstraction with one implementation, a configuration point with one caller, a branch for a state the callers cannot reach, scaffolding for an anticipated requirement. Deleting or narrowing beats adding. Before removing code that already exists, trace its callers and confirm nothing depends on the behavior. A new test must earn its place too: before adding one, name the behavior it protects and the credible regression that makes it fail, and confirm no existing test already fails on that regression. When a mutation run checks the new test, read every test that fails under it, not only the new one: if existing tests also fail, keep the new test only for a regression they miss. When an existing test covers the same contract, extend its cases instead. Drive the test through a boundary production code already uses rather than adding an export, flag, or hook that only the test calls. A test pins the behavior it is named for: when one you add or change also covers another behavior only through how it is set up, give that behavior its own test unless another test already fails when it breaks, and set the first test up the way its siblings are. Input validation at trust boundaries, error handling that prevents data loss, security controls, accessibility affordances, and anything explicitly requested outrank this rule.
2. **Reuse existing code**: Before writing a new helper, check if an existing method can be reused or generalized. If a new helper is needed, model it after its closest sibling.
3. **Reuse existing patterns**: Find the closest analogous feature and replicate its structure (method decomposition, control flow, annotations, guard clauses). When an existing pattern fits, use it rather than introducing a new one. When following it would force materially more code or indirection than a different approach, take the different approach and apply it across the whole change.
4. **Mirror the surrounding code exactly**: Match brace style, comment style, naming conventions, blank line spacing, code density, and level of detail by reading nearby code first.
5. **Maintain symmetry**: If adding `fooB()` parallel to `fooA()`, match naming, parameter order, and structure. Symmetry covers every name the new sibling makes asymmetric: identifiers, route paths, config keys, event names, environment variables, CLI flags, and file naming schemes. Rename the existing name by default; keep it as it stands only when it is a published contract whose consumers you cannot update, or cannot update in step with the rename. Treat deployment and registration as costs the change absorbs: updating every place the name is referenced or registered is part of the change.
6. **Logical ordering**: Place new methods, switch cases, and fields in the order that mirrors the existing grouping or business lifecycle, rather than appending at the end.
7. **Default to no comment**: Write code that self-explains through naming, extraction, and structure. When you reach for a comment, first try refactoring so it becomes unnecessary. Add one only for a load-bearing constraint the code cannot express (a hidden invariant, a workaround, a non-obvious performance characteristic). When in doubt, omit it.

# Codex Exec

Autonomous task execution via the codex CLI. Runs non-interactively. Progress streams to stderr; final result on stdout.

```bash
codex exec --skip-git-repo-check "task description" < /dev/null
```

For large context, pipe it via stdin. The prompt stays as the argument, context is passed as `<stdin>` automatically:

```bash
cat context.txt | codex exec --skip-git-repo-check "question about the context"
```

# Commit Rules

## Commit Message Rules

- Match the style from `git log -n 10 --oneline`
- Concise and descriptive
- Imperative mood, present tense
- Aim for ≤100 characters in the subject
- No commit description—summarize everything in the message
- Don't reference `.turbo/` content (filenames, acceptance criteria, step numbers, headings) in commit messages. `.turbo/` is gitignored, so these references would be opaque to anyone reading without local copies.

## Technical Constraints

- Use `git commit -m "message"` directly—do not use heredoc syntax (sandbox blocks temp file creation)

# Commit Staged Changes

## Step 1: Run `/commit-rules` Skill

Run the `/commit-rules` skill to load commit message rules and technical constraints.

## Step 2: Commit

- Changes are already staged and ready to commit
- Do not stage any files
- Keep the current branch and commit on it, including when it is the default branch

# Commit and Push

## Step 1: Run `/commit-staged` Skill

Run the `/commit-staged` skill.

## Step 2: Push

Push to the current branch's remote:

```bash
git push
```

# Consult Codex

Multi-turn consultation with Codex CLI. Maintains a conversation across multiple turns using session persistence.

## Step 1: Gather Context

Identify the 2-5 files most relevant to the problem. Formulate a clear, specific question. Include what has been tried and relevant constraints.

## Step 2: Start Session

Run `codex exec` with `-o` to capture the response cleanly. Default to `-s read-only` for safety. Use `-s workspace-write` when the consultation requires running code, inspecting an artifact passed by path, or reading files outside the workspace, and tell Codex to keep any scratch files it writes under `.turbo/`. Pass the same `-s` value on every resume turn of the consultation: a resume turn takes its sandbox from its own command line, and without the flag it falls back to the codex config, where a trusted project runs workspace-write.

Omit `-m`, leaving the consultation on codex's configured model. When the user named a model for this consultation, add `-m <model>` to every `codex exec` command in this skill, resume turns included, and pass the name verbatim.

# Consult Oracle

Consult ChatGPT Pro via ChatGPT browser automation for problems that resist standard approaches.

## Configuration

The oracle reads from `~/.turbo/config.json`:

```json
{
  "oracle": {
    "chatgptUrl": "https://chatgpt.com/"
  }
}

# Context Level

Call the `mcp__context-level__read` tool and report its reading.

# Contribute Turbo

Propose an improvement to a turbo skill as an issue on `tobihagemann/turbo`.

## Step 1: Identify the Proposed Change

Confirm the local repo exists:

```bash
test -d ~/.turbo/repo
```

If it does not, tell the user to run the Turbo setup first and stop.

# Create Changelog

Create a changelog backfilled with version history.

## Step 1: Run `/changelog-rules` Skill

Run the `/changelog-rules` skill to load shared changelog conventions.

## Step 2: Check for Existing Changelog

Use `git rev-parse --show-toplevel` to find the repository root. Look for the changelog file per `/changelog-rules`. If it already exists, use `AskUserQuestion` to confirm overwriting it. If the user declines (chooses the free-form "Other" option or asks to abort), stop without running the remaining steps.

## Step 3: Backfill Version History

# Create Handoff

Write a session handoff file at `.turbo/handoff/<YYYY-MM-DD>-<slug>.md` so a fresh session can pick up where this one left off.

## Step 1: Resolve the Target Path

Get today's date: `date +%Y-%m-%d`.

Pick a slug for the current task:

- Lowercase
- Replace non-alphanumeric characters with hyphens
- Collapse consecutive hyphens
- Trim leading and trailing hyphens

# Create Issue

Draft a focused title and body for a GitHub issue, then file it. Bug reports state reproduction steps and observed versus expected behavior.

## Step 1: Gather Context

Determine what the issue is about from the conversation. When the subject is ambiguous, use `AskUserQuestion` to settle it before drafting.

List the repo's issue templates, read its labels, and search for an existing issue covering the same thing:

```bash
ls .github/ISSUE_TEMPLATE/ 2>/dev/null
gh label list --limit 100
gh issue list --search "<keywords>" --state all

# Create Pull Request

Draft a concise and descriptive title and a body for a PR. Explain the purpose of the changes, the problem they solve, and the general approach taken. When the changes involve clear runtime flows or state transitions, include Mermaid diagrams. When they add a user-facing surface or change how one looks, and this session already captured it, include screenshots.

## Step 1: Analyze Changes

If git is in a feature branch, examine all commit messages and the full diff to understand the overall changes. Analyze the diff for framing, diagram, and screenshot opportunities.

Source every claim about prior behavior from the base branch itself, by reading its code with `git show origin/<base>:<path>`. A long session leaves the working tree carrying intermediate states that were never the state this PR is measured against, and describing one of those as the prior behavior misleads the reviewer.

Before writing that two pull requests must land together, check whether the consumer uses what changed: `git grep <symbol>` in its checkout, or the other repository's working copy when the dependency crosses repositories. When it does, name the actual cause. When it does not, drop the landing-order claim and keep any reference to the related pull request as plain context. State the claim as unverified when the consumer is not reachable.

When the PR closes an issue, read the issue before drafting.

# Create Project Skills

Generates one skill per detected convention area in the project's skill directory so future Claude or Codex sessions auto-load them when working in the repo.

## Task Tracking

At the start, use `TaskCreate` to create a task for each phase:

1. Survey codebase
2. Extract patterns in parallel
3. Evaluate patterns
4. Propose skill list
5. Run `/create-skill` skill

# Create Skill

This skill guides the creation of effective skills. Authoring guidance is split across the reference files below. Read the ones the current step needs rather than all of them.

| Reference | Covers |
|---|---|
| [references/principles.md](references/principles.md) | Conciseness, instructions-not-documentation, degrees of freedom |
| [references/structure.md](references/structure.md) | Frontmatter, naming, descriptions, progressive disclosure, file layout |
| [references/writing.md](references/writing.md) | Prose rules: terminology, phrasing, conditions, thresholds |
| [references/workflows.md](references/workflows.md) | Step/phase structure, feedback loops, exit signals, output patterns |
| [references/composition.md](references/composition.md) | Depending on, invoking, and fanning out to other skills |
| [references/tools.md](references/tools.md) | Agent, Bash, AskUserQuestion, and MCP tool invocation |
| [references/evaluation.md](references/evaluation.md) | Evaluations and iterating on a skill from observed behavior |
| [references/scripts.md](references/scripts.md) | Skills that bundle executable code |

# Create Test Plan

Analyze what changed and generate a comprehensive test plan covering four escalating levels of testing depth.

## Step 1: Determine Scope

Resolve scope using the first match:

1. **User-specified** — the user says what to test. Use that.
2. **PR** — a PR URL or number is provided. Fetch the PR details (title, description, changed files, comments) and read the changed code.
3. **Conversation context** — prior conversation contains recent work (a feature, fix, or refactor). Extract what changed, where it lives, and expected behavior.
4. **App-level discovery** — fresh context with no prior work. Examine the project (entry points, routes, commands, README) to identify the app's core user-facing flows.

If the resolved scope spans more than one git branch and the user named no single branch, cover each of them instead of only the branch currently checked out. Include scenarios that exercise them together where the branches can be combined in the working tree the plan's executor will have, and state the required branch state in each such scenario's steps.

# Create Threat Model

Analyze the current codebase and produce a structured threat model at `.turbo/threat-model.md`.

The threat model describes the current state of the codebase: what it protects, where trust boundaries are, how it can be attacked, what defenses exist, and how severe each risk is. It is descriptive, not prescriptive. Do not include remediation recommendations.

Optional: `$ARGUMENTS` may specify scope (directories, modules, or focus areas). When scope is provided, limit reconnaissance and code discovery to the specified directories or modules. Still produce all four sections, but title the overview to reflect the narrowed scope and note what is excluded.

## Step 1: Reconnaissance

Build a mental model of the system before analyzing threats.

1. Read the project README, CLAUDE.md, and any architecture or security documentation.
2. Examine top-level directory structure, build files, and dependency manifests to identify modules, languages, frameworks, and deployment model.

# Discuss Change

Escalate open decisions, agree on the implementation shape, then implement.

## Task Tracking

Use `TaskCreate` to create a task for each step:

1. Capture the task
2. Escalate product decisions
3. Deep-dive discussion
4. Confirm the shape
5. Act on the user's reply
6. Run `/implement` skill

# Draft Plan

Produce an implementation plan at `.turbo/plans/<slug>.md`. Capture the task, survey patterns, escalate decisions, discuss, and draft.

## Task Tracking

Use `TaskCreate` to create a task for each step:

1. Capture the task and pick a slug
2. Run `/survey-patterns` skill
3. Consult task-specific skills and docs
4. Escalate product decisions
5. Deep-dive discussion
6. Draft and write the plan file

# Evaluate Findings

Assess external feedback (code reviews, AI suggestions, PR comments) with adversarial verification. Triage findings into actionable verdicts. Do not apply fixes.

## Step 1: Assess Each Finding

If you already assessed a finding earlier in this session and recorded a verdict of Skip or Escalate — for example when an iterating loop re-runs review and the same finding resurfaces — do not re-adjudicate it from scratch. When the re-reported finding matches one you already judged (same location and substance) and presents no new evidence beyond what your recorded reason already accounts for, keep that verdict and reason without re-reading the code, re-verifying, or routing it to the Devil's Advocate in Step 2. Assess fresh only when the finding raises materially new evidence, or when you have not judged it before in this session.

When several findings rest on a shared premise — for example a source-of-truth choice — verify that premise once before adjudicating them individually. Findings whose premise holds proceed through normal per-finding verification; when it fails, they are all Skip, citing the refuted premise.

When a plan governs the work, re-read the decisions it records before adjudicating. Having read it earlier in the session does not count: once it falls out of context, a recorded decision is indistinguishable from no decision at all.

When the repo keeps an improvements backlog (`.turbo/improvements.md` at the repo root or, inside a linked worktree, at the main checkout's root), search it before adjudicating for the paths and symbols the findings name and for entries on the same subject, leaving out any entry the work in hand sets out to implement. Read every matching entry: run the search uncapped, splitting it into one search per finding when the combined output is too large to read, since output cut off or capped before its end settles nothing about the entries it left out. An entry that parks all or part of the change a finding asks for records a decision to defer it. When that finding holds and acting on it would make the change now, treat it as one that would reverse a decision the user made earlier, naming the entry as the original decision and quoting any condition it records for taking the change up. An entry that only shares the finding's area leaves the verdict to the finding's merits. In both cases, weigh what the entry records about that code when verifying the claim and assessing severity.

# Explain This

Take whatever the user is pointing at and translate it into plain language. "This" is usually the most recent assistant output or something pasted as an argument: a multi-option prompt, a free-form question, a code block, an error, a command output, or an artifact like a plan, findings report, or diff.

## Step 1: Identify the Subject

Pick the subject in priority order:

1. Text passed as an argument — use that
2. A quoted or selected region from the user's most recent message — use that
3. The most recent non-trivial assistant output — use that
4. If the guess is not obvious, lead the explanation by naming what was picked so the user can redirect

## Step 2: Ground in State

# Exploratory Test

Execute multi-level exploratory testing that goes beyond smoke testing to actively find bugs through escalating test scenarios.

## Task Tracking

At the start, use `TaskCreate` to create a task for each step:

1. Load or create test plan
2. Determine testing approach
3. Run `/user-experience` skill (when user-facing)
4. Run `/test-run-rules` skill
5. Execute tests by level
6. Report

# Fetch PR Comments

Fetch unresolved review comments, top-level review body comments, and PR conversation comments from a GitHub PR and present them in a readable summary. This is a read-only skill -- it does not evaluate, fix, or reply to any comments.

## Step 1: Fetch Comments

Auto-detect owner, repo, and PR number from current branch if not provided. Then run `scripts/fetch-pr-data.sh`, which handles full pagination (review threads, inner comment pages for long threads, reviews, issue comments) and emits a single merged JSON document:

```bash
bash <skill-dir>/scripts/fetch-pr-data.sh <owner> <repo> <pr_number>
```

Output shape:

# Finalize Implementation

Post-implementation QA workflow: tests, code polishing, commit, and self-improvement.

## Task Tracking

At the start, use `TaskCreate` to create a task for each phase:

1. Run `/polish-code` skill
2. Run `/simplify-docs` skill
3. Run `/update-changelog` skill
4. Run `/self-improve` skill
5. Ship It

# Frontend Design

Create distinctive, production-grade frontend interfaces that feel deliberate, premium, and current. Implement real working code with exceptional attention to aesthetic details and creative choices.

## Design Thinking

Before coding, understand the context and commit to a clear aesthetic direction.

Output three things as text before coding:

- **Visual thesis**: one sentence describing mood, material, and energy (e.g., "brutally minimal dark interface with surgical precision" or "high-contrast editorial magazine feel with oversized serif headlines")
- **Content plan**: the sections in order (hero, support, detail, final CTA for a marketing page; the working surface first for product UI)
- **Interaction thesis**: 2-3 motion ideas that change the feel of the page

# GitHub Voice

## Writing Style

- No em dashes (`—`) or double hyphens (`--`) used as dashes. Use periods, commas, colons, or restructure the sentence.
- Write in a natural, human tone. Avoid stiff or formal phrasing, unless the session is operating under an explicit style constraint. That constraint governs GitHub text too, and the destination does not relax it.
- Don't over-explain. Say what needs saying, then stop. Answer a question with exactly what it asked, in the vocabulary it used.
- Leave evidence of correctness out of a PR body: a Verification section and test-count lines when CI runs the suite, lines listing the tests or changelog entry the change includes, and figures from a survey of live data. A statistic offered as reassurance reads as an open question rather than a finished change. Keep a measurement the change exists to produce.
- In issues and design proposals, present the principle, the options, and their costs at a high level. Expert readers infer the call-site lists and per-file mechanics, and that detail buries the decision.
- When explaining how the code works, describe its current behavior. Drop phrasings that narrate the edit history ("X was changed to Y", "no longer does X").
- Keep one term per concept, preferring the name the code uses. Once a thing has a name, repeat that name instead of rotating synonyms, and refer to a code element by its identifier rather than a shorthand the text never introduces.
- When the user has stated their reasoning in the conversation, mine it and write from that reasoning. A cleaner argument constructed afterwards reads as someone else's, however sound it is.
- When the user supplies wording for the artifact, that wording is the draft. Keep their phrasing rather than sharpening it into something more precise, more formal, or more technically careful. Where the phrasing names an effect and the mechanism differs, state the mechanism separately. Flagging the deviation to the user does not license it.
- Sound like the author, not like an AI assistant.

# Implement

Standard implementation flow: load style rules, make the change, run post-implementation QA.

## Task Tracking

At the start, use `TaskCreate` to create a task for each step:

1. Run `/code-style` skill
2. Load task-specific skills
3. Make the change
4. Run verification
5. Run `/smoke-test` skill for UI/UX changes
6. Run `/preview` skill for UI/UX changes

# Implement Improvements

Validate improvements from `.turbo/improvements.md`, propose a specific working set based on the backlog's actual contents, and run one lane per session: direct, investigate, or plan. Mixing lanes in a single run tangles commits, so the skill processes exactly one lane each time. Entries outside the confirmed working set stay in the backlog for future runs.

## Task Tracking

At the start, use `TaskCreate` to create a task for each step:

1. Read the backlog
2. Validate and classify
3. Recommend, confirm, and update the backlog
4. Run the chosen lane
5. Prune working-set entries from the backlog

# Implement Plan

Execute an implementation plan file.

## Task Tracking

At the start, use `TaskCreate` to create a task for each step:

1. Resolve and read the plan file
2. Read context files
3. Run `/implement` skill
4. Update plan status

## Step 1: Resolve and Read the Plan File

# Interpret Feedback

Run two independent interpretations of third-party feedback in parallel (internal + codex peer), then reconcile into enriched items with clear intent summaries. Designed for feedback where the author's intent is ambiguous or the correctness of suggestions is uncertain.

## Step 1: Identify Feedback Items

Determine the feedback to interpret:

- If feedback items are in conversation context, use them
- If a file path or URL was provided, read or fetch the content
- If called by another skill, use the items passed in

For each item, collect whatever context is available: code snippets, diffs, surrounding discussion, file paths, line numbers. More context produces better interpretation.

# Investigate

Systematic methodology for finding the root cause of bugs, failures, and unexpected behavior. Cycle through characterize-isolate-hypothesize-test steps, with oracle escalation for hard problems. Diagnose the root cause — do not apply fixes.

Optional: `$ARGUMENTS` contains the problem description or error message.

## Step 1: Characterize

Gather the symptom and establish what is actually happening:

1. **Collect evidence** — error message, stack trace, test output, log entries, or user description of unexpected behavior
2. **Classify the problem type**:

| Signal | Type |

# Note Improvement

Capture improvement opportunities discovered during work so they don't get silently dropped. Appends to the `.turbo/improvements.md` backlog of the repo an improvement concerns.

## Step 1: Locate the Improvements File

Each repo keeps its improvements file at `.turbo/improvements.md` relative to that repo's root. Resolve that root with `git -C <repo path> rev-parse --show-toplevel`, except inside a linked worktree — where `git -C <repo path> rev-parse --git-dir` differs from `--git-common-dir` — in which case use the parent of the common dir, so the entry lands in the main checkout rather than in a worktree that is destroyed with its branch.

## Step 2: Identify the Improvement

Gather from context or `$ARGUMENTS`:

- **What**: One-line summary of the improvement
- **Type**: One of `direct`, `investigate`, or `plan` — see criteria below

# Peer Review

Independent peer review via codex. Translates a natural-language review request into a codex-specific prompt so invocations stay implementation-agnostic.

## Step 1: Understand the Request

Identify from the invoking prompt or conversation context:

- **Material** — the code scope, artifact text, feedback items, or other content under review
- **Criteria** — reference file paths codex should read directly, inline criteria text, or the material's own domain conventions
- **Dimensions** — one review concern (single-pass) or multiple independent concerns (fan-out, one per dimension)
- **Skepticism guidance** — any material-specific instruction for pushing past surface findings; optional
- **Prior adjudications** — findings already judged, one line each with its verdict and the recorded reason; optional
- **Output format** — finding layout, priority scale, or verdict labels; optional

# Pick Next Issue

Rank open GitHub issues by engagement and plan the selected issue.

## Step 1: Fetch and Rank Issues

Run `gh issue list` to fetch open issues with engagement data:

```bash
gh issue list --state open --json number,title,body,url,reactionGroups,comments,labels,createdAt --limit 50
```

Calculate an engagement score for each issue:

# Polish Code

## Task Tracking

At the start of every invocation (including re-runs from Step 7), use `TaskCreate` to create a task for each step:

1. Run `/stage` skill
2. Run `/run-checks` skill
3. Run `/review-code` skill
4. Run `/evaluate-findings` skill
5. Run `/apply-findings` skill
6. Run `/smoke-test` skill
7. Re-run `/polish-code` skill if changed

# Preview

Bring up the running app and let the user drive it themselves to judge the change, then act on their verdict.

## Step 1: Determine Scope

Resolve what to preview using the first match:

1. **User-specified** — the user says what to look at. Use that.
2. **PR** — a PR URL or number is provided. Fetch its details and read the changed code.
3. **Conversation context** — prior conversation contains recent work. Extract what changed, where it lives, and the expected behavior.
4. **App-level discovery** — fresh context with no prior work. Examine entry points, routes, and the README to identify the app's core user-facing flows.

If the resolved scope has no user-visible surface to try (a CLI-only change, a library with no entry point, backend work with no UI to look at), present this message: "Nothing to preview — <one-line reason>." Then use the TaskList tool and proceed to any remaining task.

# Prototype

Build a throwaway prototype that answers named unknowns, operate it, and hand it to the user for judgment.

## Step 1: Name What the Prototype Must Settle

Take the open unknowns from what was passed in. When nothing was passed in, derive them from the current work: the questions whose answers in prose would still leave the user guessing, such as what a surface looks like or whether an interaction pattern makes sense in the hand.

State each unknown as a question the user answers by using the prototype rather than by reading a description. When the work that prompted the prototype already named competing alternatives, state the unknown as a comparison between them. Output that list as text before building, and keep anything outside it out of the prototype.

## Step 2: Resolve the Prototype Path

Reuse the slug of the plan that governs the work when there is one. Honor an explicit slug or output path the user passed in. Otherwise generate a slug from the task title:

# Quick Finalize

## Task Tracking

At the start, use `TaskCreate` to create a task for each phase:

1. Run `/stage` skill
2. Run `/simplify-all` skill
3. Run `/run-checks` skill
4. Run `/smoke-test` skill
5. Run `/update-changelog` skill
6. Run `/self-improve` skill
7. Ship It

# Recall Rationale

Locate the Claude Code transcript that produced a given change and recover why it was made. Useful for answering reviewer questions, writing post-hoc explanations, or recovering forgotten context.

## Inputs

Accept any of:

- A commit SHA
- A file path, optionally with a line number (`<path>:<line>`)
- A reviewer question plus surrounding context (file and line)
- A passage with no commit behind it, because the project is not a git repository or the change is uncommitted

If only a file is given, `git blame` resolves the commit that last touched the line.

# Refine Plan

Loop the review pipeline over a plan until no new findings are accepted. Writes back to the plan file in place.

## Task Tracking

At the start of every invocation (including re-runs from Step 5), use `TaskCreate` to create a task for each step:

1. Resolve the plan
2. Run `/review-plan` skill
3. Run `/evaluate-findings` skill
4. Run `/apply-findings` skill
5. Re-run `/refine-plan` skill if changed

# Reply to PR Conversation

Draft a single reply that addresses a processed issue-comment list, confirm with the user, and post it as a new PR issue comment.

## Step 1: Run `/github-voice` Skill

Run the `/github-voice` skill to load voice rules and the insider-vs-outsider detection.

## Step 2: Compose the Reply

Use the processed-item list from conversation context. Each entry has: id, author, original comment body (to quote from selectively), category (`fix`, `skip`, `answer`, or `clarify`), and per-category payload.

Draft one reply that addresses every item as natural conversational prose. The output is a single piece of prose with flexible length and no rigid section structure.

# Reply to PR Threads

Draft replies for a processed review-thread list, confirm with the user, post the surviving drafts, dismiss the code-scanning alerts their entries name, and resolve threads whose entry carries a resolution reason.

## Step 1: Re-fetch Thread State

Auto-detect owner, repo, and PR number from the current branch if not provided, then query the current resolution state:

```bash
gh api graphql -f query='
query($owner: String!, $repo: String!, $pr: Int!) {
  repository(owner: $owner, name: $repo) {
    pullRequest(number: $pr) {
      reviewThreads(first: 100) {

# Resolve Findings

Apply evaluated findings and close out the change.

## Task Tracking

At the start, use `TaskCreate` to create a task for each step:

1. Run `/code-style` skill
2. Run `/apply-findings` skill
3. Close out the change

## Step 1: Run `/code-style` Skill

# Resolve PR Review Comments

Fetch unresolved review comments from a GitHub PR (inline threads, review-body observations, and issue-comment observations from the PR conversation), evaluate each one, fix or skip based on confidence, answer reviewer questions using the recalled rationale behind the change, and reply. Inline threads are answered with thread replies; issue-comment findings from people are answered with new PR conversation comments. Review-body findings and AI-reviewer issue comments flow through the same evaluate-and-fix pipeline; their outcomes land only in the summary.

## Task Tracking

At the start, use `TaskCreate` to create a task for each step:

1. Fetch comments
2. Triage already-addressed feedback
3. Run `/interpret-feedback` skill
4. Split questions and change requests
5. Run `/evaluate-findings` skill
6. Resolve ambiguities

# Review Code

Review code against type-specific criteria. Runs internal reviews and `/peer-review` in parallel by default. Returns combined structured findings.

**Types:** `correctness`, `security`, `api-usage`, `consistency`, `simplicity`, `coverage`

With a type argument, runs a single-concern internal review plus the peer review. With no type argument, runs all six internal reviews plus the peer review.

## Step 1: Determine the Scope

Determine what to review:

- If a specific **diff command** was provided (e.g., `git diff --cached`, `git diff origin/main...HEAD`), use that.
- If a **file list or directory** was provided, review those files directly (read the full files, not a diff).

# Review Dependencies

Detect package managers and CI action pins, then discover outdated or vulnerable dependencies. Analysis only. Does not upgrade.

## Step 1: Detect Package Managers

Identify which package managers are in use by searching for config files:

| Config file | Package manager | Lockfile | Ecosystem |
|---|---|---|---|
| `package.json` | npm / yarn / pnpm | `package-lock.json` / `yarn.lock` / `pnpm-lock.yaml` | Node.js |
| `Package.swift`, `*.xcodeproj` | Swift Package Manager | `Package.resolved` | Swift |
| `pyproject.toml`, `requirements.txt`, `setup.py` | pip / poetry / uv | `poetry.lock`, `uv.lock` | Python |
| `Cargo.toml` | cargo | `Cargo.lock` | Rust |

# Review Plan

Review a plan against structure and scope criteria. Runs internal reviews and `/peer-review` in parallel by default. Returns combined structured findings.

## Step 1: Resolve the Plan

1. **Plan text in conversation** — use it
2. **Explicit path** — read it
3. **Explicit slug** — resolve to `.turbo/plans/<slug>.md` and read it
4. **Single file** — Glob `.turbo/plans/*.md`. If exactly one file exists, use it
5. **Most recent** — most recently modified file
6. **Legacy fallback** — `.turbo/plan.md` if `.turbo/plans/` does not exist
7. **Nothing found** — stop and state that no plan was found to review

# Review PR

Fetch PR context, run a comprehensive code review, evaluate findings, and dispatch accepted findings to implementation.

## Task Tracking

At the start, use `TaskCreate` to create a task for each step:

1. Run `/fetch-pr-comments` skill
2. Resolve base branch
3. Run `/review-code` skill
4. Run `/evaluate-findings` skill
5. Run `/resolve-findings` skill

# Run Checks

Build the gate by combining every source below that the project declares (sources 1-3); run the baseline (source 4) only when the project declares none of them. Passing the gate must mean the project's own checks (and CI, where it exists) pass.

1. **CI config** — where present, it is the authoritative gate; run the checks it enforces.
2. **Check scripts** — package-manager scripts (`check`, `verify`, `lint`, `typecheck`, `build`), Makefile, Taskfile, or justfile targets, or a combined format+lint script.
3. **Configured tools** — any tool with a config committed to the repo, such as a dead-code or unused-dependency gate. A committed config means the project treats the tool as a gate; run it even when no script or CI invokes it. Do not run such a tool when the project has not configured it.
4. **Baseline** — when the project declares nothing more, run the formatter, then the linter, then the build where the project produces one, then the test suite.

Run the formatter first so later checks see formatted code, then the rest. When a check fails on a sandbox denial, re-run it via the Bash tool (`dangerouslyDisableSandbox: true`) before diagnosing it or reporting it as not run. A check passes only when its command exits 0. A check still running has no exit status: wait for every check to exit, one running in the background included, before reporting the gate or starting anything that follows it. Judge each run by its exit status and the runner's full summary, never by filtering the output for selected summary lines. Fix any failure the tools do not auto-resolve, then re-run each failed check and judge it by the re-run. When a fix, or a tool resolving its own failure, edits the code while the gate is running, re-run every check whose passing run started before that edit. When the same edit keeps recurring across re-runs, stop and report the checks that produce it. For test failures, run the `/investigate` skill to diagnose the root cause, apply the suggested fix, and re-run; if investigation finds no root cause, stop and report with its findings.

State which sources the project declared, which checks ran, and each check's final exit status, so a narrower-than-intended gate or a failing check stays visible.

Then use the TaskList tool and proceed to any remaining task.

# Self-Improve

Review the current conversation, or the project's past sessions when asked, to extract durable lessons and route each one to the right knowledge layer.

## Step 1: Detect Context

Available destinations:

- **Project CLAUDE.md / AGENTS.md** — The root `.claude/CLAUDE.md` (may be a symlink to `../AGENTS.md` — resolve it), plus any nested `CLAUDE.md` / `AGENTS.md` files in subdirectories. Claude Code loads a subdirectory's file on demand when files in that subtree are accessed, so a lesson scoped to one subtree belongs in the nearest enclosing file, with the root reserved for project-wide rules.
- **Auto memory** — The project-specific memory directory named by the active harness. An effective `autoMemoryDirectory` setting overrides its location; otherwise it normally lives at `<Claude config home>/projects/<encoded project root>/memory/`, where the config home is `CLAUDE_CONFIG_DIR` when set and `~/.claude` otherwise. The key replaces every character outside `A-Za-z0-9` with `-`, and long keys may be truncated and hashed, so prefer the exact harness-provided path over recomputing it. List the directory and read `MEMORY.md` if it exists.
- **Skills** — Project skills at `skills/` or `.claude/skills/` (resolve symlinks)

Discover the project CLAUDE.md/AGENTS.md files (the root file and any nested ones in subdirectories) and read them, then read MEMORY.md. When those files point at a knowledge base the repo maintains, read its index too; it is a documentation source for Step 3 rather than a routing destination. List all skill directories with the `description` frontmatter of each SKILL.md, but do not read the bodies yet — Step 2 needs to run first so you know what to look for.

# Ship

Commit, push, and optionally create or update a PR for the current staged changes.

## Task Tracking

At the start, use `TaskCreate` to create a task for each phase:

1. Determine intent
2. Branch (if needed)
3. Stage unstaged changes
4. Run `/commit-rules` skill
5. Commit
6. Update PR (if requested)

# Simplify All

## Step 1: Run `/simplify-code` and `/simplify-docs` Skills

Run the `/simplify-code` and `/simplify-docs` skills via the Skill tool in one assistant message, passing along any scope that was provided so both passes cover identical files.

Emit the Agent tool calls for every review agent the two skills define in one assistant message. Each Agent call uses `model: "opus"` and no `name`. Wait for every agent to report before continuing. Do not begin the next step on a partial set, and do not relaunch an agent that has not yet reported. State the count explicitly when emitting the calls. Hold every fix for Step 2 in place of each skill's own fix step.

## Step 2: Fix Issues

Aggregate the findings and apply one round of fixes, following each skill's own guidance for resolving its findings.

Once this round's fixes have landed, including any resolved at a gate, make one pass over the agents' findings: any whose verdict depended on code the fixes changed, moved, added, or deleted gets decided again against the current tree, keeping resolutions the user already chose.

# Simplify Code

Review code for scope, reuse, quality, efficiency, clarity, and altitude issues, then fix them.

## Step 1: Determine the Scope

Determine what to review:

- If a specific **diff command** was provided (e.g., `git diff --cached`), use that.
- If a **file list or directory** was provided, review those files directly (read the full files, not a diff).
- If **neither** was provided, determine the appropriate diff command (e.g., `git diff`, `git diff --cached`, `git diff HEAD`) based on the current git state. When the branch is an open pull request, resolve its base with `gh pr view --json baseRefName --jq '.baseRefName'`, run `git fetch origin <base-branch>`, and diff against `origin/<base-branch>...HEAD`: a local branch of the same name can sit behind the remote, which puts the merge base before an already-merged pull request and pulls merged work into the scope. If there are no git changes, review the most recently modified files mentioned in the conversation.

State the resolved file list before launching the agents: add `--name-only` to a diff command, or list the files for a file or directory scope.

# Simplify Docs

Review code comments and markdown documentation for unnecessary content, then fix the issues.

## Step 1: Determine the Scope

Determine what to review:

- If a specific **diff command** was provided (e.g., `git diff --cached`), use that.
- If a **file list or directory** was provided, review those files directly (read the full files, not a diff).
- If **neither** was provided, determine the appropriate diff command (e.g., `git diff`, `git diff --cached`, `git diff HEAD`) based on the current git state. When the branch is an open pull request, resolve its base with `gh pr view --json baseRefName --jq '.baseRefName'`, run `git fetch origin <base-branch>`, and diff against `origin/<base-branch>...HEAD`: a local branch of the same name can sit behind the remote, which puts the merge base before an already-merged pull request and pulls merged work into the scope. If there are no git changes, default to a full-tree sweep of source files plus top-level markdown.

State the resolved file list before launching the agents: add `--name-only` to a diff command, or list the files for a file or directory scope.

# Smoke Test

Launch the app and hands-on verify that it works by interacting with it. Every smoke test is a concrete interaction with the running app: navigating a screen, clicking a control, filling a form, running a CLI command, and observing the result.

## Step 1: Determine Scope

Resolve scope using the first match:

1. **User-specified** — the user says what to test. Use that.
2. **PR** — a PR URL or number is provided. Fetch the PR details (title, description, changed files, comments) and read the changed code.
3. **Conversation context** — prior conversation contains recent work (a feature, fix, or refactor). Extract what changed, where it lives, and expected behavior.
4. **App-level discovery** — fresh context with no prior work. Examine the project (entry points, routes, commands, README) to identify the app's core user-facing flows. Design tests that verify the app launches and its primary functionality works end-to-end.

## Step 2: Determine Testing Approach

# Split and Ship

Ship an approved split plan so each change group becomes its own reviewable unit, either as a separate branch and PR or as a sequential commit on the current branch.

## Context

A split plan must exist in the conversation. The plan specifies an ordered list of groups, each with a name, file list, and any dependencies on earlier groups.

## Task Tracking

At the start, use `TaskCreate` to create a task for each phase:

1. Choose realization path
2. Ship the groups

# Stage Changes

Stage implementation changes with precise file selection.

## Step 1: Identify Changes

Run `git status` to see all modified, added, and deleted files.

## Step 2: Stage Files

Stage only the files relevant to the current task:

```bash
git add <file1> <file2> ...

# Stage and Commit Changes

## Step 1: Run `/stage` Skill

Run the `/stage` skill.

## Step 2: Run `/commit-staged` Skill

Run the `/commit-staged` skill.

# Stage, Commit, and Push

## Step 1: Run `/stage-commit` Skill

Run the `/stage-commit` skill.

## Step 2: Push

Push to the current branch's remote:

```bash
git push
```

# Survey Patterns

Search the codebase for analogous features and reusable building blocks before planning a change, and read any source the task names outside this repo. Returns structured findings. Does not write code or plans.

## Step 1: Identify the Task

Determine what the change is about:

- If a task description was passed in, use it
- Otherwise, derive it from conversation context (the user's latest request)

State the task back in one sentence to confirm scope before searching.

## Step 2: Spawn Pattern Survey Subagent

# Test Run Rules

Apply these rules for the rest of the test run, whether it drives the running app or runs a test target. A scenario they leave **blocked** could not be set up or run; one they leave **inconclusive** ran, but its result cannot be read.

## Sandbox Denials

When a command failed on a sandbox denial, whether it starts or reaches infrastructure or is a scenario's own command, re-run it via the Bash tool (`dangerouslyDisableSandbox: true`) before treating the infrastructure as unavailable or recording the scenario as failed, blocked, or inconclusive.

## Isolation

- Isolate shared process state so concurrent or subagent runs don't collide: bind dev servers and services to unique ports, scope tmux sessions (`tmux -L <name>`), give each browser session a unique name so cleanup can target only its own, and write screenshots and other scratch state to absolute paths under a uniquely named subdirectory of the session scratchpad directory. Derive each such identifier once and reuse that exact value in every later command, writing it as a literal or reading it back from a note in that subdirectory. A value recomputed per shell, such as `$$`, differs between the command that creates a resource and the command that releases it, so cleanup releases something it never created and reports success while the real resource leaks. A port picked as unique may already be held by a concurrent agent, so check it before binding and move to another when it is taken, leaving the incumbent running. When a unique port moves a service off its default address, find the settings elsewhere in the stack that name that default, such as allowed origins and sign-in callback URLs, and bring each in line through runtime overrides, leaving the working tree unchanged: add the new address beside the default in a list, and replace the default only where no process outside this run reads the setting.
- Reuse a running dev server only when this session started it, has not handed it to the user to try, and serves the current code: nothing it serves changed since it started, or, since the latest such change, its output reports having reloaded that code or a served response reflects the change. Stop each server this session started that fails only that last condition by the process group captured when it started, and confirm its port released and no process from that group still running before starting another; leave one whose group is unknown running. When no server qualifies for reuse, start one on a port this run selected and wait for it to be ready. Confirm it bound to that port before sending it traffic — a failed bind leaves another agent's service answering. Move to another port when the port is taken. When the start refuses to run because the project allows one dev server instance and one is already running, build and serve the project's production output with the configuration the dev server reads, on a port this run selected and confirmed bound the same way, and name that substitution in the result. A scenario that needs development-only behavior, or configuration the production output cannot be given, is then blocked: name what it needs. Report the error and stop when the server failed to start for any other reason.
- Treat state the app persists at a fixed path, such as a data file or a local database, as shared with every other live instance of the app. When another live instance is using it, give this run's instance a copy of its own under the run's scratch subdirectory: repoint the path there through runtime configuration, or, when the path cannot be repointed and the app resolves it relative to its own tree, run the instance from a copy of the working tree placed there, uncommitted changes included. Leave the working tree unchanged. When neither separates the state, every scenario that writes to it is blocked: name the path.
- Run each test runner this run starts in its own process group under a timeout enforced from outside the runner. Before reading an exit status as the runner's, confirm the runner ran: it printed its own output, or wrote a result artifact after this invocation started. An artifact left by an earlier invocation reads the same as a fresh one. When the runner did not run, fix the launch and rerun; the scenario is blocked when no fix starts it.

# Triage Improvements

Decide, entry by entry, which improvements in `.turbo/improvements.md` are worth keeping.

## Step 1: Read the Backlog and Merge Duplicates

Read `.turbo/improvements.md`, relative to the repo root resolved with `git rev-parse --show-toplevel`, except inside a linked worktree — where `git rev-parse --git-dir` differs from `--git-common-dir` — in which case use the parent of the common dir. When the file does not exist or holds no entries, present "No improvements to triage." Then use the TaskList tool and proceed to any remaining task.

Merge entries that cover the same improvement into one entry that keeps every detail either held, write the merged entries back, and output which ones were merged. Update each **Paired with** line in counterpart entries that names a title the merge retired.

Number the remaining entries in file order.

## Step 2: Assess Each Entry

# Turboplan

Analyze task complexity to recommend an execution mode, then let the user set the final route.

Categorize the user-supplied task along these dimensions using subjective judgment. This analysis makes the recommendation informed:

- **Scope**: single feature / single subsystem vs multi-feature / multi-subsystem
- **Stakes**: one-off change vs long-lived project with architectural implications
- **Unknowns**: clear approach vs needs exploration and product decisions

Modes are named by what they produce: no plan, or a plan file.

| Mode | Criteria | Route |
|---|---|---|

# Understand Change

Act as an effective teacher whose goal is the user's deep understanding of a change. Work incrementally, confirm mastery at each stage before advancing, and keep going until the user has demonstrated understanding of everything on the checklist.

## Step 1: Identify the Change

Pick the subject in priority order:

1. A commit, PR, or path passed as an argument — use that
2. The work produced in the current session — use that
3. Uncommitted work from `git status` and `git diff` — use that
4. The most recent commit when nothing else is in scope

When the guess is not obvious, name what was picked so the user can redirect before teaching starts.

# Update Changelog

Update the Unreleased section of the changelog based on the current changes.

## Step 1: Run `/changelog-rules` Skill

Run the `/changelog-rules` skill to load shared changelog conventions.

## Step 2: Check for Changelog

Use `git rev-parse --show-toplevel` to find the repository root. Look for the changelog file per `/changelog-rules`. If it does not exist, skip this skill. Do not create it.

## Step 3: Analyze the Changes

# Update Dependencies

Upgrade project dependencies, researching breaking changes for major version updates.

Optional filter: `$ARGUMENTS` (e.g., `react`, `Alamofire`, `serde tokio`)

## Task Tracking

At the start, use `TaskCreate` to create a task for each phase:

1. Run `/review-dependencies` skill
2. User strategy selection
3. Research breaking changes
4. User confirmation