task-spec — define the task before you do it

Why this exists

Most task failures are not execution failures — they are definition failures. An agent (or a person) that starts work before "done" is judgeable will produce something plausible that nobody can confirm is correct, and the gap only surfaces after the work is wasted. This skill front-loads that risk: it makes you turn a fuzzy request into a TaskSpec — a definition concrete enough that both a machine and a reviewer can tell whether the result is acceptable — before any real work begins.

The payoff is not bureaucracy. A good TaskSpec is the cheapest possible place to catch "we were aiming at the wrong thing," and it gives the downstream work a target function, an evidence standard, and clear human-review points.

The full data structure has 13 sections (see references/taskspec-schema.md). You rarely need all of them. The spine below — goal, inputs, constraints, evidence, success criteria, human-review points — is what makes a task judgeable.

The four moves

Work through these in order. Each move has a concrete output; don't skip to execution until move 4 says the definition is judgeable (or a human has signed off on what's still ambiguous).

Move 1 — Profile the task

Read the request and any supplied material, then extract a structured profile. Surface what's there AND what's missing — the gaps are the whole point.

Produce these seven elements (omit one only if genuinely N/A):

• task_type — what kind of task this is (analysis / writing / decision / review / automation …)
• primary_goal — the single core objective, stated so it could be checked
• required & missing inputs — what's needed to do this reliably, and what's not yet supplied
• evidence_requirements — which conclusions must be traceable to a source
• constraints / boundary — hard limits that must not be crossed (compliance, authority, scope)
• risk_points — where this could go wrong or do harm
• suggested_output_structure — the shape of the deliverable

If the request is rich, this is extraction. If it's a one-liner, this is mostly missing_inputs and risk_points — and that's a signal the definition is thin.

Move 2 — Score how judgeable the definition is

A definition is "judgeable" when an independent party could look at the result and the spec and agree on whether the task succeeded. Check the goal against these 8 dimensions — each is a yes/no with a reason:

These deliberately adapt SMART for agent work: classic SMART stops at "measurable," but an agent also needs to know when it's done, when to stop, what it may never do, and what must be backed by evidence. Those four are where vague tasks quietly go wrong.

A rough clarity read = fraction of dimensions that pass. Anything below ~85% means the definition isn't ready to execute on its own.

Move 3 — Clarify only what matters, then converge

For each dimension that failed, you could ask the user a question. Don't ask all of them. Interrogating someone with a 10-question form is its own failure mode — it pushes the cognitive load back onto the person this is meant to help.

Rules:

• Ask only high-impact questions — the ones where a different answer would meaningfully change the work. A missing deadline on a low-stakes task isn't worth a round-trip.
• Prefer choices over open prompts where you can offer sensible options.

Stop and wait — don't run ahead on assumptions. This is the part that's easy to get wrong. The temptation, once you've profiled a task, is to pick sensible defaults for every gap and barrel straight through to a finished artifact "to be helpful." Resist it. Separate the gaps by impact:

• Low-impact gap → fill it with a clearly-labeled default and keep going. ("Assuming UTC unless you say otherwise.") The cost of being wrong is small and easily corrected.
• High-impact gap → stop and ask, then wait for a real answer before executing. Do not produce the deliverable on an assumed answer to a high-impact question. A high-impact gap is one where the wrong guess means redoing the work, shipping something harmful, or touching something irreversible (deleting data, sending to customers, spending money, crossing a boundary). For these, "I'll proceed with a reasonable assumption" is exactly the failure this skill exists to prevent — the whole point is to catch the wrong target before the work, not after.

You may absolutely propose a recommended answer alongside the question (it makes the user's reply a quick yes/no rather than an essay). What you may not do is act on that recommendation, for a high-impact gap, without their confirmation.

Clarification is a multi-round loop, not a one-shot form. Each round: ask the high-impact questions, take the user's answers, fold them in, re-score the 8 dimensions, and decide whether to ask again or proceed. Converge — don't loop forever. End the loop when ANY of:

• the definition clears the bar (~85% of dimensions pass), or
• you've done 3 rounds of clarification, or
• a round produced no improvement over the previous one.

When you stop with gaps still open (round cap hit, or no progress), don't pretend they're resolved — list the remaining ambiguities and route them to human review rather than guessing. An honest "these 2 points need a human call" beats a confidently wrong assumption.

This convergence rule is load-bearing: it's what keeps the skill from turning into an endless questionnaire while still refusing to silently paper over real ambiguity — and the stop-and-wait rule is what keeps it from "helpfully" executing on a definition that isn't actually settled yet.

Move 4 — Make success criteria checkable, and grade risk

Compile the success criteria into checks. Each criterion in the spec should become an explicit, per-criterion check that can be judged against the actual deliverable — with evidence (the specific passage / data point that supports the verdict), not just a thumbs-up. A criterion you can't turn into a check is a criterion that's still too vague — send it back to move 2.

Each check yields one of: pass / fail / uncertain.

Grade each action by risk before committing or finalizing. Map every verdict (and every risky step) to one of five dispositions, and act accordingly:

The report-level disposition is the most severe across all items. And the finalize gate: you may only finalize/commit once every item that isn't pass has been explicitly dispositioned by a human (approved or consciously overridden). This is what keeps "verified" honest — nothing risky ships on a silent assumption.

Output

Default deliverable: a TaskSpec in YAML (English keys, values in the user's language; keys come from references/taskspec-schema.md — don't translate keys), plus:

1. the clarity read (which of the 8 dimensions pass, which don't),
2. the clarifying questions you're actually asking (only the high-impact ones),
3. the compiled checks for the success criteria, and
4. the risk grading / finalize-gate status.

The spec must be self-contained. Whoever — or whatever — consumes it may not have the source material, this conversation, or this skill in front of them. So inline every load-bearing element; never leave a pointer that resolves to nothing on the other end. In particular, when you turn a rich source document into a TaskSpec, do not reference its section numbers (§4, 见 §6 决策表) — pull the actual data contracts, formulas, checks, and rubrics into the spec as concrete fields. Likewise never reference earlier conversation ("see above") or this skill's own Move numbers. A §4 in the output is not shorthand; it is a dangling pointer that silently drops the content a downstream consumer needs — and it reads as if the content is present when it isn't, which is exactly the kind of hidden hole this skill exists to prevent. Internal references within the same spec (e.g. a field pointing at inputs.missing_inputs) are fine — those resolve.

Keep the spec to the sections that carry weight for this task — a minimal judgeable spec beats an exhaustive one nobody reads. The minimal viable spine:

task_name: <name>
task_type: <kind>
goal:
  primary_goal: <single checkable objective>
  success_criteria: [<criterion you can check against rule/evidence>, ...]
  done_predicate: <what "complete" means>
  failure_conditions: <what triggers stop / escalate>
inputs:
  required_inputs: [...]
  missing_inputs: [...]   # the gaps you surfaced
constraints:
  permission_boundary: <what must never be crossed>
evidence:
  evidence_required: true|false
  citation_rules: <which conclusions must be sourced>
human_in_loop:
  confirmation_points: [...]
  approval_points: [...]
outputs:
  output_format: <shape of the deliverable>

See references/taskspec-schema.md for the full 13-section structure and field meanings when a task needs the richer sections (tools, workflow, validators, learning).

Pre-publish self-check (the gate)

Before you mark a spec as published/ready — or hand it off as done — run this self-check. These are not "recommended"; they are the bar. The host app enforces the same four mechanically (lib/validators/spec-gate.ts); this is the portable version you run yourself.

The governing principle is reward honesty: a draft that openly carries <待确认> gaps and a non-published status passes — admitting incompleteness is correct. The strict checks fire only when a spec claims to be ready. The gate targets specs that look finished but aren't, never specs honest about their holes.

1. Required, not optional: done_predicate / failure_conditions / time_bound. Each must be present. A placeholder value is fine while the status is still a draft; it is not fine in a published spec. (time_bound may be an explicit "N/A" when the task genuinely has no deadline or budget — but say so, don't omit it.)
2. Any prioritization needs a computable rubric. If the goal/criteria use ranking or weighting language (优先级 / 加权 / 权重 / 打分 / 评分 / 排序 / 分级, or "prioritize by high-impact / high-value"), there must be a corresponding rule that says how it's computed (a scoring/weighting field, numeric weights, or an explicit ordinal scale like 高/中/低). "Prioritize the important ones" with no definition of "important" is a fail — add the rubric or flag it.
3. Don't assert a gap as settled. Nothing listed in missing_inputs or confirmation_points may be written elsewhere (e.g. outputs) as if it were already decided. If the data source is "to be confirmed," the output spec can't hard-code "reads from Salesforce." (This one is a judgement call — when unsure, flag for human review rather than auto-failing.)
4. 已发布 / published requires real readiness: no unresolved placeholders in the definition body (administrative meta like owner/version doesn't count), clarity at/above the ~85% bar, and the finalize gate passed (every non-pass item human-dispositioned). If any of these fails, the status stays a draft — you don't get to publish past it.
5. Self-contained — no dangling references. The spec must carry everything its consumer needs. No pointers to the source document's sections (§4, §6), to earlier conversation ("see above / 见上文"), or to this skill's Move numbers — those resolve to nothing for a downstream reader and disguise a hole as a reference. If you're turning a rich source doc into a TaskSpec, inline its data contracts / formulas / checks / rubrics as concrete fields. (Unlike #3, this is deterministic and the host app flags it mechanically in spec-gate.ts.)

Using the deterministic engine (MCP), and why it still doesn't trust you

When a deterministic engine is available (the taskspec-engine MCP server, which wraps the same checks), route the mechanical steps through its tools instead of eyeballing them: clarity_score for the 8-dimension read, lint_spec_gate / find_dangling_refs / find_placeholders for the gate, compile_criteria_checks for Move 4, and verify_for_acceptance as a pre-flight before you call a spec ready. The tools are pure and deterministic — same spec in, same verdict out — so their answer is reproducible, not a vibe.

But understand what actually enforces the bar: not you calling the tool. The real wall is the consuming side (the app's finalize, a CI check, the asset registry, any downstream like spec-to-loop) independently re-running these same checks and rejecting whatever doesn't pass — computing the verdict from the spec's content, never reading a self-reported field like status or a provenance stamp. Because the checks are pure functions of the spec, the consumer doesn't need to trust how the spec was made; it reproduces the verdict itself. So a spec you hand-edited to say status: 已发布, or one you skipped the gate on, simply won't be accepted — the only way to get an accepted spec is to produce one that passes. That's why the tools are worth using: they tell you, before submission, exactly what the consuming gate will independently re-derive. (This re-verification only covers the deterministic/structural checks; semantic "is this spec actually right" stays a model-review + human job and can't be a hard wall.)

Anti-patterns

• Don't run the full process on an already-crisp, low-stakes task. If success is obvious and the blast radius is tiny, just do the task. This skill is for ambiguity and stakes, not ceremony.
• Don't turn clarification into an interrogation. Three rounds, high-impact only, then converge and escalate the rest.
• Don't let "success criteria" stay subjective. "Make it good" is not a criterion. If you can't write the check, the criterion isn't done.
• Don't silently fill high-impact gaps with assumptions, and don't execute past them. Low-impact gaps can take a labeled default; high-impact ones (irreversible, customer-facing, costly, boundary-crossing) require a real answer — stop and wait for it rather than "helpfully" finishing the work on a guess. The whole value is honesty about what's still undefined.
• Don't ship past the finalize gate. Anything not pass needs a human disposition first.