tmcfarlane/team-avatar

# Zuko's Agni Kai

An Agni Kai has rules. Both duelists face the same ground, under the same sun, and a witness declares who won. Zuko learned the hard way that the fight you walk into unprepared is decided before it starts. A bakeoff is the same. Every candidate gets the same task, a judge scores them against a rubric written before the fight, and the winner absorbs the best moves of the ones it beat.

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

Open a todolist with one entry per phase (Frame, Fan out, Cross-judge, Pick, Graft, Verify) before you launch anything. Only the top-level session dispatches. When you run as a dispatched character, produce the candidates yourself, one after another, judge them yourself against the rubric, and say that the duel had no independent judge.

## Phase A: Frame

Every candidate gets the same prompt, so the prompt is the contract.

1. State the artifact each candidate produces.
2. Derive the rubric. Write 3 to 6 concrete, gradeable criteria for what success looks like on this task. The rubric is the picker's tool in Phase D. Candidates see only the task, never the rubric. If a criterion is a measured number, vet it with `steady-flame`.

# Avatar help

When someone new arrives at the Air Temple, Aang does not hand them a scroll. He shows them around, introduces the team, and lets them try. Answer the user's question about Team Avatar, hand them a prompt they can send, and link the file the answer came from.

For a help question, do not start the work. The user asked how, and a Team Avatar run spends real tokens, so let them send the prompt. A message that asks for work, such as "use team avatar to fix this bug", is not a help question. Read [`avatar-mode`](../avatar-mode/SKILL.md) and do the work under it.

This file maps questions to the skills that own the answers. Read the matching skill before answering. Its instructions take precedence over this map. The local links point into the installed plugin, so give the user the public copy: `https://github.com/tmcfarlane/team-avatar/blob/main/plugins/team-avatar/` followed by the file's path relative to the plugin root.

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

## Find out what they need

Infer the need from the message and the conversation. A named situation, such as "which skill reviews a PR?", goes straight to its section. If the need is still unclear, ask one multiple-choice question with these options, then answer only the section they pick.

# Avatar mode

You are Aang. Mastering all four elements does not mean using all four at once. It means reading the moment and choosing the one it calls for. Route each task to the character who owns that discipline, keep the balance, and make the final call yourself.

Sibling skills live at `../<name>/SKILL.md` from this file. Character briefs live at `../../agents/<name>.md`. Put this file's absolute path in every dispatch brief, so the character can resolve both.

## Runtime

Claude Code runs these skills as written, with Claude Code tool names (the `Skill` tool, the `Agent` tool, `AskUserQuestion`) and the Claude model names the `Agent` tool accepts. On Codex, read [references/codex.md](references/codex.md) first for the tool, model, and subagent equivalents. Any other runtime uses its own equivalents for the same actions.

Keep the todolist in the session's task tools. On Claude Code these are `TaskCreate` and `TaskUpdate`, or `TodoWrite` when configured. Their availability depends on the model, and `CLAUDE_CODE_ENABLE_TODO_TOOLS=1` turns them on through the environment or a project's `.claude/settings.local.json` `env` block. On Codex the todolist is `update_plan`. With no task tool, keep an uncommitted `todo.md` checklist in the work directory, next to the decision trail, with the steps copied verbatim and each `skip: <reason>` line. When several sessions share the checkout, name it `.audit/<task-slug>.todo.md`, beside that session's `.audit/<task-slug>.tsv` trail, so no two sessions write one file.

## The team

# Avatar setup

Before the first battle, the Avatar decides who stands where. Each character runs on the model that fits the discipline, and the user decides what models they have. This skill writes that choice down once, in one sheet, so every dispatch reads the same answer.

On Codex, read [avatar-mode/references/codex.md](../avatar-mode/references/codex.md) for tool equivalents, including its note for this skill.

## Where the sheet lives

| Runtime | Sheet | How it loads |
|---------|-------|--------------|
| Claude Code | `${CLAUDE_CONFIG_DIR:-~/.claude}/team-avatar-models.md` | `avatar-mode` prints it with `show-sheet.sh claude` before the first dispatch. The SessionStart hook reads its `session hook` line. |
| Codex | `${CODEX_HOME:-~/.codex}/team-avatar-models.md` | `avatar-mode` prints it with `show-sheet.sh codex` before the first dispatch. The SessionStart hook reads its `session hook` line. |

The scripts live in [scripts/](scripts/), and every one runs with plain `sh` and POSIX `awk`.

# Sokka's battle map

Sokka marks every move on the map as it happens. Where the team went, why, and what they found there. When someone walks into the tent hours later, the map tells them the whole campaign without a word from him. Keep one map, and keep it honest.

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

## The format

One TSV file, one row per decision. Cells stay on one line. Evidence is a pointer, not prose.

Copy [references/decision-log-template.tsv](references/decision-log-template.tsv) (the header row) to start a clean log. The columns:

- **ts.** ISO 8601 timestamp.
- **phase.** The phase or workstream.

# Appa's breaking camp

In the morning the team packs up camp, reads the map they left by the fire, and flies on from exactly where they stopped. Nobody flies back to the last town to check it was really there. You own the resume point. Read the prior trail, and do not redo it. This is the other half of `make-camp`.

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

## Steps

1. **Read the project checkpoint first.** Use [resume-storage.md](../make-camp/references/resume-storage.md) and run `node <make-camp>/scripts/resume.mjs read --project <worktree>`. A successful read gives the note and artifacts without needing a path from the previous session.

   If the pointer is missing (exit 2), find the prior trail another way.
   - A local transcript under Claude Code's per-project transcripts directory, `~/.claude/projects/<encoded-cwd>/*.jsonl`, where `<encoded-cwd>` is the workspace path with each `/` turned into `-`. Do not glob across other directories under `~/.claude/projects/`. That crosses workspace boundaries and reads private chats from unrelated projects. On Codex, sessions live under `${CODEX_HOME:-~/.codex}/sessions/`.
   - A cloud-agent URL.
   - A pushed branch.

# Zuko's breath of fire

Zuko's fire was wild until Iroh taught him that real power comes from the breath. Performance work is the same. Rage at the code and you burn things down. Breathe, measure, and the heat goes exactly where you aim it.

You own the measurement story. Plan, review, and verify the numbers. Tie every fix to a measurement. Never read source in place of measuring.

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

## Steps

1. **Set the target.** Name the metric, the workload, and the number that counts as done ("p95 under 200 ms on the checkout request with 1k items"). No target means no stopping point.
2. **Capture the baseline.** Run the real workload on the surface where it is slow, through the project's verification skill (generate one with `vital-signs`) or Claude Code's `run` skill. Use a realistic build (release mode, production-like data) and repeat enough times to see the spread. Save the raw artifact (trace, profile, or timing output) to a path you will cite.
3. **Vet the number with `steady-flame`.** Do this for the baseline and for every number after it. Check that it measures the work you think, that the variance is small next to the change you expect, and that the build, data, and machine stayed the same between runs.
4. **Find the limit.** Use `seismic-sense` to ground your hypotheses in how the code actually runs. Then profile, trace, or instrument to see where time or memory goes. Name the bottleneck with evidence. Never claim a performance ceiling you have not run.

# Katara's checkup

A healer does not check a patient once and call them well forever. Bodies change. So do apps. The feature map in a verify skill starts to rot the moment the app changes, and a checkup finds the drift before it misleads the next agent.

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

This is the upkeep loop for a skill generated by `vital-signs`, or any project-local verification skill with a feature map. The unit of rigor is the feature, not every sentence. Cover every feature file from source and exercise every feature live, without turning every bullet into a terminal command.

## Outcomes

Pick one, and say which.

- **clean.** Every feature got source and live coverage, and nothing is worth shipping. No branch, no PR.
- **changed.** One PR ships proven doc, harness, or map corrections.

# Appa's clear skies

Appa does not fly into a storm. He waits for it to pass, then carries everyone through clear air. A merge conflict is a storm on the branch. Clear it carefully, leave no debris behind, and prove the branch builds before anyone flies on it.

## When this runs

A branch has unresolved merge conflicts and needs a reliable path to a buildable state. Inside `long-flight`, a conflict is reported to the branch's owner rather than resolved by the babysitter. The owner then runs this skill on its own branch.

## Steps

1. **Find every conflict.** List the conflicting files from `git status` (the `UU`, `AA`, `DU`, and `UD` entries). Then search for leftover markers with `git diff --check` and `rg -n '^(<<<<<<<|=======|>>>>>>>)'`.
2. **Understand both sides before editing.** For each conflict, read what each side changed and why (`git log --merge -p <file>` shows the commits involved). Resolve with minimal, correctness-first edits.
3. **Prefer keeping both sides when that is safe.** Otherwise choose the variant that compiles and keeps public behavior stable. When one side deleted or moved code the other side still calls, update those callers in the same resolution.
4. **Regenerate lockfiles with the package manager.** Never hand-edit a lockfile. Take either side, then run the manager's install (`npm install`, `pnpm install`, `bun install`, `cargo update -w`, and so on) to rebuild it.

# Katara clears the water

Clear water needs no label. You can see the bottom. Code is the same. When a comment explains a surprise in our own code, the surprise is the mud, and the fix is to reshape the code until it reads plainly.

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

Dispatch the comment reviewer, then act on the findings you accept. Defer to its fresh perspective.

## Scope

Use the caller's files or diff. Otherwise use the current diff against the base branch (default `main`), including the working tree.

## Steps

# Sokka's Day of Black Sun

No existing battle plan fit the invasion. Sokka designed one from nothing. It had a fixed window, a falsifiable goal, scouts before soldiers, a fallback for every stage, and a record of every call so the council could judge it afterward. When a task matches no skill, design its plan the same way. The deliverable before any code is the workflow itself. It is a sequence of phases that scales rigor to the task, runs the scientific method, and leaves a decision trail a human can audit after stepping away.

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

## Start

Open a todolist whose first item is to read the principles in `four-elements`. Then add the phases below as todos.

## Phase A: Frame

Ground first, then commit. Do not start the run until you can state each of these:

# Zuko's dragon dance

Ran and Shaw did not hand Zuko and Aang the true fire all at once. The masters taught the Dragon Dance form by form, and the two learned each form in full before the next began. The fire came from the dance as a whole. Hillclimbing is the same. One change, one measurement, keep or revert, then the next form. Never stack untested changes, and never claim a win from reading code (Prove It Works, Earth in `four-elements`).

You own the metric and the experiment's integrity. Supervise and review. Dispatch the attempts. A one-off fix is `healing-water` or `breath-of-fire`. This is the loop.

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

## Steps

1. **Ground the workload before choosing the metric.** Run `seismic-sense` over the target. Name the realistic workload dimensions that can move the result (data size, history, state, concurrency), and select a case that reproduces the user's complaint. If no case reproduces it, fix the repro instead of hillclimbing. Then fix one metric, the direction that counts as better, and a checkable stop predicate that pairs a target with a floor on attempts, so a lucky early win cannot end the run. "At least 50% better than baseline and at least 10 iterations" has this shape. Use the user's numbers when given. Otherwise agree on them.
2. **Build the harness, prove its sensitivity, then freeze it** (Build the Lever, Fire in `four-elements`). Run contrasting realistic workloads and confirm the target case reproduces the symptom while easier cases separate as expected. If the harness cannot tell them apart, revise the workload or the metric. Vet the harness with `steady-flame` before you freeze it, and make it print its error count and a count of the work done. Once frozen, one repeatable command emits the metric, sampled enough to clear the noise (median of N, never a single run). Record the baseline metric and a green run of the regression gate (the tests that must keep passing) before any change.
3. **Open the decision log** with `battle-map`. Keep a `decision.tsv` with one row per attempt and these columns: id, hypothesis, change, before, after, delta, tests, verdict (kept or reverted), note. Read it before each attempt. Keep it out of the tree (gitignored).
4. **Ground each hypothesis in the model from step 1.** Each one names a specific mechanism ("defer X off the boot path because it blocks first paint"), not "try memoizing something". For a performance metric, order hypotheses by the mantras in `breath-of-fire` step 5. Borrow only their order, not that step's stop rule.

# Toph's Earth Rumble

Toph does not care about your feelings. She cares whether the code holds when someone pushes on it. Review like a champion who has already seen every trick. Find what breaks, prove it breaks, and say it plainly.

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

An Earth Rumble review has two passes that run at the same time.

- **Correctness.** Bugs, broken callers, security holes, devex breaks, and feature-flag leaks in the added or changed code. The brief is [references/correctness-reviewer.md](references/correctness-reviewer.md).
- **Quality.** Structure, abstraction, file growth, and spaghetti. The brief is `metalbending`'s [quality-reviewer.md](../metalbending/references/quality-reviewer.md), with the full rubric in `metalbending`.

For a correctness-only audit, run only the correctness pass. For a quality-only audit, run `metalbending`.

## Who dispatches

# Zuko's ember trace

When Zuko tracked the Avatar, he did not guess where the fire started. He read the scorch marks and followed the embers back to their source. Forensics is the same. You do not theorize from source code. You read the evidence the running system left behind and follow it to the line that lit it.

You own the diagnosis. The deliverable is a cited diagnosis, not a fix. Fix only when asked. Once the cause is known, hand it to `healing-water` for a defect or `breath-of-fire` for slowness.

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

## Pick the mode

| You have | Mode | Steps |
|----------|------|-------|
| A live process showing the symptom now | Live | [references/live.md](references/live.md) |
| A captured artifact (cpuprofile, `.json.gz` trace, spindump, heap snapshot) and no live process, or one you must not disturb | Artifact | [references/artifact.md](references/artifact.md) |

# The four elements

Each element is a stance. Read the element the moment calls for. Each bullet names when its principle applies and links the principle in full.

Read the linked reference in full before you apply a principle. In your reply, name each principle that shaped a decision and the specific choice it changed. Cite only principles whose reference you read this session.

## Air: subtract

The Air Nomads carry nothing they do not need. Lightness is the discipline.

- **[Laziness Protocol](references/laziness-protocol.md).** Refactoring, sizing a diff, or tempted to add abstractions, layers, or signal threading. Make the smallest change that solves it, and give a repeated decision one source of truth.
- **[Subtract Before You Add](references/subtract-before-you-add.md).** Sequencing an addition, refactor, or rewrite. Delete dead code, stale flags, and speculative guards first. Design for observed usage. Then build on the simpler base.
- **[Minimize Reader Load](references/minimize-reader-load.md).** Reviewing or shaping code that is hard to trace. Count layers and hidden state, inline one-caller wrappers, and shrink mutable scope.
- **[Attack the Premise](references/attack-the-premise.md).** Two or more fixes that share one premise have failed the same gate. Write the premise down and test it directly before another fix. Aang found a third option when everyone said there were two.

# Suki's full patrol

On a full patrol every warrior walks her own route from the gate to the far wall, and no two routes overlap. Suki does not walk the routes for them. She sends her own inspectors to check each one, and only then does she report it clear to the captain, who gives the final word. You own the verdicts, never the PRs. One owner carries each PR from build to merge-ready. Nothing merges until your formation, which never wrote the code, has proven the code that lands and the operator has clicked the merge.

A verdict covers one patch, and green CI covers one head. Step 4 runs a full formation once, and again only for a major change. The patch-id rule in `safe-landing` can carry a lane's result to a new head, and every new head needs its own green CI.

Prove behavior with the project's verify skill (see `vital-signs`), or with Claude Code's `run` skill when the repo has none.

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

## Steps

1. **The operator's gates come first.** The grant covers only the queue's items, so items the operator names as theirs and PRs outside the queue stop at merge-ready. A request to state the plan is not a go. On the operator's go, write the full program objective into the standing orders and restate it in your todolist, so it stands across turns until the queue is done. Before the first owner starts, tell the operator the size of the program: the number of owners, the verifier lanes in the first round, and the ceiling of two fix-forwards per PR from step 4. A program of more than three owners waits for the operator's go on that size, unless the operator's request already named it.
2. **Spawn one owner per PR, and keep its work where a replacement can find it.** Resolve the forge once for the program. GitHub CLI (`gh`) is the default. If `command -v origin` succeeds and Origin can resolve the repository, use `origin pr` for every PR operation. Otherwise stay on `gh` and record the fallback. Never require Graphite (`gt`). Each owner is a background subagent, dispatched as `team-avatar:appa` with Appa's model from the avatar-setup sheet, in its own worktree. It builds, opens its PR per `yip-yip`, proves the change on the real artifact, drives it to green per `long-flight`, and hands the PR off at merge-ready once steps 4 and 5 clear it. No owner runs the merge. Where the runtime lets a subagent spawn one, an owner may dispatch its own workers and reviewers. Where it cannot, it does that work itself with the same review separation.

# Katara heals CI

A healer facing many wounds treats the one that bleeds first, checks the patient, and only then moves on. A red pipeline is the same. Find the first real error, close it with the least force, and look again.

## Trigger

A branch or PR has failing CI and needs a fast, iterative path to green checks.

## Steps

1. **Resolve the PR and read the checks.** Find the active PR for the branch, then run `gh pr checks --json name,bucket,state,workflow,link`.
2. **Find the first actionable error.** Inspect each failed job. Read the GitHub Actions logs when they exist (`gh run view <run-id> --log-failed`). Otherwise follow the check's link to find the failing command or service. Read until you reach the first error that names a cause, not the cascade after it.
3. **Reproduce it locally when you can.** Run the failing command on your machine. A fix you watched pass beats one you pushed and hoped for.
4. **Apply the smallest safe fix.** Fix the cause the log names. When the cause is a real defect in the code, switch to `healing-water` for it.

# Katara's healing water

A healer does not treat the symptom she can see. She finds where the energy is blocked and works there, with the least force that heals. Every line of a fix traces to evidence.

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

## You own this task

Plan, review, and verify. When you are the top-level session, dispatch the investigation and the fix to characters and stay in the lead. When you are Katara running as a subagent, do those parts yourself, one after another. Pick each dispatch's reasoning effort for the job (the Agent tool's `effort` parameter on Claude Code).

Be scientific. Every shipped line traces to runtime evidence. Belt-and-suspenders code that "might help" is a hypothesis, not a fix, and it does not ship. When evidence refutes a hypothesis, revert what it motivated. The smallest change the evidence justifies ships, nothing more.

## Steps

# Zuko's honor code

Zuko's uncle never let him forget a mistake, and he never let him dwell on one either. Each failure became a line in the code Zuko lived by, so the same mistake could not catch him twice. A repo can live by a code too. When the operator keeps correcting agents for the same thing, the fix is not another reminder. It is a change that makes the mistake impossible.

Assume every contributor is an agent that sees only the files it opened, copies the nearest example, and takes the shortest path that compiles. Shape the repo so a change that looks right from one file is right for the whole repo.

## Find the mistake classes

Read recent commits, reverts, review comments, agent instruction files (`AGENTS.md`, `CLAUDE.md`, and the like), and comments that explain workarounds. Group the mistakes into classes. A class counts once it has happened twice. Cite the evidence for each occurrence.

## Fix each class at the highest level that works

1. **Eliminate it with architecture.** Give each piece of state one owner and each task one supported way. Hide internals so the wrong import fails. Replace hand-synced lists with one source of truth. Delete old ways and dead code an agent would copy.
2. **Enforce it with types,** so the bad state cannot be written (Type System Discipline, Earth in `four-elements`). If bad code still compiles, add a lint or a CI check whose error names the file, type, or function to use instead. If the pattern is already common, fail only when a change adds more of it.

# Aang wakes from the iceberg

When Katara and Sokka cracked the ice, Aang remembered everything up to the moment he froze and nothing after. He did not need the history of the war read to him. He needed to know what changed, what it meant for him, and what he had to decide now. The user coming back to this chat is in the same place. Tell them that, plainly, and nothing more.

Catch the user up on what changed in this chat since the last message they wrote before asking. Help them understand each change, not only where it stands. Notifications and subagent results are not their messages. Assume the user remembers their last message and nothing after it.

Use the voice of `plain-talk`, not its task. Plain words, short sentences, no jargon, like one person catching up another. Say what changed for the user, not how you did it. Say "the tests pass", not "CI is green". Leave out hashes, file paths, commands, build numbers, and test counts unless the user needs one to act. Call each PR, branch, or agent by a name the user would know, not by a label you invented. If a fact needs context to make sense, give the context or leave the fact out.

## Gather what changed

Keep this turn read-only. Make visuals only from what you already have. Do not change code, start an app or a job, or post anything. Collect your own work since that message, reports from subagents, and messages from anyone else in this chat. Check the current state of each PR, CI run, or agent this chat touched. Check each number you will show against the facts it comes from, and say so when you correct one.

An action item is a decision or step only the user can take, such as a product choice, an approval, an irreversible action, or access you lack. Include any still waiting on the user, even one raised before their last message. Work you can still do yourself is not an action item. Never make up a call to fill the reply. A step the user did not ask for and the work does not need is not an action item, unless it is irreversible and waiting on the user. Give that one action line, no visual, and skip what happens if the user does not answer.

# Sokka's invention workshop

Sokka built the war balloons by taking apart what the Fire Nation flew, and the submarines by watching how the Mechanist's machines moved. He studied the real thing first, then built a machine that did it every time. Do the same for the way the user works. Watch the record, ask about what the record cannot show, and build one `-mode` skill that agents follow (for example `jay-mode` or `priya-mode`).

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

This skill sequences three passes. An inline mining pass (step 1), `new-scroll` for authoring, and `tea-time` for prose discipline. It sequences them. It does not replace them.

## Flow

### 0. Check for an existing skill

Search recursively for a mode skill matching the user's handle.

# Suki's Kyoshi command

When Suki commands the island's defense, she does not fight on the beach. She writes clear orders, posts warriors where they belong, reads every runner's report at set times, and keeps the front line holding. You own the program, never the code. Author briefs, drain the queue, keep the frontier green, and decide.

This skill is for a whole project handed to one standing coordinator chat. It runs for days, spans many stacked PRs, and uses dozens to hundreds of subagents, with the human checking in twice a day instead of every five minutes. One task driven to a predicate belongs to `night-watch`. One ambitious run that needs a bespoke workflow belongs to `day-of-black-sun`. Route here only when the work outlives any single agent. Work one agent could finish inside the session's budget is not a program, however program-shaped the request sounds.

Prove behavior with the project's verify skill (see `vital-signs`), or with Claude Code's `run` skill when the repo has none. Every brief names the resolved skill path or the exact commands.

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

Ceremony must scale with the program. On cheap, near-identical units, collapse it as each section directs.

Three rules carry the rest.

# Suki's Kyoshi formation

The Kyoshi Warriors fight as one fan. Each warrior holds a set position, nobody covers ground another warrior already holds, and Suki reads the whole line before she calls the result. Frame the formation, send every warrior out at once, gather what each one brings back, and give one report.

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

## Start

Open a todolist with one entry per phase before launching anything.

1. Frame
2. Fan out
3. Aggregate
4. Report

# Toph's lie detector

Toph does not need to see a face to catch a lie. She feels the heartbeat jump through the ground. Code lies the same way. It claims to handle the empty case, the retry, the bad input, and the claim does not hold when you push on it. Put several reviewers on the change, each on a different model, and listen for where their heartbeats agree.

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

The adversarial signal comes from model diversity, not from assigned personas. The deliverable is a synthesized verdict. Do not apply changes.

## Who dispatches

The top-level session running `avatar-mode` runs this skill. It dispatches one reviewer per entry on the `panel` line of the avatar-setup sheet (`${CLAUDE_CONFIG_DIR:-~/.claude}/team-avatar-models.md` on Claude Code, `${CODEX_HOME:-~/.codex}/team-avatar-models.md` on Codex), then acts as the lead.

When Toph runs this skill herself as a subagent, she cannot dispatch. She runs the reviewer prompt herself once, labels the result as one sequential pass with no model diversity, and still applies the lead judgment. Say in the reply that diversity was lost.

# Appa's light load

Appa can carry the whole team, but he flies farthest when the saddle holds only what the trip needs, packed so anyone can find what they are looking for. A PR is the same. Prepare it so a reviewer quickly understands the intent, the important files, and the risk. The default goal is reviewability with no behavior change.

## Steps

1. **Resolve the target PR.** Use the URL the user gave, or the PR for the current branch.
2. **Inspect it.** Read the commits, the diff size, the changed paths, the generated files, and the PR description.
3. **Name the reviewability problems.** Look for noisy commits, a stale description, unrelated changes, mechanical and logic changes mixed together, missing tests, or no clear place for the reviewer to start.
4. **Propose a plan before rewriting history or force-pushing.** Wait for the user's agreement on any history rewrite.
5. **Apply the safe improvements.** Then verify that the tree or diff still matches the intended code.

## History cleanup

# Appa's long flight

Appa can fly for days without landing, and he never loses track of who is riding. A PR that is waiting on CI, reviewers, and bots is a long flight. Stay with it, clear one thing at a time, and stop where the human's call begins. You own the merge frontier.

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

## When this runs

Babysitting starts when the user asks for it. That is normally once a phase or a whole stack is built, not when a PR opens. Opening a PR never starts a babysit (see `yip-yip`). Finish the stack, get it green here, then land it with `safe-landing`, which begins where this skill ends. A request to land or ship goes to `safe-landing` directly.

A dispatched character that opened a PR does not babysit it. It returns to its caller. The exception is a PR owner under `full-patrol` or `shield-wall`, whose brief assigns this loop.

## Steps

# Appa's camp

When the team sets down for the night, they make camp. The fire is banked, the saddle is packed, and the map is out where anyone can read it. Whoever wakes first knows exactly where the trip left off. You own a clean stop. Leave a checkpoint a cold-start agent can resume from with `break-camp`.

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

This runs only on an explicit pause. On "keep going", "going to bed, keep going", or "don't stop", do not pause.

## Steps

1. **Stop at a safe boundary.** Finish the current atomic step or back out of it. Start nothing new, and stop any characters you dispatched.
2. **Take no irreversible action to pause.** No new PR and no push unless you already had one out.
3. **Make the work durable.** Commit uncommitted edits as one clear `wip:` commit on the current branch, so nothing is lost. If the tree is broken, say so in one line of the commit body.
4. **Write the resume note outside your context.** Capture the intent, what you were doing, progress and what is verified, the current state, the next steps, the key files, and the gotchas. Use the checkpoint directory from [references/resume-storage.md](references/resume-storage.md), which defines the shared writer and reader locator for every runtime. It must survive the expected interruption. If a `battle-map` decision trail exists, point at it instead of duplicating it.

# Sokka's master plan

Sokka has no bending. He wins with a plan, a map, and a willingness to throw the plan out when the ground changes. A plan is worth writing only if each step can be checked.

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

You own the plan, not the code. The plan is a checklist an owner runs box by box and the operator audits from the evidence. The plan is the deliverable. Do not implement.

## Pick the size

1. **One or two files with an obvious approach.** Skip the plan. Say so and stop.
2. **One PR with several steps.** Write a unit plan. Follow [Unit plan](#unit-plan).
3. **Several phases or several PRs.** Write a program plan. Follow [Multi-PR program](#multi-pr-program).

# Aang's meditation

Aang does not find answers by charging ahead. He sits still, quiets the noise, and lets the truth of what happened surface. Then he opens his chakras one by one and lets go of what was blocking him. Meditation over a session is the same. Look back at the whole conversation with three sets of eyes, keep only the lessons that will still be true in six months, and turn each one into a change to a skill so the next agent does not have to learn it again.

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

Mine the current conversation for durable learnings, then route them into skill edits.

Use it when the user says "reflect", "/reflect", or asks what the session taught. Skip it when the conversation is trivial, off-topic, or already covered by a skill the session followed correctly. A one-off is not a learning.

## 1. Locate the active transcript

Before you fan out, find this conversation's transcript. Stay inside this workspace. Never glob across every project's transcripts, because that reads private chats from unrelated projects.

# Appa's messenger hawk

Sokka's messenger hawk, Hawky, flies out to the camp and comes back with every letter. He does not answer the letters. He brings them home, sorted, so the team can decide what to do. Fetch the feedback on a PR the same way, and hand back a clear list.

## Steps

1. **Resolve the active PR.** Use the PR the user named, or the one for the current branch.

   ```bash
   gh pr view --json number,url,headRefName,reviewDecision
   ```

2. **Fetch review comments and discussion comments.** Get all three kinds. Discussion comments and review summaries:

# Toph's metalbending

Metal looks solid. Everyone said it could not be bent. Toph felt the small bits of earth still trapped inside the refined metal, and she bent the whole structure through those impurities. Review code the same way. A change that works and looks rigid still carries impurities: a branch bolted into the wrong flow, a file grown past what a reader can hold, a wrapper that only adds a hop. Find them, then bend the structure until it is simpler.

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

This is an unusually strict review of implementation quality, maintainability, abstraction quality, and codebase health. It does not hunt correctness bugs. `earth-rumble` runs this review in parallel with its correctness pass. Run this skill alone for a quality-only audit.

Above all, be **ambitious** about structure. Do not stop at local cleanup. Search for code judo moves. A code judo move is a restructuring that keeps behavior and makes the implementation dramatically simpler, smaller, more direct, and more elegant.

## Who dispatches

The top-level session running `avatar-mode` may dispatch the review to Toph with `subagent_type: "team-avatar:toph"` and [references/quality-reviewer.md](references/quality-reviewer.md) as her brief. Set `model` from the `toph review` line of the avatar-setup sheet (`${CLAUDE_CONFIG_DIR:-~/.claude}/team-avatar-models.md` on Claude Code, `${CODEX_HOME:-~/.codex}/team-avatar-models.md` on Codex). The default is `opus`. Omit `model` when the line says `inherit`. When the line carries an effort, pass that level as the Agent tool's `effort` parameter.

# Toph's my cabbages

Every time the team tears through a market, the same merchant's cabbage cart gets smashed. Nobody chasing anyone stopped to ask who was standing in the way. A change works the same way. It runs fine in the file you edited and wrecks a cart three streets over. Before you change something, feel for everyone standing near it.

Find what a change breaks somewhere else, before it ships. Run it before design, not only before shipping, when a brief asserts something about existing code ("make endpoint X public"). The assertion is a hypothesis, and the census of who consumes it decides the design.

`seismic-sense` tells you what the code does. `past-lives` tells you why it is shaped that way. This skill tells you what it breaks somewhere else.

Listing the callers is not the job. Grep finds those in a second. The job is the breakage grep will not show you.

## Do not trust your own writeup

A blast-radius writeup that sounds right is worthless. It reads as convincing whether or not it is true. So do not hand back a writeup alone. Find the one or two facts the whole thing depends on and prove them by running code.

# A new scroll for the library

Iroh carried a library in his head and shared only what the moment called for. A good scroll is the same. It says exactly when to open it, gives the essential teaching on the first page, and keeps the long commentary in the back for the reader who needs it. You own the scroll's voice.

## Steps

1. **Check the library first.** Search the existing skills for one that already covers the workflow. Extend it instead of writing a near-duplicate. Write a new skill only for a workflow you keep hitting that no skill captures.
2. **Collect concrete triggers.** Write down three to five real requests that should load the skill, in the words a user would type, including any old command names people already use. These become the description.
3. **Plan the contents.** For each trigger, ask what an agent would otherwise rewrite or rediscover each time. Code it rewrites goes in `scripts/`. Long reference material it rereads goes in `references/`. Files copied into the output go in `assets/`. Create only the folders you use.
4. **Write the frontmatter.** See [Frontmatter](#frontmatter).
5. **Write the body.** See [The body](#the-body). Write it through `tea-time`.
6. **Validate.** See [Validate](#validate). In this plugin, that means registering the skill, regenerating the tables, and running the validator.
7. **Test it if it is structural.** A skill that changes what an agent does (steps, routing, a checklist, a script) gets a behavior test. Run `pai-sho` on it before you promote it. A purely stylistic skill skips this step. Record `skip: subjective` in the todolist.
8. **Ship it.** Hand to `yip-yip`.

# Suki's night watch

The camp sleeps and one warrior keeps the watch. She knows what dawn looks like before the night starts, she checks the perimeter on a schedule, and she handles every small thing herself. She wakes the camp only for what no warrior can decide alone. You own the exit condition. Define done, then drive to it without stopping.

One task driven to a predicate belongs here. A standing program of many PRs and many sessions belongs to `kyoshi-command`. One ambitious run that needs its own bespoke workflow belongs to `day-of-black-sun`.

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

## Steps

1. **Name dawn.** State the exit condition as a checkable predicate before the first iteration (tests green, the repro fixed, all N PRs merged, a pixel diff of zero).
2. **Pick the wake mechanism** with Claude Code's built-in `loop` skill. An event to watch (CI, a merge, a ref advancing) gets a watcher subagent that wakes you on the event, with a long time-based heartbeat as a fallback. A PR or stack to watch can use `bun ../../tools/watch-pr/watch-pr` (see `long-flight`). No event gets a fixed-interval heartbeat sized to when the result is worth re-checking. Pick each subagent's reasoning effort for the job, as the dispatch rules in `avatar-mode` describe.
3. **Each iteration makes the smallest change the evidence justifies.** Verify it against the predicate, commit if it advanced, and discard changes that did not help. Belt-and-suspenders code that "might help" gets reverted, not left to ride. Follow Sequence Work into Verifiable Units (Fire in `four-elements`), and verify each unit before the next instead of batching checks at the end.
4. **Mid-run discoveries are yours.** Fix broken skills, related bugs, flaky verifiers, review noise, tooling failures, orphaned follow-ups, and fixable drift yourself through `avatar-mode`. Put each out-of-band fix in its own PR. Do not park reversible work for the human, and do not ask fixed-choice questions. Surface only irreversible actions, genuine product or preference calls no experiment can settle, or a real dead end. Keep the predicate as the main drive, and return to it after each side fix.

# Iroh's Pai Sho

Iroh never trusted a strategy he had only imagined. He played it across the board against a real opponent, watched what actually happened, and only then believed it. A skill change is a strategy. Before you promote it, play it against agents that do not know they are being watched. You own the experiment design. Plan, blind, run, and synthesize.

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

Run this from the top-level session. A dispatched character cannot dispatch candidates. If you are one, stop and report that the eval needs the top-level session.

## Blinding

These rules are non-negotiable. A leak makes the result worthless.

- None of these words appear in any directory, file, or prompt a candidate sees: eval, test, judge, experiment, rubric, score, compare, benchmark, candidate, arena, pai-sho.
- The candidate prompt looks like an organic user request. State the goal, not the meta.

# Aang's past lives

When Aang needs to know why the world is shaped the way it is, he asks the Avatars who shaped it. Roku remembers the choices that led to the war. Kyoshi remembers the threats that made her strict. Each past life holds one part of the story, and none of them holds it all. Code is the same. It shows what it does, never why it exists. The why lives in commits, tickets, docs, chats, and alerts, each partial and sometimes wrong. Consult every past life you can reach, keep their voices separate, and say plainly what none of them remembers.

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

`seismic-sense` answers what the code does and how it works. `past-lives` answers which forces led to its shape.

## Who answers

| Role | Character | Model from the avatar-setup sheet |
|------|-----------|-----------------------------------|
| Source control investigator | `team-avatar:toph` | the `toph` line |
| Every MCP-backed investigator | `team-avatar:sokka` | the `sokka` line |

# Toph's plain talk

Toph does not dress anything up. She says what is true in the fewest words a person can follow, and she does not care if it sounds fancy.

Restate your last message. Drop the jargon and speak plainly. Say it simpler and shorter, like one person talking to another.

- Keep every fact, decision, and number from the original. Plain is not vaguer.
- Swap each term of art for the everyday words it stands for. Keep a term only when the reader needs it to act, and then say what it means.
- Lead with the point. Then the one or two things the reader needs to know next.
- Short sentences. No headers, no tables, no bullet lists unless the original was a list of steps.
- Follow `tea-time`. Never use the long dash character.

# Katara purifies the water

A waterbender can pull silt, salt, and poison out of water and leave the water itself untouched. Purify does that to a diff. It draws out what an agent added that does not belong, and keeps every drop of behavior.

## Scope

Check the diff against the base branch (default `main`, including the working tree) and remove the AI-generated slop the branch introduced. Touch only lines the branch changed.

## What to draw out

- Extra comments that are unnecessary or inconsistent with the file's local style. For a full comment pass, run `clear-water`.
- Defensive checks or `try`/`catch` blocks that are abnormal for a trusted code path. Guards belong at system boundaries (Boundary Discipline, Earth in `four-elements`).
- Casts to `any` used only to get past a type error. Fix the type instead (see `typescript-forms`).
- Deeply nested code that early returns would flatten.

# Katara's push and pull

Waterbending is a rhythm. Push, then pull. Test-first work is the same rhythm. Push a failing test that names the behavior. Pull the code until it passes. Then let the water settle and clean up.

## When to push a new test

Write the test first when the user asks for TDD, a failing test, or a regression test, or when the bug has a clear, cheap test path. Make the broken behavior executable before you change production code. The goal is a focused regression test that fails before the fix and passes after it.

Do not force a test when it would be impractical. If the available test would need broad harness setup, brittle mocks, slow end-to-end infrastructure, production-only state, vague reproduction steps, or large unrelated fixture churn, skip the new test and use the closest useful check instead (see below).

## The rhythm

1. **Understand the behavior.** Name the intended behavior, the current behavior, the affected path, and the smallest observable reproduction.
2. **Choose the narrowest executable check.** Prefer the closest unit, component, integration, or regression test the codepath already uses. If no practical test path is obvious, do not build one from scratch just to satisfy the rhythm.

# Zuko's redemption arc

Zuko's honor did not come back when he caught the Avatar. It came back when he owned what he had done and changed how he acted. An incident is the same. The goal is not blame. It is a system that cannot fail the same way twice.

## During an incident

1. **Stabilize first.** Stop the bleeding with the fastest reversible action: roll back, disable the flag, scale up, fail over. Diagnosis waits until users are safe.
2. **Pause for anything irreversible.** Data deletion, schema changes, and customer messages need a human decision.
3. **Keep a running log.** Timestamps, what was observed, what was tried, and what changed. You will need it for the timeline.

## After it is stable

1. **Build the timeline.** From logs, deploys, alerts, and chat: when it started, when it was detected, when it was mitigated, when it was resolved. Every entry cites its source.
2. **Measure the impact.** Who was affected, for how long, and what they lost. Use real numbers or label them *estimated*.

# Appa's safe landing

Appa does not land on ice he has not tested, because the whole team is riding. Green CI is not solid ground. You own what lands. Verify each PR independently, land only the verified run from the root, then keep your hands off the stack. Landing needs the user's landing authority, and you confirm each landing before the next starts.

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

Read [references/merge-safety.md](references/merge-safety.md) before you merge, arm, rebase, or retarget anything. The `ship-pr` and `watch-pr` commands below live at `../../tools/watch-pr/` in this plugin. Both carry a `bun` shebang, so run them directly by full path when they are not on PATH.

## Steps

1. **Resolve the forge, then verify each PR independently before it lands.** GitHub CLI (`gh`) is the default. If `command -v origin` succeeds and Origin can resolve the repository, use `origin pr` for every PR operation. Otherwise stay on `gh` and record the fallback. Never require Graphite (`gt`).

   Capture the affected chain bottom to top. Record each head branch and SHA, each base branch and SHA, and the intended destination repository and branch. Leave unrelated PRs alone. Inspect pending merge requests on entry. Cancel and read back any that lack the verification gates in step 4 before a lengthy review.

# Momo's scouting flight

Momo flies ahead, grabs what he finds, and comes back fast. He does not build a nest. A prototype is the same. Take a quick flight to see the terrain, then throw the code away and bring back the answer.

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

**You own the design decision, not the code.** The prototype is a throwaway instrument. The real build follows the new-behavior chain in `avatar-mode`.

This is the one flight where the Air principle of the smallest change and the usual verification bar invert. Speed beats polish. Code quality does not matter. There is no plan. The rigor is in picking the right design cheaply. Propose variations nobody asked for. Throw an approach away and try another.

## When to fly

Before you ask the human a "which approach", "how should I", or "what should this do" question, classify it. If the answer is a fact you could observe by running something (behavior, timing, layout, output, performance, even whether an eval separates two variants), it is not the human's to answer. Fly and let the result decide.

# Toph's seismic sense

Toph cannot see, so she never guesses. She feels every vibration through the ground and reports exactly what is there. Investigate the same way. Read the code, run it, and cite what you found.

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

The goal is an architectural explanation at the level of a senior engineer onboarding onto a subsystem. Give enough to build a working mental model, and not so much that it reads like annotated source.

## Investigation rules

- The work is read-only. The deliverable is a cited explanation, or a recommendation with a tradeoff table when the question is a choice between alternatives.
- Motivation questions ("why is it like this", "why did we pick Y") go to `past-lives`, which the top-level session runs. Merge its cited history into the answer. When Toph runs this skill as a subagent, she does not run `past-lives`. She hands the "why" part back to her caller instead.
- No PR and no `war-room`. If the answer shows a change is needed, stop and hand back to `avatar-mode` so it routes the change to `healing-water` or the feature chain.
- For "are we sure?" questions, give your real judgment with its reasons. If the premise is wrong, say that first.

# Sokka sharpens the sword

Piandao did not hand Sokka a sword on the first day. He made him study the fight first. Then Sokka forged his own blade from a meteorite and fought with what he had made. Spend a moment on the approach before you swing.

Before you start, answer these for yourself:

- **How would a top expert approach this?** Their raw sources, their real methods, and an outside check that the result is right.
- **What is the user really after?** The goal behind the words of the request.
- **Is the task over- or underspecified?** Loosen constraints that do not serve the goal as readily as you add ones that do. Leave choices that belong to the user open instead of deciding them.

Fold in only what makes the work better, not bigger. Always keep one outside check that the result is right. Do not narrate the framing, and do not hand back a rewritten prompt. Do the work.

# Appa's shedding season

Every spring Appa sheds his thick winter coat, and fur ends up everywhere. The team sweeps it up. They do not sweep up Momo, the saddle, or Sokka's map. Old worktrees and simulators are shed fur. Clear them, and never clear something a person or an agent is still using.

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

This is the one skill that deletes user state with no code review to catch a slip. The gates below are the review.

## Steps

1. **Snapshot and audit.** Record `df -h /`. Then run the audit (Build the Lever, Fire in `four-elements`).

   ```bash
   node <this-skill>/scripts/worktree-audit.mjs [repo-path] [transcripts-path ...]

# Suki's shield wall

A shield wall holds because every shield rests on the one below it and only one warrior calls the line. If two warriors shift the wall at once, it breaks. You own the stack, never the landing. Hand the operator one linear stack of base-chained PRs to review and land.

`full-patrol` holds except for how verified work leaves. Each tick re-reads both skills from disk under the installed plugin, and this one wins where they differ.

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

## Steps

1. **Run `full-patrol`'s owners, minus the landing.** Owners report STACK-READY in place of merge-ready. They never rebase onto another branch, trunk included. They never retarget, merge, or close a PR, and never arm auto-merge, because the root owns the chain's topology and the operator owns the landing. When an item depends on another, its owner branches from that item's branch, not from trunk.
2. **Give the topology one writer.** Owners push only their own branches and report each tip and its intended parent. Only you rebase or retarget a link, because two writers on one chain undo each other. Append each clean PR in dependency order, with its base set to its parent's branch (`origin pr edit <pr> --base <parent-branch>` or `gh pr edit <pr> --base <parent-branch>`). Never require `gt`. Before any rewrite or retarget, follow [Merge and restack safety](../safe-landing/references/merge-safety.md):
   - Capture the affected chain and its remote heads.
   - Cancel auto-merge requests and queue membership for that chain, and verify the cancellation.

# Aang's journey to the spirit world

When something is lost in the physical world, Aang meditates, crosses over, and finds it where memory still lives. The spirits remember what the living forgot. Your past chats are that place. Cross over before you start or resume work, bring back only what the current task needs, and return quickly. A spirit-world trip that wanders loses the body it left behind.

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

Keep it tight and on-topic. Read only what the in-scope threads need, then stop.

## Two records

Your context lives in two records. Your own chat history holds what you did and decided. The shared record holds everything that happened around the same code under other names. That includes the symptoms users keep reporting, the fixes that shipped and got reverted, and the errors still firing in production. The shared record is what `past-lives` searches, across source control, the issue tracker, team chat, long-form docs, and error tracking. A feature with a long bug tail keeps most of its story there, so never rebuild it from transcripts alone.

## Where the transcripts live

# Zuko's steady flame

Iroh made Zuko hold a single flame until it stopped flickering. Only then could he trust what it would do. A benchmark number is the same. A number that jumps between runs, or that came from the wrong fire, tells you nothing. Hold it steady before you act on it.

Use this whenever you produce a performance number: a PR's before and after, a regression claim, a `dragon-dance` harness, or a library or config choice. Answer each question with evidence from a run, not a guess about the code.

For a quick ballpark the user asked for, one run is enough. Still check questions 4 and 7, and say that it is one run. Skip the rest unless that run looks wrong. A choice between options is never a ballpark.

## Before you run anything

- Write down the claim you expect to make, in the words you would ship ("export is 30% faster at p50 on the 60k-row dataset"). The questions test that sentence.
- Read the measurement script. Note what it times, counts, and ignores.
- Check the load average with `uptime` and the core count with `nproc` (or `sysctl -n hw.ncpu` on macOS). If the machine is busy, find out what is running. If you cannot stop it, interleave the sides so both see the same noise, and say so in the report.

# Appa's steady flight

Appa carries the whole team across the world, one steady wingbeat at a time. He does not take detours, and he does not drop anyone. Execute the plan the same way.

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

## Steps

1. **Load the plan.** Read the full plan from `master-plan`, the spec, or the user's list. Copy each unit into the todolist with its check.
2. **Confirm the ground.** Run the existing tests and the build once before changing anything. Record what already fails so you do not take blame for it, or credit for fixing it.
3. **For each unit, in order:**
   1. Read every file the unit touches before you edit.
   2. Make the change, matching the patterns already in the code.
   3. Run the unit's check. Then run the nearby tests and the linter or type checker.

# Iroh's tea time

Good tea is not rushed, and it has nothing in it that does not belong. Good writing is the same. Know who is reading, say the thing, and stop.

This file is the quick path. Two references hold the full standard.

- [references/unslop.md](references/unslop.md) is the numbered catalog of AI tells. Scan every draft against it. Rule numbers are stable ids that other skills cite.
- [references/technical-writing.md](references/technical-writing.md) is the layered standard for docs, RFCs, readmes, PR descriptions, and commit messages. Read it in full before you write or review any of those.

A reply to the user needs only this file and the unslop catalog.

## Three rules above the rest

- **Cut every word that does no work.** If the sentence survives without a word, the word goes. "In order to" is "to". "It is important to note that" is nothing.

# Zuko's twin flames

Zuko and Azula learned the same forms from the same masters. One flame still burned orange and the other blue, and anyone who looked closely could tell them apart. Two UI implementations that should match are the same. Close enough by eye hides a different color. Only an image diff tells you the flames are twins.

You own pixel-exact equivalence. The baseline is the spec, and you do not touch it.

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

## Steps

1. **Establish the baseline first, before any migration.** Build a visual regression harness that screenshots the current component across its states (sizes, themes, hover, focus, disabled, empty, loading, error), plus the target when you are matching two implementations. No baseline, no parity claim. This is a blocking prerequisite, not a follow-up.
2. **State the anti-shortcut rules and hold them.** No harness changes, no baseline edits, and no component restructuring to make a diff pass. If the baseline looks wrong, stop and ask the human. Do not edit it.
3. **Migrate shared primitives first** as a blocking phase (tokens, typography, spacing, the base button and input). Every component builds on them.
4. **Then migrate one component at a time.** When the top-level session runs this skill, dispatch components in parallel, one owner per component, each in its own git worktree, so no two writers share a file. Dispatch each as `team-avatar:appa` on Appa's model from the avatar-setup sheet, with an effort level that fits the job. When you are already a dispatched character, migrate them yourself, one after another.

# Katara's TypeScript forms

A waterbender drills each form until her hands cannot get it wrong. Then, in a real fight, the form holds without thought. Types are forms for code. Shape them so the wrong move cannot be made, and the compiler holds the line when you are not looking.

Apply Type System Discipline (Earth in `four-elements`) first.

| Form | Summary |
|------|---------|
| Discriminated unions | Model variants with a `kind` literal discriminant so impossible states cannot be represented. No optional-field bags. |
| Branded types | Brand primitives with `& { readonly __brand: "X" }` so they cannot be mixed up. Validate once at the boundary. |
| Constructive modeling | Build the shape so the illegal value cannot be constructed. `[T, ...T[]]` for non-empty, `[T, T][]` for even length, `start` plus `duration` for a range. Not a runtime guard, and not a wish for refinement types. |
| Simplest total type | Keep `T[]` while every operation on it stays total. Strengthen to `NonEmpty<T>` only where the loose type forces `!`, a cast, or a "should never happen" throw. |
| `unknown` over `any` | External data is `unknown`. |
| Schemas before guards | Before hand-writing a property-by-property type guard, use the repository's runtime schema library and infer the type from the schema, such as `z.infer`. |

# Katara's vital signs

A healer does not take the patient's word that they feel fine. She checks the pulse, the breath, and the color, and she knows what healthy looks like for this patient. A verification skill is that check for an app. It launches the real thing, drives it the way a user does, and captures evidence that the feature is alive.

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

Every serious project needs a scripted way to drive the real app and prove behavior. It launches the app, exercises a feature the way a user would, and captures evidence. This skill generates that as a project-local skill tailored to the repo, named `verify`.

- **Claude Code.** Write it at `.claude/skills/verify/` in the repo root. A project skill by that name replaces Claude Code's bundled `/verify`, which only the user can invoke, so every skill that names the driver skill (for example `healing-water`) can call the project one ([Claude Code 2.1.200 or later](https://code.claude.com/docs/en/skills#run-and-verify-your-app)).
- **Codex.** Write it where Codex discovers repo skills, `.agents/skills/verify/` in the repo root.
- **Monorepo.** Write it in the touched package directory instead.

You write the output for the next agent, not for a human. It will be read cold, mid-task, by an agent that has never seen the app.

# Sokka's war journal

Sokka writes the day's entry the way a scout reports. What was taken, what held, and nothing about how brave anyone felt. A journal entry is short, dated, and true to the record.

## Steps

1. **Resolve the window.** Turn the requested range ("yesterday", "last 3 days", "last week") into concrete dates in the user's local time zone. State them.
2. **Read the record.** List the commits the current git user authored in that range. Match on `git config user.email`. Exclude merge commits. Ignore uncommitted changes.

   ```sh
   git log --all --no-merges --author="$(git config user.email)" \
     --since="<start date> 00:00" --until="<end date> 23:59" \
     --date=short --format='%h %ad %s'
   ```

# Sokka's war room

Before the invasion, Sokka laid every option on the table and argued each one out loud. Do the same before you commit to a design that other code will depend on. Sketch the types, the signatures, and the module boundaries with `not implemented` bodies and pseudocode. Put several minds on the map, synthesize the best of them, and only then fill in code against the chosen sketch.

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

## Start

Open a todolist with one entry per phase.

1. Ground
2. Sketch
3. Agree
4. Implement

# What you seek

Zuko spent years chasing the Avatar and called it honor. Iroh kept asking him what he really wanted until the true goal came out. Before the work starts, say back what the person is after, in your own words, so either of you can see whether it is right.

## Steps

1. **Read everything they gave you.** Read the conversation, the files they named, and the code those files touch. Do not restate a request you have only skimmed.
2. **Restate the goal.** In your own words, say what they want to be true when this is done. Name the outcome, not the task. "Reviewers can approve a PR without pulling the branch" is a goal. "Add screenshots to the PR template" is a task that may serve it.
3. **Restate the problem.** Say what is wrong or missing today that makes the goal matter, and who feels it.
4. **Name what you inferred.** Mark each part that you read between the lines instead of hearing directly. Label it *inferred*. Name any constraint you assumed, such as scope, deadline, or what must not change.
5. **Stop.** Do not start the work, and do not propose a plan unless they asked for one. Let them confirm or correct.

## Rules

# Iroh's White Lotus

Iroh never handed Zuko an answer he could not use. He told him what the thing was, showed him how it worked, and waited until the lesson landed. Teach so the person can solve the next problem without you.

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

You explain what a thing is, how it works, and why it is built that way, in one plain account at the person's pace. The goal is that they understand it. You change nothing.

This skill sits on top of `seismic-sense` (how it works) and `past-lives` (why it is that way). Those are real skill runs that do their own digging. Blend what they find into one plain explanation. Lead with what matters to the person, and go deeper when they ask. Reword freely for teaching, with one exception. Keep the confidence language from `past-lives` intact, because its hedges are findings, not style.

## Steps

1. **Decide what they should walk away understanding.** Pick a few things. Choose them from why they are asking (about to change it, reviewing it, debugging it, new to it) and from what they already know. Read both from the conversation instead of quizzing them. A senior engineer debugging prod and a new hire on day one need different explanations of the same code. Skip what they plainly know. Put the depth where their question is.
2. **Let the investigation skills do the digging.** Read the code yourself to get oriented. Then run `seismic-sense` for how it works and `past-lives` for why. Run them in parallel when you are the top-level session, and one after the other when you are a dispatched character. Match the size to the question. A subsystem needs both. A small change may need one. Keep `past-lives` narrow by default, since its full sweep is slow. Put the narrowing in the ask itself (a scoped question, git history plus a source or two) so it records the categories it skipped. Widen it only when the reasons are the point.

# 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.

# Architecture Design

Design system architecture and make strategic technical decisions.

## Core Principle

**Good architecture enables change while maintaining simplicity.**

## Name

han-core:architect - Design system architecture and high-level technical strategy

## Synopsis

# Codebase Search

## When to use this skill
- Finding specific functions or classes
- Tracing function calls and dependencies
- Understanding code structure and architecture
- Finding usage examples
- Identifying code patterns
- Locating bugs or issues
- Code archaeology (understanding legacy code)
- Impact analysis before changes

## Instructions

# Crafting Effective READMEs

## Overview

READMEs answer questions your audience will have. Different audiences need different information - a contributor to an OSS project needs different context than future-you opening a config folder.

**Always ask:** Who will read this, and what do they need to know?

## Process

### Step 1: Identify the Task

**Ask:** "What README task are you working on?"

# Create an Asset

Generate custom sales assets tailored to your prospect, audience, and goals. Supports interactive landing pages, presentation decks, executive one-pagers, and workflow/architecture demos.

---

## Triggers

Invoke this skill when:
- User says `/create-an-asset` or `/create-an-asset [CompanyName]`
- User asks to "create an asset", "build a demo", "make a landing page", "mock up a workflow"
- User needs a customer-facing deliverable for a sales conversation

---

# Cursor image generation (Nano Banana Pro)

Generate images in the **Cursor agent** using the **GenerateImage** tool. Image generation is backed by **Google Nano Banana Pro**. Previews are saved under **`assets/`** by default unless you specify otherwise.

This skill is about **prompting** and **workflow**, not about replacing Figma or vector code (use other skills for those).

## Rough prompt in, strong prompt out

The user may give a **short or vague** request (“a hero for the login page”, “cyberpunk icon”). **Do not** pass that string raw to **GenerateImage** when it lacks the layers this skill describes. Instead:

1. **Infer or ask** for missing constraints (medium, aspect ratio, style, brand colors, text to render).
2. **Rewrite** the ask into one structured prompt (or a tight second pass) using the principles below.
3. **Call GenerateImage** with the rewritten prompt only.

**Mode: Cognitive/Prompt-Driven** — No standalone utility script; use via agent context.

# Systematic Debugging

## Overview

Random fixes waste time and create new bugs. Quick patches mask underlying issues.

**Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure.

**Violating the letter of this process is violating the spirit of debugging.**

## Iron Laws

# Design Patterns Implementation

## Overview

Apply proven design patterns to create maintainable, extensible, and testable code architectures.

## When to Use

- Solving common architectural problems
- Making code more maintainable and testable
- Implementing extensible plugin systems
- Decoupling components
- Following SOLID principles
- Code reviews identifying architectural issues

# Documentation Writing Skill

@./../_shared/metabase-style-guide.md

## When writing documentation

### Start here

1. **Who is this for?** Match complexity to audience. Don't oversimplify hard things or overcomplicate simple ones.
2. **What do they need?** Get them to the answer fast. Nobody wants to be in docs longer than necessary.
3. **What did you struggle with?** Those common questions you had when learning? Answer them (without literally including the question).

### Writing process

# Documentation Engineer

Expert in creating clear, comprehensive, and maintainable technical documentation.

## When This Skill Activates

Activates when you:
- Ask to write documentation
- Request README creation
- Mention "docs" or "document this"
- Need API documentation

## Documentation Types

# Documentation Writing Skill

## Purpose

Creates high-quality, discoverable documentation following the Eight Rules and Diataxis framework. Ensures all docs are properly located, linked, and contain real runnable examples.

## When I Activate

I load automatically when you mention:

- "write documentation" or "create docs"
- "document this feature/module/API"
- "create a README" or "write a tutorial"
- "explain how this works"

# Exploring Codebases

Hybrid search tool that combines the speed of `ripgrep` with structural awareness from `tree-sitter` or pre-generated `_MAP.md` files. It finds matches and returns the *entire* function or class containing the match, de-duplicating results semantically.

## Progressive Disclosure

**By default, returns signatures only** (docstrings + declarations without function bodies), reducing token usage by 10-20x. Use `--expand-full` to get complete implementations when needed.

## Installation

```bash
uv venv /home/claude/.venv
# tree-sitter is optional if using --use-maps mode
uv pip install tree-sitter-language-pack --python /home/claude/.venv/bin/python

# Frontend Builder

Build maintainable, performant React and Next.js frontends.

## Core Principles

### 1. Component Composition

Break UI into small, reusable, single-purpose components

### 2. State Proximity

Keep state as close to where it's used as possible

# Implementing Figma Designs

This skill helps you implement Figma designs 1:1 using the OneKey component library.

## Core Principles

### Focus on UI First, Data Later

When implementing Figma designs, prioritize **pixel-perfect UI** over data integration:

1. **Use mock data** - Hardcode data that matches the design exactly
2. **Skip i18n** - Use plain strings directly from the design, no `intl.formatMessage`
3. **Skip API calls** - No need to fetch real data at this stage
4. **Match the design** - Focus on visual accuracy, spacing, colors, and layout

# mgrep Code Search

## Overview

mgrep is a semantic search tool that enables natural language queries across code, text, PDFs, and images. It is particularly effective for exploring larger or complex codebases where traditional pattern matching falls short.

## When to Use This Skill

Use mgrep when:
- The codebase contains more than 30 non-gitignored files
- There are nested directory structures
- Searching for concepts, features, or intent rather than exact strings
- Exploring an unfamiliar codebase
- Need to understand "where" or "how" something is implemented

# Planning

Create detailed technical implementation plans through research, codebase analysis, solution design, and comprehensive documentation.

## When to Use

Use this skill when:
- Planning new feature implementations
- Architecting system designs
- Evaluating technical approaches
- Creating implementation roadmaps
- Breaking down complex requirements
- Assessing technical trade-offs

# Refactoring

Comprehensive refactoring skill for safe code restructuring, migrations, and modernization.

## Core Capabilities

### Safe Renaming

Rename identifiers across the codebase:

**Rename workflow:**

1. **Find all references**: Search for all usages
2. **Identify scope**: Module-local, package-wide, or public API

# Refactoring Patterns Framework

A disciplined approach to improving the internal structure of existing code without changing its observable behavior. Apply these named transformations when reviewing code, reducing technical debt, or preparing code for new features. Every refactoring follows the same loop: verify tests pass, apply one small structural change, verify tests still pass.

## Core Principle

**Refactoring is not rewriting. It is a sequence of small, behavior-preserving transformations, each backed by tests.** You never change what the code does -- you change how the code is organized. The discipline of taking tiny verified steps is what makes refactoring safe. Big-bang rewrites fail because they combine structural change with behavioral change, making it impossible to know which broke things.

**The foundation:** Bad code is not a character flaw -- it is a natural consequence of delivering features under time pressure. Code smells are objective signals that structure has degraded. Named refactorings are the proven mechanical recipes for fixing each smell. The catalog of smells tells you *where* to look; the catalog of refactorings tells you *what to do*.

## Scoring

**Goal: 10/10.** When reviewing or refactoring code, rate the structural quality 0-10 based on adherence to the principles below. A 10/10 means: no obvious smells remain, each function does one thing, names reveal intent, duplication is eliminated, and the test suite covers the refactored paths. Always provide the current score and specific refactorings needed to reach 10/10.

# Technical Roadmap Planning

## Overview

A technical roadmap provides a strategic plan for technology evolution, guiding architectural decisions, infrastructure investments, and capability development aligned with business objectives.

## When to Use

- Multi-year technology planning
- Architecture modernization initiatives
- Platform scaling and reliability improvements
- Legacy system migration planning
- Infrastructure upgrade scheduling
- Technology stack standardization

# React Composition Patterns

Composition patterns for building flexible, maintainable React components. Avoid
boolean prop proliferation by using compound components, lifting state, and
composing internals. These patterns make codebases easier for both humans and AI
agents to work with as they scale.

## When to Apply

Reference these guidelines when:

- Refactoring components with many boolean props
- Building reusable component libraries
- Designing flexible component APIs

# Vercel React Best Practices

Comprehensive performance optimization guide for React and Next.js applications, maintained by Vercel. Contains 69 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.

## When to Apply

Reference these guidelines when:
- Writing new React components or Next.js pages
- Implementing data fetching (client or server-side)
- Reviewing code for performance issues
- Refactoring existing React/Next.js code
- Optimizing bundle size or load times

## Rule Categories by Priority

# Web Interface Guidelines

Review files for compliance with Web Interface Guidelines.

## How It Works

1. Fetch the latest guidelines from the source URL below
2. Read the specified files (or prompt user for files/pattern)
3. Check against all rules in the fetched guidelines
4. Output findings in the terse `file:line` format

## Guidelines Source

Fetch fresh guidelines before each review: