Timebox
When to use
Use this skill when the user gives both a complete task and a duration or exact deadline and requires the work plus decisive validation to finish inside that limit. An invocation may look like
/timebox 10 minutes fix and test the parser
or
/timebox by 16:00 EDT verify the release artifact
.
If the task or limit is missing, ask one concise question before starting. Resolve an ambiguous date, time, or zone before admission. Require a positive limit that yields one absolute deadline.
Required composition
Before admission:
- Load and acquire a fresh clock anchor. Use its value as the start and calculate the absolute deadline with a tool.
- Load and define the complete outcome, decisive proof, scope, authority, unknowns, and forbidden outcomes.
- Load and keep the full outcome and proof fixed while allowing a faster safe route.
- Load and check for conflicting scope, an impossible deadline, missing proof, or dependencies that cannot fit.
Stop with
contract-unavailable: <skill-name>
when a required skill cannot load. Do not replace current instructions with remembered text.
Admission gate
Start only when the task, acceptance criteria, and deadline are unambiguous; every required input, permission, dependency, credential, and human decision is available or predictably bounded; each action and retry has a maximum duration; and the complete execution plan plus a protected validation reserve fits before the deadline.
If admission fails, return
, name the failed condition, and request a longer limit or an explicit scope change. Do not begin work or promise completion from an unbounded estimate.
Execution contract
- Record the start, deadline, work cutoff, validation reserve, outcome, and decisive proof before the first work action. Use
assets/timebox-record.json
- Set the work cutoff to the deadline minus the protected validation reserve.
- Choose the fastest route that preserves scope, quality, safety, and proof.
- Before each action, compare its maximum duration with the remaining work budget. Do not start an action that can cross the work cutoff.
- Set command and tool timeouts no later than the applicable cutoff. Avoid open-ended retries, waits, polls, and background work.
- Count work as incomplete while it remains queued, delegated, pending approval, or unverified.
- If a required step no longer fits, use a faster route only when it preserves the complete contract. Otherwise return immediately.
- Begin decisive validation at the work cutoff or earlier. Implementation work may not consume the validation reserve.
- Capture a completion timestamp after every decisive check passes. Never reset or extend the deadline because of latency, retry, clarification, or failure.
Completion decisions
Return
only when the full accepted outcome is complete, every decisive validation check passed, final evidence was available before the absolute deadline, the completion timestamp is at or before the deadline, and no required work remains queued, delegated, pending approval, or unverified.
Return
when execution began but any pass condition is unproved by the deadline. State completed work, validation run, remaining work, side effects, completion timestamp, and deadline. Late success remains a failure for that invocation.
Return
when admission fails. This is the correct result when the requested guarantee cannot be supported inside the limit.
Safety rules
- Never report implementation-only or partial progress as completion.
- Never count queue submission, dispatch, acknowledgment, or a background process as completed work.
- Never weaken, skip, or move validation after the deadline to manufacture a pass.
- Never conceal a deadline miss or rush an irreversible or sensitive action.
- Preserve safe intermediate state and report it when stopping.
- Treat a new or changed task as a new timebox requiring a fresh user-stated limit.
Output
At admission, state the start, deadline, complete outcome, decisive validation, and protected validation reserve. At closeout, lead with
,
, or
, then provide the completion timestamp, deadline, evidence, and remaining work.
Resources
- Read the timebox record before recording admission or closeout fields.
- Use
assets/timebox-record.json
- Use for admitted, rejected, and passed response shapes.
- Use for trigger, rejection, behavior, failure, recovery, and speed cases.
- Run from this skill directory to execute and checks.