openup-create-task-spec

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:

• File exists at docs/changes/T-XXX/plan.md matching the template at docs-eng-process/templates/task-spec.md.
• Front-matter is fully populated (id, title, status, priority, estimate).
• Status is ready (not proposed) — the rubric grades to all-✅.
• All thirteen rubric criteria in .claude/rubrics/task-spec-rubric.md are ✅.
• Every requirement carries a Given/When/Then scenario (standard/full tracks): python3 scripts/openup-spec-scenarios.py check docs/changes/T-XXX/plan.md exits 0.
• docs/roadmap.md references the new task with a status entry.

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

• openup-create-iteration-plan — produces the roadmap lines this skill expands
• openup-assess-completeness — rubric grading
• openup-orchestrate — runs the multi-role rounds