/yip-yip

name: yip-yip
description: Appa's "yip yip" for opening a pull request. Use at the end of every other workflow, and for "ship it", "open a PR", "open a pull request", "stack these PRs", or "write the PR description". Covers worktrees, commit shape, Conventional Commits titles, the PR description, forge choice, stacked PRs, and review-bot triage. Driving an open PR to merge-ready is `long-flight`.

Yip yip

"Yip yip" is how the team tells Appa it is time to fly. Use it when the work is done and proven, and it is time to land it in front of a reviewer. Every other workflow ends here.

On Codex, read [avatar-mode/references/codex.md](../avatar-mode/references/codex.md) for tool equivalents.

Before opening the PR

1. **One coherent change.** The PR does one thing a reviewer can hold in their head. Split unrelated changes into their own PRs. 2. **Clean the diff.** Read every hunk. Run `purify` over the diff before you commit and `clear-water` before review. Remove debug output, commented-out code, and stray files. Keep a comment only for a non-obvious why. 3. **Run every check locally.** Tests, linter, type checker, build. Record the commands and their results. 4. **Self-review.** Run `earth-rumble` on your own diff. Run `lie-detector` when the design is contested. Fix blockers and majors before anyone else sees them. 5. **Gather the evidence.** The output, screenshot, recording, or benchmark that shows the change working on the real artifact.

Worktree

Work from a git worktree off the default branch. Dispatched characters inherit it. Several dispatches on the same branch each get their own worktree, or run `git fetch && git reset --hard origin/<branch>` between them.

• A dirty branch with unrelated work. Save the patch, make a fresh worktree, and apply it there.
• A snarled worktree. Reset from the default branch and redo the change minimally.

Before you commit, merge, or deploy from a worktree, list the live agents and stop every one that holds it. That includes grandchildren you never launched. A dispatch's children do not inherit its brief, so a read-only instruction never reaches them. Confirm each stop. Then run `git status` and read the tree you are about to ship.

Commits

Commit liberally. Rebase into small, ordered commits before you open PRs. Each commit is a future PR. It is landable on its own, and the order tells the story. Amend when the fix belongs in a commit you just made. Make a new commit when the fix is separable. A commit body does not restate the subject.

Prose

Write every PR title, description, and commit body with `tea-time`. Use one word per action, keep the articles, and prefer a plain verb over an `-ing` form where one works.

**Titles.** Conventional Commits `type(scope): subject`, with no trailing period. The type is one such as `feat`, `fix`, `docs`, `refactor`, `test`, `chore`, or `perf`. The scope is the area, such as `team-avatar` or `yip-yip`. The subject is short and imperative, and names a real symbol when one carries the change. For example, `fix(team-avatar): retarget yip-yip review trigger`.

**Descriptions.** The PR body is a one-minute briefing for a reviewer who has the diff. It is not a lab notebook. It says why the change exists, what it leaves out, what it could break, and how you proved it works. Write short, simple sentences with few identifiers and no walls of text. The body becomes the squash commit body, so keep it under about 40 lines. Follow the repo's PR template when one exists. Otherwise use these `##` headings in this order, not bold lead-ins, and drop a section with nothing to say:

• `## Why`. The problem and the approach, in one to three short sentences. No SHAs, rebase history, or "based on main" preamble.
• `## What changed`. One to three short bullets. Name a real symbol or path only when it carries the change. Name both sides of a rename or retarget.
• `## Scope`. Always present. One to three short items on what it covers and what it deliberately leaves out (a follow-up, a known gap). No symbols, paths, or file-by-file essay.
• `## Tradeoffs`. Only the rejected alternatives a reviewer would otherwise ask about. Skip it when there was no real choice.
• `## Blast Radius`. One or two sentences on who or what it touches and why that is safe or risky. If the default branch is red, state the cost of leaving it red.
• `## Verification`. One to three bullets, each a real run path and its outcome. For performance, give one primary number with its unit as `before → after`, and link the directory that holds the rest. No sample-size methodology, run recitals, or metric tables.

After the sections, attach videos or screenshots when they prove a claim. Full SHAs, per-lane run recitals, file-by-file checklists, and "CLEAN" verdicts go in a linked artifact, not the body.

Forge

Resolve the forge before the first PR operation. Keep that choice for create, edit, view, watch, and merge.

• GitHub CLI (`gh`) is the default.
• If `command -v origin` succeeds and Origin can resolve the repository, prefer `origin pr ...`.
• If Origin is absent or cannot resolve the repository, stay on `gh` and record the fallback.
• Do not require Graphite (`gt`).

**Built-in PR tool.** When the run provides a built-in PR tool, create, edit, retarget, and mark ready through it, never through a forge CLI. A PR made by the CLI misses what the tool tracks. Use the resolved forge for everything the tool does not cover, and for every PR operation when the run has no such tool.

Size and stacks

Prefer five narrow PRs to one large PR. When a PR is too big to review, run `light-load`.

A stack is a chain of base branches. The root PR targets trunk. Each child branch rebases onto its parent's exact tip, and its PR targets the parent branch. As a parent merges, move its child onto trunk per step 4 of `safe-landing`. Without a built-in PR tool, use the resolved forge.

• Create a child with `origin pr create --status open --base <parent-branch>