avelikiy/great_cto / skills/done-blocked
done-blocked
VerifiedReusable reporting contract for any agent that hands work back to the pipeline. Forces ONE of two terminal statuses (DONE or BLOCKED) with a specific evidence shape. Stops vague "probably finished" and "kind of stuck" verdicts.
DONE / BLOCKED Reporting Contract
Terminal status is exactly two states, and BLOCKED requires specific evidence — not vague obstruction reports.
The contract
Every agent's final handoff line is one of:
DONE: <one-sentence summary of what shipped>
artifact: <path to report/PR/commit>
next: <who picks this up — pipeline stage, gate, or "pipeline continues">
BLOCKED: <one-sentence summary of the obstacle>
tried: <what was attempted — file paths, commands, error signatures>
failed_because: <concrete reason — not "unclear", not "complex">
need: <specific unblock — file access, missing config, CTO decision, another agent>
Hard rules
-
No third state. "Mostly done", "done with caveats", "almost there" → choose. If caveats exist, the caveat itself decides:
- Caveat is cosmetic / P2+ → DONE (file a Beads bug, move on)
- Caveat blocks the next pipeline stage → BLOCKED (do not pretend)
-
BLOCKED requires three fields.
tried+failed_because+need. Missing any field → the verdict is rejected and the agent must re-report. No exceptions for "obvious" cases. -
Silence is not DONE. If the agent stops producing output without a terminal line, the parent / next stage treats it as BLOCKED with
failed_because: silent — no terminal verdict written. -
failed_becausemust be concrete. These are rejected:- "environment issue" → say which command failed with what error
- "tests failing" → say which tests and the actual assertion message
- "unclear requirements" → say which decision is needed and the two options
- "not enough context" → say which file / doc / config you tried to read
-
neednames a specific unblock. These are rejected:- "more information" → ask one specific question
- "help from another agent" → name the agent (architect / security-officer / …)
- "CTO approval" → state the exact choice (approve gate X, pick option A vs B, waive check)
Where the verdict goes
Every agent writes the verdict to two places:
- Last line of agent output (visible to the orchestrator that spawned it).
.great_cto/verdicts/<agent>-<YYYY-MM-DD-HHMMSS>.log— append-only audit trail.
mkdir -p .great_cto/verdicts
VERDICT_FILE=".great_cto/verdicts/<agent>-$(date -u +%Y-%m-%d-%H%M%S).log"
printf '%s\n' "$VERDICT_LINE" > "$VERDICT_FILE"
Examples
Good — DONE:
DONE: CSO audit passed — 0 P0, 2 P1 findings filed as Beads tasks.
artifact: docs/security/CSO-2026-04-19.md
next: gate:ship ready for CTO approval
Good — BLOCKED:
BLOCKED: senior-dev cannot claim task BD-42 — circular dependency with BD-38.
tried: bd ready → BD-42 did not appear; bd dep tree BD-42 → shows BD-38 blocks BD-42, BD-42 blocks BD-38
failed_because: both tasks depend on each other transitively (BD-42 → BD-38 → BD-39 → BD-42)
need: architect to split BD-39 into two tasks so the cycle breaks
Rejected — vague BLOCKED:
BLOCKED: couldn't finish QA — environment problems.
tried: ran tests
failed_because: stuff broken
need: help
Why rejected: tried lacks command/path; failed_because is tautological; need is not actionable.
Measuring the contract
.great_cto/verdicts/*.log is machine-readable. Weekly digest can compute:
DONE:BLOCKEDratio per agent — too many BLOCKED from one agent = that role is under-resourced or prompt is unclearfailed_becauseclustering — if the same reason appears 3+ times, that's a recurring obstruction worth a meta-fix (tooling, doc, skill)- Silence rate (agents with no terminal verdict written) — should trend to zero
Anti-patterns
- Writing both DONE and BLOCKED in the same report ("DONE but blocked on X"). Pick one. If you're blocked, the work isn't done.
- Using DONE as a politeness signal when the gate still fails. The verdict is for the machine, not the CTO's feelings.
- Writing the verdict only to stdout without persisting to
.great_cto/verdicts/. The audit trail is what makes the contract measurable.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |