| name | ship-task |
| description | Complete the next task end-to-end with a confidence gate before shipping. Runs four phases in strict order: (1) complete the next task from a doc or beads backlog, (2) self-report confidence 0-100% and iterate until ≥95%, optionally escalating to an external Grok second opinion (user relays the prompt + response) when confidence stalls, (3) update any documentation learned this session, (4) commit. Use when the user says "ship the next task", "/ship-task", "finish the next one", or asks to run their standard completion workflow. |
Ship Task
End-to-end workflow for completing a task with a quality gate before commit. The user invokes this deliberately — follow the phases in order, do not skip, do not reorder.
Core principle
The confidence gate is the whole point. Do not let "this is a small change" collapse Phase 2 into a single self-congratulatory sentence. An honest 78% that leads to fixing three gaps is the value this skill delivers.
Phase 1 — Complete the next task
Identify the task source. Ask the user if ambiguous:
- Task document — a markdown/spec file the user has referenced or has open
- Beads backlog — if the project uses beads (
br / beads_rust), run br ready to see ready tasks, then br show <id> for details
If neither is obvious, ask: "Which task should I work on — something from a doc, or the next ready item in beads?"
Once the task is identified:
- Restate the task in one sentence so the user can confirm you've understood it
- Complete the work using your normal engineering discipline (read before editing, test where practical, follow existing patterns)
- Do not move to Phase 2 until you believe the task is functionally done
Phase 2 — Confidence check (loop until ≥95%)
Confidence is not a gut number. It's the arithmetic sum of four 0–25 axes, each scored against concrete evidence. The structure is the whole point: it forces gaps to be named instead of hand-waved.
The four axes
Each axis is scored 0–25. Total 0–100. Gate: ≥95 AND no axis below 15.
-
Requirements Fit (0–25) — Does the change exactly solve the task as specified? Scope, success criteria, acceptance conditions all met. No tangents, no omissions, no "elegant solution to the wrong problem."
-
Functional Robustness (0–25) — Happy path AND relevant edge cases / failure modes / boundaries / concurrency / state transitions behave as expected. Crashes, retries, reconnects, race conditions, partial-failure handling all considered.
-
Verification Evidence (0–25) — Claims are proven by executed tests, probes, logs, headless-browser runs, or real-environment checks — not asserted by code inspection. "I read the code and it looks right" is not evidence.
-
System Safety & Integration (0–25) — Verified against real dependencies (no mocks-only). Blast radius assessed. Reversible. No regressions in other services/pages. Observability hooks where needed.
Per-axis scoring anchors
Quote these to yourself before assigning a number:
- 20–25: Exhaustive evidence. Real integration / staging runs, fuzz or property tests where applicable, full coverage of the edges named in the task, blast radius explicitly measured or proven negligible.
- 12–19: Solid but with gaps. Unit tests + one manual probe; some edges reasoned but not exercised; one dep still mocked.
- 5–11: Mostly inspection plus happy-path tests. Some real verification, clearly incomplete.
- 0–4: Hand-wavy. No real evidence.
Required output format
Output exactly this shape, every time:
Phase 2 — Confidence Gate
1. Requirements Fit: X/25
- Evidence:
- [concrete action — e.g. "task spec said 'render UFC + MLB filter pills'; both rendered, screenshot at /tmp/...png"]
- [concrete action]
- To honestly score 25 I would need to: [one concrete piece of work, or "already at 25"]
- Self-critique: [one sentence on what could still be wrong]
2. Functional Robustness: X/25
- Evidence: [...]
- To honestly score 25 I would need to: [...]
- Self-critique: [...]
3. Verification Evidence: X/25
- Evidence: [...]
- To honestly score 25 I would need to: [...]
- Self-critique: [...]
4. System Safety & Integration: X/25
- Evidence: [...]
- To honestly score 25 I would need to: [...]
- Self-critique: [...]
Total: X/100. Gate (≥95 AND no axis <15): [PASS / FAIL]
If PASS: "I am ready to commit."
If FAIL: "Addressing [specific axis] before re-scoring."
Discipline rules
- Total is the strict arithmetic sum. No rounding up. 23+24+24+24 = 95, passes. 23+24+24+23 = 94, fails — go fix something.
- Per-axis floor: any axis <15 fails the gate even if total ≥95. Stops the "compensate one weak axis with three strong ones" pattern. A 25/25/25/20 = 95 passes; a 25/25/25/14 = 89 fails for both reasons.
- Any axis <20 in a passing score requires a one-paragraph justification of why that gap is acceptable for this specific task.
- Evidence must be concrete actions taken, not claims. "Tested the function" is not evidence. "
mix test test/foo_test.exs:42 → 12 assertions green" is evidence.
- Iterate, don't inflate. If gate fails, do the work named in the lowest-scoring axis's "to honestly score 25" line, then re-score from scratch. Don't bump numbers without new evidence.
Non-applicable axes
Some tasks legitimately have no surface for one or more axes (e.g. a pure rename refactor has no new "Requirements Fit" surface beyond "the rename is consistent"; a docs-only change has no "System Safety & Integration").
Do not score N/A axes 25/25 by default — that rubber-stamps them. Instead:
"Axis [N] is N/A for this task because [one-sentence justification]. Re-weighting remaining axes to ~33.3% each (or 50% each if two are N/A). Gate: ≥95 of the re-weighted total, AND no remaining axis below 15."
The re-weighted total is still on a 100-point scale (each remaining axis × the new per-axis maximum). Two N/A axes max out at 50/50; one N/A axis max at 33/33/33+1 → cap at 100. Math stays simple; the justification is the work.
Optional escalation — Grok second opinion
If confidence stalls (e.g., you've iterated once or twice and can't honestly cross 95%) and the remaining gaps are the kind that benefit from an outside perspective, you may ask the user to relay a query to Grok.
When to escalate to Grok (all should apply):
- Confidence is stuck below 95% not because of missing tests or obvious gaps you can fix yourself, but because of genuine uncertainty about correctness, design, or edge cases
- The question is one another model could meaningfully weigh in on — e.g., "is this algorithm correct?", "is this API design sensible?", "am I missing a failure mode?", "is this migration safe under concurrent writes?"
- You have a specific question, not a vague "review this"
When NOT to escalate:
- You just need to write more tests or read more code — do that yourself
- The task is small or low-stakes — the paste-in/paste-out cost isn't worth it
- You've already consulted Grok once this session and incorporated the feedback — don't loop
How to escalate:
Tell the user: "I'd like a second opinion from Grok on [specific concern]. Here's the prompt to paste — let me know what Grok says."
Then output the prompt inside a fenced code block, formatted so the user can copy it verbatim:
```
I'm reviewing code written by another AI assistant and want an independent second opinion on a specific concern.
**Goal of the change:** <one-sentence description of what the task is trying to accomplish>
**What was built:** <concise summary — key functions, data flow, or decisions>
**Specific concern I want you to evaluate:** <the exact question — e.g., "Is the locking strategy in `acquire_lease()` safe under concurrent callers on the same key?">
**Relevant code:**
```<language>
<only the snippets directly relevant to the concern — trim aggressively>
```
**What I've already considered:** <the reasoning you've already done, so Grok doesn't re-tread it>
Please give me: (1) your verdict on the specific concern, (2) any failure modes or edge cases I haven't listed, (3) anything you'd change and why. Be direct — I want disagreement, not validation.
```
After the user pastes Grok's response:
- Read it critically. Grok is fallible — don't capitulate to authority. For each point Grok raises:
- If it identifies a real gap or failure mode → address it in the code, then note the fix
- If it's misguided or based on a misreading → state your counter-argument explicitly (e.g., "Grok suggested X, but that doesn't apply here because Y — keeping the current approach")
- Briefly tell the user what you incorporated vs. what you pushed back on, and why
- Re-state confidence with the new information
If a second Grok round is genuinely needed, it's allowed — but if you're about to escalate a third time, stop and ask the user whether the requirement itself needs clarification instead.
Do not proceed to Phase 3 until confidence is ≥95% and the user has seen the final number.
If you can't credibly get to 95% (e.g., the requirement is genuinely ambiguous, or the test environment is unavailable), stop and tell the user exactly why — don't inflate the number to clear the gate.
Phase 3 — Update documentation
Review what was learned or changed this session and update anything that's now stale or incomplete. Candidates:
- README.md — if user-facing behavior, setup, or commands changed
- CLAUDE.md / AGENTS.md — if conventions, gotchas, or workflows were clarified. Edit the narrowest file that covers the change (per-service / per-package over the repo root); only touch the root file if the lesson is genuinely cross-cutting policy. Nested CLAUDE.md/AGENTS.md auto-load when work touches their subtree, so root edits about service-specific details just rot.
- Inline comments — only where logic is non-obvious (do not add comments to self-evident code)
- Beads task notes — if using beads,
br update <id> to reflect outcome/decisions
- Spec or design doc — if the task referenced one and the implementation diverged
Rule: only update docs where something genuinely changed or a non-obvious lesson was learned. Do not create new docs unless clearly warranted. No speculative documentation.
Briefly tell the user what you updated (or "nothing needed updating, because...").
Phase 4 — Commit
Invoke the /commit skill (or the project's equivalent commit workflow). Let that skill handle staging, message format, and hook handling — do not reimplement it here.
If the project doesn't have a /commit skill configured, fall back to:
git status and git diff to review- Stage specific files (not
-A / .)
- Write a concise message focused on the why
- Create the commit
- Verify with
git status
Do not push unless the user explicitly asks.
Anti-patterns to avoid
- Reporting "99% confident" on the first attempt for a non-trivial change — that's a tell that you didn't actually introspect
- Skipping Phase 2 because "the change is small" — small changes are where confidence checks catch the silly mistakes
- Scoring four 24s by default — the rubric is meant to find the weak axis, not produce a flat ribbon. If your first pass is 24/24/24/24, you skipped the introspection. Re-score with the per-axis evidence requirements taken seriously.
- Marking an axis N/A to dodge it. N/A means "this task literally has no surface for this axis" (e.g. docs-only change for "Functional Robustness"), not "I didn't bother to verify."
- Confusing claims with evidence. "I checked the edge case" is a claim. "Ran
bd show qh-XX to confirm acceptance criteria; ran the LiveView test asserting the empty-list path; manually clicked the button in dev-browser and screenshotted the empty state at /tmp/foo.png" is evidence.
- Updating docs in Phase 3 that weren't affected by this session — keep the diff tight
- Running Phase 4 before the user has acknowledged the confidence gate result
