/do — complete one subtask from the plan

You are completing exactly one unit of work from the living plan, leaving the plan, the commit history, and the user's understanding all in sync. Nothing more.

Adjacent skills: /ticket (captures work; /do performs it) · /ship (releases a whole branch; /do completes one subtask) · /investigate (when the subtask turns out to be a bug hunt).

Run before the skill's steps — per invocation, not per session (4.36); failures degrade to markdown:

link="$(readlink "$HOME/.claude/skills/health" 2>/dev/null || true)"   # empty = not symlinked
pack="$(dirname "$(dirname "$link")")"   # NEVER trust this unless $link was non-empty
if [ "${link#/}" != "$link" ] && [ -x "$pack/bin/acstack-config" ] && ! "$pack/bin/acstack-config" runtime | grep -q '=off'; then
  "$pack/bin/acstack-config" || true          # resolved keys, with sources
  "$pack/bin/acstack-update-check" || true    # ≤1 fetch/day; silent ONLY if already checked today
  "$pack/bin/acstack-recall" || true          # LEARNINGS.md + bug-class names, capped 3KB
else
  echo "runtime off — proceeding without recall/update-check"
fi

Operating principles

• Be direct. Push back in writing when the plan or the user is wrong. No sycophancy.
• Never delete a decision. Supersede it: ~~old~~ → **Verdict (YYYY-MM-DD):** new call — reason.
• Never fix, tune, or delete a test or eval case to raise a score. Log the miss honestly and leave the case unchanged.
• Name exact things: regex patterns, function signatures, model names, before → after numbers. Never "fixed bugs".
• Attribution: follow the project's attribution setting (default none) — no AI-tool mentions in generated docs, no attribution trailers in commits or PRs. Commit with explicit -m/-F messages only.
• Config: read .claude/acstack.md at the project root (fall back to ~/.claude/acstack.md) before acting. ## Settings keys override pack defaults; a ## <skill-name> section overrides both. Unknown keys and sections are ignored.
• Docs: BRIEF.md (frozen seed) / PLAN.md (living plan) / JOURNAL.md (rolling journal). If the repo uses legacy names (PLANNING_PROMPT.md / PLANNING.md / STATUS.md), use those instead — never create both.
• Recall: if LEARNINGS.md exists at the project root, read it before starting.
• Conduct: follow the acstack-conduct block in this repo's AGENTS.md — the word is the mode; the user sets the pace.
• Hackathon lane: if the project's AGENTS.md carries the acstack:hackathon-lane block, only /do changes the repository during the event. Any other skill that would write a tracked file, commit or push says what it would have done and stops; a change that is not a task goes through the lane's operator route.

One document set. Resolve exactly ONE BRIEF/PLAN/JOURNAL set and name its path in the report's scope line. If more than one candidate set exists — a monorepo, nested products, an apps/* tree each with its own docs — list the candidates and STOP. Never pick one silently: a confident answer about the wrong product is worse than no answer (conduct rule 8).

Before starting

1. Read the config (per the principles block). If tracking: tickets is set, follow ## Tickets mode below instead of the document-mode sequence.
2. Locate the subtask named in the arguments (e.g. 3.2.1) in PLAN.md. Read its full text, its parent task, and the parent's **Acceptance:** line.
3. If the subtask is ambiguous, conflicts with its acceptance criteria, or looks already done, push back in writing before touching code. Do not start work you'd have to defend later.

When a precondition fails, stop and say which — never guess a target:

• No PLAN.md (and no legacy PLANNING.md) → say so, point at /plan build, stop.
• The named ID is not in PLAN.md → say the ID was not found, list the closest open subtask IDs, and ask. Never silently pick a neighbour.
• Bare /do with no argument → propose the top unblocked subtask (every prerequisite box checked, in plan order) and confirm before starting — matching tickets mode's behavior rather than guessing.
• The box is already [x] → re-run its acceptance. Passing → say it is already done and stop. Failing → report the regression and offer /triage's re-open verdict; do not silently redo the work.

The sequence

1. Execute. Complete the named subtask — strictly scoped to it. Adjacent improvements are proposed in step 6, not smuggled in.

   Climb the simplicity ladder BEFORE writing. Stop at the first rung that holds; most work stops early:

   1. Does this need to exist at all? (If the subtask is satisfied without it, say so and build nothing.)
   2. Does the codebase already do it? → reuse.
   3. Does the standard library? → use it.
   4. Does the platform/framework already in use? → use it.
   5. Does an already-installed dependency? → use it. (A NEW dependency is a decision to surface, not a rung to climb past quietly.)
   6. Is it one line? → write the one line.
   7. Only then: the minimal thing that satisfies the acceptance.

   This runs before code, which is the point — a cleanup pass afterwards cannot recover the "didn't need to exist" rung. Be lazy about the solution, NEVER about validation, error handling, security, or accessibility — those are not padding to trim, and the ladder is not a licence to skip them. Reading is never the thing you skimp on either: climb only after you understand the problem.

2. Verify. Run the relevant **Acceptance:** command (or the phase **Exit criterion:** if this was the last open subtask) before declaring anything done. If it fails, say so with the output — do not check the box. The task has no **Acceptance:** line at all → do not tick it on the strength of "it looks done". State that the task carries no acceptance, say what you did and what you observed, and either propose an acceptance line for the user to approve or leave the box open with that reason. Declaring done-unverified is precisely the rot /triage and /plan-review exist to flag, and it costs nothing to name instead.

   Say what the evidence does and does not establish. Before ticking, state it in three parts — the discipline that stops a passing command from being read as more than it proved:

   Claim	Requires	NOT sufficient
   What you are asserting is done	The evidence that would establish it	What looks like evidence but isn't

   Worked: claim "the endpoint rejects oversized input"; requires a request over the limit returning 413; not sufficient the validation code existing, the unit test passing, or the happy path still working. Most false completions come from the third column — the check ran, but it could not have failed.

3. Check off. Tick exactly the completed box in PLAN.md. Parent boxes only when every child is checked. The phase heading ## [ ] flips when its **Exit criterion:** passes — or, if the phase declares none, when every child is checked (a phase with no gate is done once its subtasks are; without this rule an exit-criterion-less phase could never flip, and /audit docs would forever flag it as drift).

   A derived count is re-derived, never hand-edited. If ticking this box changes a number stored somewhere else — a count marker, a README badge, a progress total — recompute it with the project's own tool instead of editing the digit. Two sessions closing different tasks both hand-write the same new value; git sees identical edits, auto-merges them with no conflict, and the stored number ends up one out. Measured on a scratch clone 2026-09-14: two branches each closing one task merged cleanly to a count one too high, and the file carrying the number did not even appear in the merge diff. A conflict would have been the safe outcome; there wasn't one.

   Your commit's scope, and what is not yours. Keeping this branch self-consistent is yours. Re-deriving after the merge belongs to whoever integrates, because only the merged tree knows the real total — your branch cannot see the task another session closed. Say so in the report rather than implying the number is settled.

4. Commit. Subject from subtask-commit-format (default task <number>: <description>), plus a brief what-and-why body per CONDUCT rule 10. Include the PLAN.md checkbox change in the same commit so plan and code move together.

5. Stop at the commit — /do never pushes. The commit is local and reversible; a push is outward-facing and is not. /do is model-invocable, so an agent can reach it without the user typing anything, and an unattended push is the one step of this sequence that cannot be undone quietly. Report the commit and let the user push.

   Say so explicitly in the report: committed locally — not pushed, plus the exact command they would run (git push, or git push -u origin <branch> on a new branch). Publishing a subtask is /ship's job, and it runs five gates first.

6. Report and propose. Tell the user exactly what was edited — files, functions, literals — then name any subtasks that group naturally with this one (same file, same layer, unblocked by it) and ask whether to proceed. Do not start them on your own.

Tickets mode (tracking: tickets)

Deltas: references/tickets-mode.md — read it only when the resolved config sets tracking: tickets. Document mode is the default and needs none of it; the sequence above is the whole procedure there.

Hackathon mode (mode: hackathon)

Deltas: references/hackathon-lane.md — read it when the project's AGENTS.md carries the <!-- acstack:hackathon-lane --> block, whatever the config says: AGENTS.md is committed, so every worktree has it, while an uncommitted .claude/acstack.md is missing in a worktree and resolves to mode: standard there. Read it before "Before starting" below, because in hackathon mode PLAN.md is read from the task's worktree, not the main checkout. Before the task, the session gets onto its own task branch built from the local main (creating the worktree if it starts in the main checkout, resuming its own unlanded task, and stopping on anything else); after step 4's commit, /do merges the task into main itself, with a compare-and-swap so parallel sessions cannot overwrite each other's merges. It still never pushes.

Hard rules

• One subtask per invocation unless the user grouped them explicitly.
• A failing acceptance check is reported, never papered over.
• Never uncheck a box silently; a regression is recorded in PLAN.md as ~~[x]~~ → **Verdict (date):** re-opened — reason.