| name | openup-create-task-spec |
| description | Produce a REASONS-Canvas task spec from a roadmap line or feature description, ready for developer-role consumption |
| model | sonnet |
| fit | {"great":["decomposing iteration-plan tasks into executable specs","formalizing ad-hoc work before coding starts"],"ok":["retrofitting specs onto in-progress work that lacks one"],"poor":["trivial doc-only edits (overhead exceeds value)","exploratory spikes"]} |
| arguments | [{"name":"task_id","description":"Task ID (T-XXX). Reserves the next free ID via `openup-claims.py reserve-id` if not provided.","required":false},{"name":"title","description":"One-line task title. Required if task_id is new; reads from roadmap if existing.","required":false},{"name":"source","description":"Where the task comes from: 'roadmap' (default), 'plan' (with plan path), or 'adhoc'.","required":false},{"name":"plan_ref","description":"Path + section to the originating plan, e.g. 'docs/plans/2026-04-28-foo.md#3'","required":false}] |
Create Task Spec (REASONS Canvas)
This skill produces a per-task REASONS Canvas — the executable blueprint a
developer-role agent reads verbatim before generating code. It bridges the gap
between coarse roadmap lines / use cases and implementation.
When to Use
Use this skill when:
- A roadmap task is about to enter implementation and has no spec yet.
- A plan item needs to be decomposed before assignment.
- Existing in-progress work needs a retroactive spec for handoff.
When NOT to Use
Do NOT use this skill when:
- The change is a trivial typo / config tweak — use
/openup-quick-task.
- The task spec already exists at
docs/changes/T-XXX/plan.md — update via this
skill (re-run), do not hand-edit (per the spec-first rule in CLAUDE.openup.md).
- You're at the idea stage and don't yet have requirements — run
/openup-plan-feature first.
Success Criteria
After this skill completes, ALL of these must be true:
Process
Load Project Config (context + rules — do this first)
If docs/project-config.yaml exists, apply it before drafting (skip if
absent): inject its context: as <project-context> and its rules.task-spec
as <project-rules>, then confirm every injected rule holds before marking
the artifact complete. Rules are additive — they may add but never waive a
framework criterion. Full mechanism + precedence (the single source):
docs-eng-process/project-config.md.
The skill is a two-round multi-role handoff. Use the token-efficiency protocol
(.claude/CLAUDE.openup.md): one orchestrator, compact handoffs, one specialist
per round.
1. Reserve Task ID and Read Context
-
If task_id is missing, reserve the next free ID through the claims
mechanism — never scan-and-increment yourself (a local scan races with
parallel planning lanes and stale checkouts; that race is what forced the
T-024→T-025…T-030 renumber — T-031):
python3 scripts/openup-claims.py reserve-id --session-id <session> --title "<title>"
The printed T-NNN is yours repo-wide: the reservation lives in the shared
claims dir (visible to every worktree) and the allocator unions live
reservations with the IDs already used in change folders, docs/roadmap.md,
and origin/main's roadmap.
-
If task_id IS provided (e.g. pre-allocated by /openup-plan-feature), pin
it with the same command plus --task-id T-NNN — it exits 6 if the ID is
already used or reserved by another session; stop and re-reserve without
--task-id in that case.
-
If planning is abandoned before the spec lands, free the ID:
python3 scripts/openup-claims.py release-id --task-id T-NNN. Once the spec
or roadmap row is committed the reservation is redundant (the allocator also
scans the repo) — releasing it then is optional tidiness, never required.
-
Read docs/roadmap.md, the originating plan (if plan_ref provided), and the
use case(s) implicated.
-
Generate path: docs/changes/<task_id>/plan.md; create the docs/changes/<task_id>/
folder if it does not exist.
-
Copy docs-eng-process/templates/task-spec.md to that path.
2. Ambiguity Gate (before drafting)
Before any role drafts, list the open questions the request leaves unanswered
and classify each:
- Blocking — the answer would change scope, requirements, or acceptance
criteria (you would build a different thing depending on it). Stop. Raise
it via
/openup-request-input (related_task = this task ID) and do not draft
the affected sections until it is answered. Guessing here is the exact waste
this gate exists to prevent.
- Non-blocking — a default is reasonable and the cost of being wrong is low.
Pick the default and record it as a
**Assumption:** line in the spec's
Analysis Context (state the choice; note it is vetoable at review). Do not
silently bake it into Requirements without naming it.
If there are no open questions, say so in one line and proceed. The point is an
explicit pass, not invented doubt.
A blocking question silently guessed is rework discovered after code. A
non-blocking question silently guessed is a decision no one got to veto. The
gate converts both into something the requester can see and correct.
3. Round 1 — Analyst + Architect
Brief one analyst-role agent and one architect-role agent in compact form (max
6 bullets each). Inputs: roadmap line, plan section, use case excerpt.
- Analyst drafts: Story (INVEST), Analysis Context, Requirements (each with
≥1
Given / When / Then scenario), Behavior Delta, Success Measures,
Entities.
- Architect drafts: Approach (3–5 lines), Structure (Add/Modify/Do-not-touch),
Rollout, Safeguards (invariants, no-go zones, token budgets).
Both write directly to the task-spec file under their respective sections. They
do NOT inline rules from conventions.md or the architecture notebook —
references only.
For Behavior Delta, the analyst groups every change to existing Ring-1 product
behavior under Added / Modified / Removed, citing the Ring-1 artifact + section on each
Modified/Removed entry (docs/product/use-cases/UC-3.md §main-flow); a greenfield task
renders n/a — all Added. This list is what /openup-sync-spec consumes to know exactly
which Ring-1 artifacts a behavior change must back-propagate to — so a missing or vague
citation is a real gap, not a formality.
For Success Measures, the analyst writes a ## Success Measures section
containing one falsifiable expectation for the feature:
We expect <measure X> to move by <direction + magnitude Y> within
<window Z> of release. Instrumentation: <the event / metric / query
that will be read>. Read-back: <date or "Z after release">.
Use impact, engagement, and returned value as prompts to find the right
measure — they are not three required slots; one honest, checkable expectation
beats three vanity metrics. A measure nobody will read back is worse than none:
on the quick track (or for genuinely unmeasurable internal work) write
n/a — <reason> instead, and the reason must survive review. Add the section when drafting;
rubric criterion 12 enforces it. (Both this section and Rollout are authored
additions — the OpenUP-derived template at docs-eng-process/templates/task-spec.md
is read-only and does not carry them.)
For Rollout, the architect writes a ## Rollout section stating how the
change reaches users (KB framing: a feature flag is the modern, cheaper
implementation of OpenUP's Develop Backout Plan deployment task — toggling
off beats redeploying):
- Flagged? yes/no with a reason either way ("config-read at startup,
flag adds no safety" is a fine reason for no).
- If flagged: flag name, default state per environment (use the names
from
docs/project-config.yaml environments: if defined, else
local/production), kill-switch behavior (what turning it off does to
in-flight users/data), and — mandatory — the named flag-removal
follow-up (one line; /openup-complete-task enqueues it into the roadmap,
because a flag is temporary debt, not a permanent switch).
- Not user-facing at all (pure refactor, internal tooling):
n/a — <reason>.
Add the section when drafting; rubric criterion 13 enforces it (authored
addition — see the note under Success Measures).
For Requirements, the analyst writes each numbered assertion with at least one
acceptance scenario in Given / When / Then form (bold markers **Given** / **When**
/ **Then**, inline or split across lines). The scenario must name a concrete
precondition, action, and observable outcome — drafting it is the test that the
requirement is unambiguous; if a clean scenario can't be written, the requirement is
still too vague. (Exempt on the quick track only.) /openup-assess-completeness
runs scripts/openup-spec-scenarios.py to enforce this deterministically.
4. Round 2 — Developer
Brief one developer-role agent with the partially-filled task spec.
- Developer drafts: Operations as a checkbox list (
- [ ] <step>,
ordered, 3–8 testable steps). Tag a step - [ ] (role) … only where it hands
off to a different role hat (tester, analyst, …); untagged steps default to
the developer hat. The first unchecked box is what /openup-next reads as
the lane's next_action — so each step must be a concrete, executable action,
not a heading. (Legacy numbered steps still parse but yield no next_action.)
- Developer also fills the Norms section with file references only (no copies).
5. Self-Critique
Apply the Self-Critique SOP (docs-eng-process/sops/self-critique.md) before
rubric grading: take a hostile-reviewer stance, surface every load-bearing
assumption into the spec, and confirm the Behaviour Delta names what observably
changes and that every acceptance criterion and scenario is failable — not
"review and approve". This precedes (does not replace) the rubric: list every weakness you find,
fix or explicitly flag each one so step 6 grades a stronger spec, then rank
them and record the top one or two with their resolutions.
6. Rubric Grading
Run /openup-assess-completeness artifact: task-spec (or apply
.claude/rubrics/task-spec-rubric.md inline). Grade each of 13 criteria. That
skill also runs scripts/openup-spec-scenarios.py check docs/changes/T-XXX/plan.md
— criterion 11 (Scenario Coverage) cannot be ✅ unless the script exits 0 (it is
auto-skipped on the quick track).
- All ✅ → set
status: ready in front-matter.
- Any ❌ → keep
status: proposed, list gaps for revision, loop back to the
responsible role for fixes.
7. Roadmap Update
Add or update the roadmap row for this task ID with status ready and a link
to the spec file.
Output
Returns:
- Path to the created task spec
- Rubric grade summary (criteria satisfied / gaps)
- Final status (
ready or proposed)
Common Errors
| Error | Cause | Solution |
|---|
| Template not found | Path moved | Verify docs-eng-process/templates/task-spec.md exists |
| Norms section duplicates conventions.md content | Specialist inlined rules | Replace inline text with a path reference |
| Operations step is multi-action | Step bundles "implement X and Y" | Split into separate steps |
| Estimate doesn't match Structure scope | Misjudged size | Either tighten Structure or revise estimate |
References
- Template:
docs-eng-process/templates/task-spec.md
- Rubric:
.claude/rubrics/task-spec-rubric.md
- Format origin: Martin Fowler, "Structured Prompt-Driven Development"
- Index:
docs/changes/README.md
See Also
