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.
summary	Draft a new task at `doc/tasks/NNNN-<slug>.md`.

<background_information> 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. </background_information>

Step 0 — scope preflight. Establish the **current repository** before naming or drafting anything. From the consumer root, run `node .agents/skills/ad-task/scripts/scope-anchors.mjs` (substitute the skill base path when loaded elsewhere). Read its JSON: `cwd` and `gitRoot` identify the target; `anchors` is the complete allow-list of repository-local sources. If `unreadable` is non-empty, stop until access is resolved.

A new task requires one exact repository-local Scope ref: a repo-relative path to the PRD roadmap line, an existing feature spec, an accepted ADR, or a root artifact that already defines the work. A board ticket, a global rule, or a request remembered from another repository does not qualify. Spec ref remains optional because a small task can be directly grounded in the PRD or an ADR.

Choose an exact entry from anchors, then run the same script with that bare path as its argument. Proceed only when verification.valid is true. If no local scope anchor exists, do not write a task. First create or amend the product, spec, or decision artifact in this current repository; then create the task against that artifact. Never use a blank, <TODO>, or another repository's path for Scope ref.

Step 1 — determine NNNN and slug. Run node .agents/skills/ad-task/scripts/next-number.mjs doc/tasks from the consumer root. Use JSON next; archived gaps stay unused. Stop until access is resolved when unreadable is non-empty, and stop for a numbering decision when exhausted is true. If loaded elsewhere, substitute the skill base path. 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.
• Scope ref: require the exact repository-local anchor validated in Step 0, with an optional section or roadmap-tier suffix. It is mandatory; a board reference never replaces it.
• Evidence ref: leave blank when creating a proposed task unless a durable evidence record already grounds its implementation decision. Before non-trivial implementation begins, ad-ground fills it with the validated doc/research/NNNN-ground-<slug>.md receipt; it supplements Scope ref, which remains the admission anchor.
• 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. It supplements the local Scope ref; it never replaces it.

Status starts at proposed. Created: today, ISO format. Notes: empty. 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.

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. A checkbox is checked only after everything it names has actually happened — never in anticipation; split a bundled step (e.g. "open PR; merge on CI green") into separate items when its parts complete at different moments. A checked box claiming an unfinished step is a false record.

<output_contract> A single new file at doc/tasks/<NNNN>-<short-slug>.md. Status proposed. Its non-empty Scope ref resolves to a repository-local source artifact. Evidence ref is blank unless an existing durable record directly grounds the task. 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): **Created:** and the dated Notes log are required by design. 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 before Acceptance Criteria.
• One scope: one task per file.
• No speculation. Acceptance criteria must be measurable; do not list aspirational items.
• Notes is append-only and dated per entry — that is the auditability primitive, not a violation of Rule 2. </output_contract>

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.