ad-task

name	ad-task
description	Draft a new task tracking file at doc/tasks/NNNN-<short-slug>.md, using a checkbox-toggle + append-only-Notes format optimized for LLM editing. Use when the user wants to create, draft, scaffold, or open a task, ticket, work item, or backlog entry tracked in the repo. Status starts at proposed; the file is the source of truth, not a board.
summary	Draft a new task at `doc/tasks/NNNN-<slug>.md`.
allowed-tools	Read, Write, Glob, Bash

/ad-task

Drafts doc/tasks/<NNNN>-<short-slug>.md for one tracked task. Format chosen so status changes via single checkbox toggles and Notes is append-only — cheap, reviewable, idempotent edits.

Step 1 — Determine NNNN and slug

List doc/tasks/. NNNN = next available 4-digit number after the highest existing (mirrors the ADR convention). If doc/tasks/ does not exist, create it; start at 0001. Slug: kebab-case, ≤6 words, derived from the user's task title.

Step 2 — Interview to fill

Ask one question per missing field, in this order:

• Context: why this task exists, what problem it solves, any assumption being tested.
• Acceptance Criteria: measurable conditions. Each is a checkbox; pass/fail must be observable, not aspirational ("loads in under 2s", not "fast enough").
• Plan: concrete sequential steps with file paths where applicable. Each is a checkbox.
• Owner: ask.
• Execution: AFK when the task is specified enough for an agent to execute with bounded context and disjoint write scope; HITL when it needs human judgment, taste, external access, or frequent back-and-forth.
• Spec ref: ask; leave blank when no spec drives this task. When a feature spec exists at doc/specs/NNNN-<slug>.md, link it here so the spec's Related → Tasks list reciprocates.
• Board ref: ask; leave blank if solo work.

Status starts at proposed. Created: today, ISO format. Notes: empty (filled during execution). Definition of Done section: copy verbatim from the template.

Do not invent values. When the user does not know something, leave <TODO> and ask. Stop after writing the file — do not start work.

Interview UX

When the host exposes AskUserQuestion, use it for multi-choice prompts (status, owner selection, Spec-ref pick from existing doc/specs/) and for confirmation gates with non-trivial branching. Inline text questions are the fallback only when the host lacks a structured-prompt primitive (Codex). Single card per multi-choice gate beats chained text questions.

Step 3 — Write the file

Path: doc/tasks/<NNNN>-<short-slug>.md. Use the template below.

Step 4 — Editing guidance for later turns

When the user later works on the task, edit the file by:

• Toggling checkboxes (- [ ] → - [x]).
• Appending to Notes (date each entry, ### YYYY-MM-DD).
• Never rewriting existing sections.

Status flips to done only when every Acceptance Criterion and every Definition of Done item is checked.

Template — doc/tasks/NNNN-<slug>.md

# Task `<NNNN>`: `<short imperative title>`

**Status:** `<proposed | in-progress | blocked | done>`
**Created:** `<YYYY-MM-DD>`
**Owner:** `<name or role>`
**Execution:** `<AFK | HITL>`
**Spec ref:** `<doc/specs/NNNN-<slug>.md or SPEC-NNNN — blank when no spec drives this task>`
**Board ref:** `<external ticket URL or ID — blank for solo work>`

## Context

`<Why this task exists. What problem it solves. Any assumption being tested.>`

## Acceptance Criteria

Verifiable conditions. Each as a checkbox so progress is point-editable.

- [ ] `<criterion 1>`
- [ ] `<criterion 2>`
- [ ] `<criterion 3>`

## Plan

Concrete sequential steps. Each as a checkbox. Reference file paths where applicable.

- [ ] `<step 1: action with file path if applicable>`
- [ ] `<step 2>`
- [ ] `<step 3>`

## Notes

Append-only log. Date each entry. Never rewrite past entries.

### `<YYYY-MM-DD>`

`<observation, decision, blocker, learning>`

## Definition of Done

All Acceptance Criteria checked, plus:

- [ ] Local tests pass (or N/A documented in Notes)
- [ ] Code review completed (human or fresh-context reviewer per WORKFLOW §10)
- [ ] No orphan `TODO`/`FIXME` introduced
- [ ] Status updated to `done` and Notes log closes the task

Output contract

A single new file at doc/tasks/<NNNN>-<short-slug>.md. Status proposed. Notes empty. No existing tasks modified. No invented values.

Task files are decision-record artifacts and are exempt from the no-dates rule (Documentation Discipline §2): the **Created:** field anchors the task in time and the append-only Notes log is dated per entry by design. The remaining Documentation Discipline rules (WORKFLOW.md §2) apply at write time:

• No emoji anywhere in the file.
• Context is the business-context-first section — why this task exists and what would break without it before Acceptance Criteria.
• One scope: one task per file. If the user's request implies multiple deliverables, ask which to write first; the others become follow-up tasks.
• No speculation. Acceptance criteria must be measurable; do not list aspirational items ("loads in under 2s", not "fast enough").
• Notes is append-only and dated per entry — that is the auditability primitive, not a violation of Rule 2.

Next

• Implement. Toggle Acceptance Criteria checkboxes and append to Notes as work lands.
• /ad-review main..HEAD (or current scope) before merge — the task DoD requires a fresh-context §10 review.
• Flip Status to done once every Acceptance Criterion and Definition-of-Done item is checked.
• If the task implements a spec, the spec's Related → Tasks list should reciprocate the link.