/sdlc:task-new

Generated from solutions/ontological/skills/task-new/SKILL.md.

Description

Interactively define a new task. Walk the user through headline, slug, status, impact, and complexity; create the file via sdlc task create; validate the frontmatter; report the path. Optionally also capture prose for the body sections and Edit them into the file before reporting.

Allowed tools

• Bash
• Read
• Edit
• AskUserQuestion

Source

Usage:

• /sdlc:task-new — start the interview. End state: a validated task file at docs/planning/tasks/<YYYY-MM-DD>-<slug>.md under the project root.

Project context (don’t re-derive every run):

• Tasks live at docs/planning/tasks/YYYY-MM-DD-<slug>.md. Schema at ${CLAUDE_PLUGIN_ROOT}entities/task/schema.ts.
• Delegate file creation to ${CLAUDE_PLUGIN_ROOT}cli/sdlc task create. That op owns date prefixing, slug validation, frontmatter shape, and headline substitution; call it and trust its output rather than reproducing any of those steps here.
• Validation: ${CLAUDE_PLUGIN_ROOT}cli/sdlc entities validate.
• This skill captures the intake. Body sections (Goal, Today, Proposed, Approach, Files to touch, Acceptance criteria, Out of scope, Dependencies) are filled in by Edit only if the user opts in at step 6; the default is to leave the template’s <...> placeholder blocks unfilled for the author to flesh out later. Treat a <...> block as an empty section, not as in-line author guidance to preserve: ${CLAUDE_PLUGIN_ROOT}entities/task/implementation-ready.md disqualifies any required body section that still carries <...> text.

1. Headline

Ask the user in plain text: “What’s the one-line headline for this task?” Skip this step if the user already gave a headline in their invocation message.

2. Preview the suggested slug

Get the suggested slug from the canonical op rather than hand-deriving it:

${CLAUDE_PLUGIN_ROOT}cli/sdlc task preview-id "<headline>" --output json

This read-only op derives the slug exactly the way task create will (the shared capped deriveSlug, 60-char), and reports the would-be T-NNNN id plus any same-slug (exists / exact_match) or near-slug (similar[]) collisions. Capture the JSON: hold slug as the suggested slug for the next step, and hold warning / similar to surface to the user there. (The bare-text projection prints the PREVIEW-ID task slug=… id=… exists=… similar=… marker followed by a warning: line; pass --output json for the structured fields.)

3. Triage + slug confirmation (one AskUserQuestion call, 4 questions)

Send a single AskUserQuestion with these four questions:

1. Slug — header “Slug”. Seed the default from Step 2’s preview: options are Use \`and Other (Other lets the user type an override). The auto-Other option is added by the tool — don't list it explicitly. If Step 2 reported awarning(an exactexistscollision or anysimilar[]slugs), include it in this question's prose so the user names the slug with that context in hand — e.g. "heads up: an existing task already uses this slug" or "similar existing slugs:<…>`”. This skill deliberately lets the user name the slug, so surface the collision rather than auto-resolving it.
2. Status — options: planning/draft, planning/proposed, planning/backlog, open/ready. Recommend planning/draft for fresh capture; open/ready only if the spec is complete enough for /sdlc:task-work to start.
3. Impact — options: high, medium, low.
4. Complexity — options: small (<1 day), medium (1–3 days), large (multi-day).

Don’t validate the slug shape inline. The slug the user picks is gated downstream by the task create op (Step 5), which checks it against the canonical SLUG_RE from ${CLAUDE_PLUGIN_ROOT}lib/util/slug.ts and exits non-zero with a slug must be kebab-case message when it fails. Trust that exit code as the source of truth; Step 5 owns the re-ask loop.

4. Tags, related, and autonomy (only if mentioned)

Don’t proactively prompt for any of these — most new tasks don’t need them, and the extra questions are friction. If the user mentioned anything in earlier messages that maps to one of these, capture it:

• Tags → --tags <tag> (repeatable). Triggers: “tag it auth/security”, “this is a docs task”.
• Related → --related <slug> (repeatable). Triggers: “related to the routing rework”, “extends 2026-05-12-foo”.
• Autonomy → --autonomy human-only, --autonomy supervised, or --autonomy autonomous/pr. Triggers (human-only): “an agent shouldn’t pick this up”, “needs human eyes”, “judgment call”, “customer-facing copy”. Triggers (supervised): “LLM can attempt but a human must review”, “needs sign-off”. Triggers (autonomous/pr): “let the agent self-ready and carry it to a PR”, “best-effort autonomous up to a PR”, “don’t park this at a spec gap” — the agent may non-interactively fill spec gaps (via /sdlc:task-auto-define) and implement to PR open, but never merges. Otherwise omit — absent means LLM-pickable by default, which is the most common case.

5. Create the file

Run:

${CLAUDE_PLUGIN_ROOT}cli/sdlc task create <slug> \
  --headline "<headline>" \
  --status <status> \
  --impact <impact> \
  --complexity <complexity> \
  [--autonomy human-only|supervised|autonomous/pr] \
  [--tags <tag>]... \
  [--related <related>]...

Pass the user-chosen <slug> from Step 3 as the positional. (When <slug> is omitted, create derives one from the headline via the same capped deriveSlug Step 2 previews — but this skill deliberately lets the user name the slug, so pass it explicitly here.)

The op prints the absolute path of the new file on stdout. Capture it. (Pass --output json instead for {path,id}.)

If it exits non-zero with “already exists”, ask the user via AskUserQuestion whether to pick a new slug or pass --force to overwrite. If it exits non-zero with slug must be kebab-case (the SLUG_RE gate the create op enforces), ask the user for a corrected slug with a one-line explanation of the rule, then re-run create.

6. Optional: flesh out the body inline

Ask once via AskUserQuestion: “Fill in Goal / Today / Proposed / Approach / ACs now, or leave the placeholders for later?”

If the user chooses “now”: for each section the user wants to fill in, ask in plain text for the content, then use Edit to replace the entire <...> placeholder block with the user’s text — every character from the opening < to the closing >, including any internal line breaks. If the template also includes skeleton bullets below the <...> block (e.g. - <item> under “Out of scope”, or 1. <step> under “Approach”), replace those too — any residual placeholder text disqualifies the section per ${CLAUDE_PLUGIN_ROOT}entities/task/implementation-ready.md. Headers (## Goal, etc.) stay; everything between adjacent headers is fair game. If the user explicitly skips a section, leave its placeholders intact verbatim — partial replacement (e.g. replacing the skeleton bullets but leaving the leading <...> paragraph) is the wrong shape.

If “later”: don’t touch the body.

7. Validate

${CLAUDE_PLUGIN_ROOT}cli/sdlc entities validate <path-from-step-5>

If validation fails, report the error verbatim. Most common cause is a custom slug or date that violates a pattern — fix and re-run.

8. Report

Detect remaining placeholders deterministically rather than eyeballing the body — shell out to the task noun’s scanner op:

${CLAUDE_PLUGIN_ROOT}cli/sdlc task scan-placeholders <path-from-step-5>

The scanner emits a single JSON array of matches ({"section": ..., "phrase": ..., "line": ..., "snippet": ...}) on stdout; exit 0 with [] means no placeholders remain. It already skips fenced code blocks and inline-code spans, inspects only the required body sections, and flags <...> angle-bracket placeholders, TBD, the (pick one) family, and empty-cell table rows (empty-table-cell). A non-empty array means the task is NOT implementation-ready. Its output needs no further filtering.

Tell the user:

• The absolute path of the new file.
• One line: <status> · <impact> · <complexity> — <headline>.
• Next step (first matching branch wins):
  • If the scanner reported any match (placeholders remain in a required body section): the task is NOT implementation-ready (per ${CLAUDE_PLUGIN_ROOT}entities/task/implementation-ready.md). Say so, and suggest /sdlc:task-define <slug> to fill the gaps. Do NOT suggest /sdlc:task-work even if the user picked status: open/ready — task-work’s Step 5 will invoke /sdlc:task-ensure-ready, which will immediately downshift the task to planning/needs-definition and clear any readiness_verified_at: stamp.
  • Else if status is open/ready: suggest /sdlc:task-work <slug>.
  • Else (no placeholders but status not yet open/ready): suggest opening the file to bump status when the spec is solid.

Acceptance criteria

• File exists at docs/planning/tasks/<YYYY-MM-DD>-<slug>.md under the project root.
• Frontmatter passes sdlc entities validate with zero errors.
• The headline is set in the body (no <One-line headline …> placeholder remains in the # ... line).
• The op’s output path was reported back to the user.

Notes

• sdlc task create owns the frontmatter fields; do not hand-edit them with Edit. To change a frontmatter value after creation, run ${CLAUDE_PLUGIN_ROOT}cli/sdlc task update <path-or-basename> --set '<json>' — it applies the JSON field updates (a null value deletes a key), schema-validates before writing, and leaves the body byte-untouched.
• Keep the conversation short. If the user packed everything into the first invocation message (“new task: add time-zone helpers, open/ready, high impact, small”), skip the AskUserQuestion calls and go straight to step 5.
• Branch naming. If this task’s spec lands in a PR before its implementation, use docs/<basename> for the spec PR (NOT task/<basename> — that’s reserved for the eventual implementation run by /sdlc:task-work). See ${CLAUDE_PLUGIN_ROOT}conventions/branch-naming.md.
• Schema bump checklist. See ${CLAUDE_PLUGIN_ROOT}conventions/schema-bump-checklist.md. When the user’s headline matches /schema bump|schema-bump|migrate v\d+ to v\d+/i, surface the five canonical questions (missing field, current field, unknown legacy value, error path, post-migrate stamp behavior) during Step 6 so the spec author answers them upfront. Do not write schema_version with Edit — the bump itself happens later, in /sdlc:entities-migrate.