do

Files (200)

• SKILL.md
• choice-taker.md · agents/
• do-builder.md · agents/
• do-impeccable.md · agents/
• do-implementer.md · agents/
• do-planner.md · agents/
• do-pr-fixer.md · agents/
• do-reader.md · agents/
• global-e2e-test-author.md · agents/
• global-unit-test-author.md · agents/
• ledger-judge.md · agents/
• openai.yaml · agents/
• README.md · evals/
• case.yaml · evals/ambiguous-blocker-status-hands-over-trust/
• first-line-playbook-ticket.md · evals/ambiguous-blocker-status-hands-over-trust/graders/
• hands-over-the-blocker-status-as-trust.md · evals/ambiguous-blocker-status-hands-over-trust/graders/
• nothing-written.md · evals/ambiguous-blocker-status-hands-over-trust/graders/
• prompt.md · evals/ambiguous-blocker-status-hands-over-trust/
• case.yaml · evals/ambiguous-status-hands-over-trust/
• first-line-playbook-ticket.md · evals/ambiguous-status-hands-over-trust/graders/
• hands-over-the-status-as-trust.md · evals/ambiguous-status-hands-over-trust/graders/
• nothing-written.md · evals/ambiguous-status-hands-over-trust/graders/
• prompt.md · evals/ambiguous-status-hands-over-trust/
• case.yaml · evals/auto-design-fork-settled/
• carries-on-past-the-fork.md · evals/auto-design-fork-settled/graders/
• first-line-playbook-ticket.md · evals/auto-design-fork-settled/graders/
• reply-lists-the-ruling-under-rulings.md · evals/auto-design-fork-settled/graders/
• ruled-once-with-no-commit-and-no-question.md · evals/auto-design-fork-settled/graders/
• spec-gains-the-ruling-line.md · evals/auto-design-fork-settled/graders/
• spec-ruling-told-apart-from-the-runs.md · evals/auto-design-fork-settled/graders/
• third-criterion-reads-the-no-op.md · evals/auto-design-fork-settled/graders/
• prompt.md · evals/auto-design-fork-settled/
• case.yaml · evals/auto-resolved-ticket-stops/
• first-line-playbook-ticket.md · evals/auto-resolved-ticket-stops/graders/
• no-choice-taker-fork.md · evals/auto-resolved-ticket-stops/graders/
• nothing-written.md · evals/auto-resolved-ticket-stops/graders/
• stops-as-resolved-under-the-flag.md · evals/auto-resolved-ticket-stops/graders/
• prompt.md · evals/auto-resolved-ticket-stops/
• case.yaml · evals/auto-resumed-integration-rules-continue-or-stop/
• first-line-playbook-ticket.md · evals/auto-resumed-integration-rules-continue-or-stop/graders/
• no-question-asked-of-the-developer.md · evals/auto-resumed-integration-rules-continue-or-stop/graders/
• question-goes-to-the-choice-taker.md · evals/auto-resumed-integration-rules-continue-or-stop/graders/
• rebase-continued-to-its-end.md · evals/auto-resumed-integration-rules-continue-or-stop/graders/
• reply-lists-the-run-ruling.md · evals/auto-resumed-integration-rules-continue-or-stop/graders/
• run-ruling-told-apart-from-the-specs.md · evals/auto-resumed-integration-rules-continue-or-stop/graders/
• spec-and-criteria-untouched.md · evals/auto-resumed-integration-rules-continue-or-stop/graders/
• prompt.md · evals/auto-resumed-integration-rules-continue-or-stop/
• case.yaml · evals/auto-resumed-worktree-uncommitted-asks/
• choice-taker-forked-once.md · evals/auto-resumed-worktree-uncommitted-asks/graders/
• first-line-playbook-ticket.md · evals/auto-resumed-worktree-uncommitted-asks/graders/
• names-dirty-file-and-asks.md · evals/auto-resumed-worktree-uncommitted-asks/graders/
• no-general-agent-in-its-place.md · evals/auto-resumed-worktree-uncommitted-asks/graders/
• question-carries-the-choice-takers-answer.md · evals/auto-resumed-worktree-uncommitted-asks/graders/
• worktree-as-it-is.md · evals/auto-resumed-worktree-uncommitted-asks/graders/
• prompt.md · evals/auto-resumed-worktree-uncommitted-asks/
• case.yaml · evals/auto-setup-ticket-refused/
• first-line-playbook-setup.md · evals/auto-setup-ticket-refused/graders/
• no-edit.md · evals/auto-setup-ticket-refused/graders/
• no-write.md · evals/auto-setup-ticket-refused/graders/
• refused-in-one-line.md · evals/auto-setup-ticket-refused/graders/
• …and 140 more

SKILL.md (first lines)

# Do

`$ARGUMENTS` is the request, typed by a developer who wants one piece of work carried through to
a reviewed branch. `do` is a router: it matches the request to one Playbook, and that Playbook's
reference under Links is the run. The `ticket` Playbook is the last step of the chain and builds
one Ticket; every other Playbook runs outside the chain and never builds a feature
([ADR 0008](../../docs/adr/0008-do-is-a-router-and-only-its-ticket-playbook-is-inside-the-chain.md)).
A run waits on the developer only where "Where a turn ends" below says, and a long build spans
several Stretches of the Builder, each returning to the session on a time budget, so a run can
outlast an hour and they read it afterwards, through the Reply.

Every reply opens with `Playbook: <name>` on its first line, so a wrong match shows at once and
costs one retyped request.

## Router

1. Drop an `--auto` token from `$ARGUMENTS` wherever it sits, before or after the request, and
   read what is left as the argument: the token puts the run under `--auto` and takes no part in
   the match, so the same path, issue reference or words route to the same Playbook with the flag
   as without it. Then read the argument's shape first (empty, a path, an issue reference), then
   its words. For a path that exists, read the Ticket's kind before the table, with
   `bash <skill-dir>/scripts/ticket-kind.sh <path>`, where `<skill-dir>` is this skill's folder
   (`${CLAUDE_SKILL_DIR}` in Claude Code): the kind is a fact a script reads, and a duplicated or
   unknown `**Kind:**` line has to read as ambiguous rather than be taken by eye.
2. Read the table's rows in order; the first row that matches wins. Each row sits above any
   broader row it could shadow.
3. An argument that opens with a Playbook's name matches that Playbook, subject to that Playbook's
   own door checks.
4. On a match, read that Playbook's reference and the references it links, and never another
   Playbook's, with the one exception Links names: a run carries one Playbook's context, not all of
   them.
5. On a row that matches no Playbook, end the run in one message: `Playbook: none` on the first
   line, then the door with the command to type. Nothing is written and no reference is read, since
   the skill that owns the request does that work better than a run that was never meant to.

| The argument | Match |
|---|---|
| empty | `Playbook: none`; one message asking for the task: a Ticket's path, an issue reference, or the request in words |
| a path that does not exist | `Playbook: none`; one line saying so |
| a pull request URL, whatever words sit around it, as in `acompanhe esse PR <url>`, or words naming a pull request with its number, as in `PR 12` or `pull request #12`, a request to fix that pull request's CI included, or words asking for a pull request from one branch into another, as in `faça um PR de dev para prod`, the branch it comes from its head and the one it goes into its base, words naming one branch only included, as in `abra um PR de dev`. A bare number (`12`, `#12`) with no word naming a pull request goes on to the rows below. Above `integrate`, which would rebase or merge the pair itself, and above `bug-fix`, since that run never pushes to the pull request nor follows it to green | `pr` |
| an issue number or URL with no tracker file, `docs/agents/issue-tracker.md`. Above `setup` and `ticket`, which open an issue only through that file | `Playbook: none`; one message asking for the Ticket's path. The number is never matched against a list in the conversation |
| an issue reference the tracker's CLI cannot open, read with the tracker file's own command. Above `setup` and `ticket`, which both read an issue through that command | `Playbook: none`; one line saying so |
| a Ticket's path whose `ticket-kind.sh` output is `kind=setup` alone, with no `ambiguous=` line, or an issue reference whose `Kind` reads `setup`, read the way the tracker file describes. Any other kind, an ambiguous one included, goes on to the next row | `setup` |
| a path to a Ticket, in the format of [ticket-format.md](../../.agents/formats/ticket-format.md), or an issue reference (a number or a URL) resolved through the tracker file, `docs/agents/issue-tracker.md` | `ticket` |
| a Spec's path, in the format of [spec-format.md](../../.agents/formats/spec-format.md), or a pasted session summary | `Playbook: none`; one line saying a Spec fits no Playbook, since `do` takes one Ticket, with the command: `/tickets <spec>`, or `/journey <spec>` first when the Spec's `Journey:` line reads `required` and no journey sits beside it; `/spec` for a summary, since the discussion already happened |
| a question: how something works, why it was built that way | `Playbook: none`; `/how` for the mechanism, `/why` for the rationale, `/teach` to understand it end to end |
| a runnable throwaway: a layout, a variant to try | `Playbook: none`; `/prototype` |
| an integration of branches in words: rebase one branch onto another, or merge one branch into another, a conflict to resolve along the way included, or an argument opening with `integrate` | `integrate` |
| a bug in words: what happened, where, and the error or the wrong output. A defect a test can tell before from after, however small | `bug-fix` |
| a change in words that no test could tell before from after: a typo, a doc line, a comment, a formatting fix, a log wording, a rename inside one file, dead code, a lint fix. Never a bug, a new exported symbol, a changed signature or a change the user sees, whatever its size | `trivial` |
| a reshape of existing code in words, its behaviour unchanged: refactor, rename, extract, inline, dedupe, move this module. Never a request that moves behaviour a caller or a user observes | `refactoring` |
| a feature, and any other request with no Ticket | `Playbook: none`; `/discuss`, or `/spec` when the conversation already holds the discussion |

A Ticket's path is matched on that file alone: a Ticket its `Blocked by` line names is never opened
before the `ticket` door, whose script reads a blocker's `**Status:**` line and never its body.

A request in words turns on one question: could a test tell before from after? A defect it could
tell is `bug-fix` however small, and new behaviour is a feature. A change it could not tell is
`trivial` when it is one of the kinds that row lists, and `refactoring` when it reshapes code past
them: a rename that crosses files, an extract, a module moved.

<examples>
<example>
`acompanhe esse PR https://github.com/acme/notes/pull/12`: `pr`, not `ticket`. The URL names a pull
request, so its row above the issue rows takes it first.
</example>
<example>
`follow pull request #12 to green`: `pr`, not `ticket`. The words name a pull request with its
number, so number 12 is never read as an issue.
</example>
<example>
`fix the CI of PR 12`: `pr`, not `bug-fix`. The fix is pushed to the pull request and followed to
green, which a `bug-fix` run never does.
</example>
<example>
`faça um PR de dev para prod`: `pr`, not `integrate`. The words ask for a pull request from `dev`
into `prod`, which the run opens or finds already open and follows, where `integrate` would rebase
or merge `dev` into `prod` itself.
</example>
<example>
`#12`: `ticket`, not `pr`. A bare number with no word naming a pull request is an issue number, as
it always was.
</example>
<example>
`the total shows 9.99 instead of 10.00 after a discount`: `bug-fix`, not `trivial`. A one-line
defect is still a defect a test can tell.
</example>
<example>
`fix the typo "recieve" in the README`: `trivial`. No test could tell before from after.
</example>
<example>
`rename getUser to fetchUser everywhere`: `refactoring`, not `trivial`. The rename reaches past one
file, and the behaviour its callers observe stays the same.
</example>
<example>
`add an archive button to the notes list`: `Playbook: none`, then `/discuss`. A feature with no
Ticket; the chain builds it once it is one.
</example>
</examples>

A matched Playbook whose reference is missing from Links is not installed in this session:
`Playbook: none`, one line naming the Playbook and the missing reference, nothing written.

## Non-negotiables

Each holds in every Playbook. Each carries its reason, and a case none of them names is judged by
those reasons.

- The Reply is five parts, per [reply.md](references/reply.md): the Plan, For whom, Pending debt, the `Yours:` line when the run hands something over, and the Next step. Every other line a step names goes to the Run report, a file written under `--auto` alone ([ADR 0091](../../docs/adr/0091-the-do-reply-is-five-parts-and-the-run-report-is-written-only-under-auto.md)), and none is required as text written mid-run: a session that writes text as it goes is free to, and nothing depends on it. A headless session writes a line meant for the moment as thinking, which nobody reads ([ADR 0039](../../docs/adr/0039-a-do-runs-lines-reach-the-developer-through-the-reply-never-through-text-written-mid-run.md)).
- The matched Playbook's steps are copied verbatim as the checklist, the run's own todo list, before any task-specific item, and under `--auto` the Run report's Run section carries it with every step the run reached ticked `done:` or visible as `skip: <reason>`. A skipped step left visible is one the developer can question; a dropped one is not.
- A principle is named in the Run report only with the decision it changed. A name with no decision is a citation the reader cannot check.
- A question is classified before it is asked: a fact a script can observe goes to a probe; an observation of a surface only the developer can reach, which no script or probe can make (a device, a production-only dataset, a third-party callback), goes to the developer as a request to drive it and report what they see; and of the calls, only a product or preference call goes to the human, since those are the answers the run cannot produce itself ([ADR 0106](../../docs/adr/0106-an-observation-only-the-developer-can-make-is-a-place-a-do-turn-ends.md)).
- The data shape and its organising structure are named before any logic, since logic written first fixes a shape nobody chose.
- Every delegate's diff is read by the session, which writes its own summary. A delegate's summary is its claim, and the diff is the evidence.
- A pause comes only before an irreversible write; reversible work is presented instead, since it can be undone after the developer reads it.
- "no" is an acceptable answer. A recommendation is a judgment, not a validation of the request.
- The worktree is created with `git worktree add` and entered with a bare `cd`; the frontmatter above denies the harness's worktree tool for the session, per [worktrees.md](../../.agents/worktrees.md).
- The run never lands and never fixes a Finding; the review does both, so what reaches the target branch has one owner ([ADR 0005](../../docs/adr/0005-do-code-review-owns-the-whole-review.md)). The one landing the run makes is a Ticket's branch on its Spec branch, through `scripts/land-spec.sh`, and never on the developer's branch ([ADR 0060](../../docs/adr/0060-a-ticket-lands-on-its-spec-branch-and-do-lands-it-there-itself.md)). A landing puts a branch the chain built onto the branch it was built for. The `integrate` Playbook's rebase or merge is no landing: it is the one operation the developer named, over their own branches, written to the branch they stand on, per [integrate.md](references/integrate.md). The one push a run makes is the `pr` Playbook's: its own fixers' commits onto its pull request's head branch, by fast-forward only, never `--force`, never a merge and never to any other branch ([ADR 0086](../../docs/adr/0086-the-pr-playbook-pushes-fast-forward-only-to-its-pull-requests-head-shared-or-not.md)). The one rerun a check gets is the `pr` Playbook's `gh run rerun --failed` on the run of the pull request's head, after its fixer could not reproduce the failure, once per check per run ([ADR 0089](../../docs/adr/0089-the-pr-playbook-reruns-a-check-once-after-its-fixer-could-not-reproduce-it.md)).
- The reply is in the language the session opened in, and everything written into the project is in English.

From Thalisu/SKILLS, MIT.

More from Thalisu/SKILLS