SDD Tasks Plan Template

Use this template when a spec is ready but implementation should happen in small, reviewable slices. It keeps human engineers and AI coding agents tied to the same acceptance criteria.

tasks.md

# Implementation Tasks

Spec:
Design:
Owner:

## Task Rules
- Keep each task reviewable.
- Do not implement behavior outside the spec.
- Attach evidence before marking done.

## Tasks
- [ ] Task 1:
  - Acceptance link:
  - Allowed files:
  - Test command:
  - Evidence:

- [ ] Task 2:
  - Acceptance link:
  - Allowed files:
  - Test command:
  - Evidence:

## Dependency Order
1.
2.
3.

When to use this template

A feature is ready for implementation but spans multiple modules.
Several engineers or agents need clear file ownership.
A large AI-generated diff would be too hard to review.
QA wants to see how tasks map to acceptance criteria.

What a filled version looks like

The template becomes useful after it carries a real decision, owner, and evidence. This is the level of specificity to aim for.

- [ ] Add refund idempotency store
  - Acceptance link: AC-2 replay returns existing refund_id
  - Allowed files: services/refunds/*, tests/refunds/*
  - Test command: npm run test -- refunds
  - Evidence: refund_timeout_replay test passes

Field note: splitting work before assigning it to AI

A feature touches an API endpoint, a background worker, and a support UI. One broad task would let an AI agent edit everything at once, making review slow and accidental refactors easy to miss.

Common failure: If the plan only says "implement backend and frontend", the first diff may mix schema changes, UI copy, provider calls, and test cleanup in one review.

Reviewer action: Ask reviewers to approve the dependency order and allowed files for each task, especially the boundary between data state and UI state.
Evidence bar: A useful task plan names the exact test command or manual check required before each task can be marked done.

How to adapt this template without making it generic

Do not only replace the title and date. A useful version turns every placeholder into a reviewable decision: who owns the change, which behavior must be true, which scope is explicitly excluded, and what evidence must exist before merge. If a field cannot be filled yet, keep it as an open question instead of burying the uncertainty in prose.

When you use this tasks.md, start with the part most likely to cause rework. For many teams that is not the implementation step; it is the boundary, exception, compatibility rule, or release evidence. The earlier the template exposes those decisions, the less room an AI coding tool or rushed engineer has to broaden the change silently.

Use it when: A feature is ready for implementation but spans multiple modules.
Review for: Every task names an acceptance criterion or design section.
Strong wording target: Add the idempotency store first, then provider timeout state, then support UI blocking. Each task names allowed files, the acceptance criterion it satisfies, and the exact test command required before review.

Suggested review path

Use the first pass to review scope: the goal should be singular, the non-goals should block common expansions, and the affected systems should be named. Use the second pass to review testability: acceptance criteria should describe state, trigger, and observable result, not a vague wish that the product feels better. Use the third pass to review evidence: tests, screenshots, logs, metrics, or manual checks should prove each criterion.

Before giving this template to an AI coding tool, ask a human reviewer to confirm allowed files, interfaces that must not change, migration order, and stop signals. The AI should receive an executable spec, not a prompt that looks complete while still leaving the risky decisions implicit.

Before implementation: confirm open questions do not block behavior decisions.
During implementation: map every task back to a criterion or constraint in this file.
Before merge: prove the result with evidence, not only with a "tests passed" sentence.

Review before implementation

Every task names an acceptance criterion or design section.
Allowed files are narrow enough to prevent unrelated edits.
Test commands are listed before implementation starts.
Dependency order prevents risky parallel work.

Weak vs strong wording

Weak

Implement backend, update frontend, add tests.

Strong

Add the idempotency store first, then provider timeout state, then support UI blocking. Each task names allowed files, the acceptance criterion it satisfies, and the exact test command required before review.

When the template stops being empty

The easiest way for a template page to become thin is to provide a clean skeleton without showing how to judge the filled result. A useful version answers three questions: why this change is worth doing now, which scope is explicitly excluded, and which evidence proves the implementation did not drift.

When you use the template for real work, attach the final file to the pull request and mark any section that changed during implementation. A spec is not a one-time document; it should move with the implementation evidence. Readers copying this template should also copy that habit: every sentence that sounds like a decision should be reviewable and traceable.

Minimum evidence: at least one automated test or contract fixture.
Higher-risk evidence: add screenshots, log queries, metrics, or rollback signals.
Follow-up evidence: give known gaps an owner and review date.

Where it fits in a complete SDD packet

Do not push every decision into the same file. tasks.md should own the layer it is best at: making one category of decision reviewable, linkable, and updateable. Scope, design, tasks, and evidence should connect to each other, but they should not swallow each other. When implementation reveals new facts, the team should know exactly which artifact needs to change.

In practice, use this template as one step in a short chain: write the spec or proposal, add design or tasks only when the work needs them, then feed evidence back into the pull request. Readers copying the template should copy that chain as well. A polished standalone template does not improve delivery by itself; a traceable set of artifacts does.

If the template becomes a team standard, keep one filled example in the repository instead of only publishing an empty skeleton. The example teaches new contributors what "specific enough" looks like and gives AI coding tools a better pattern to follow.

Upstream input: a concrete user problem, system constraint, and known failure mode.
Downstream output: executable tasks, review questions, test evidence, or release gates.
Maintenance habit: update the matching spec file whenever implementation changes a decision.

FAQ

Why not put tasks in the issue tracker only?

You can, but keeping a tasks.md beside the spec gives reviewers one artifact chain from intent to evidence.

How small should tasks be?

Small enough that a reviewer can understand the diff, run the verification, and decide whether it satisfies one part of the spec.

Can AI agents own tasks?

Yes, when each task has allowed files, non-goals, and evidence requirements. Broad agent prompts should be split first.

Related resources

Editorial note

This template is written for spec-driven development workflows. The example is illustrative and should be adapted to your domain.

Author: Daniel Marsh
Editorial policy: How we review and update content

Tip: keep it under /docs/specs/ or /.specs/, then update it in the same pull request as implementation changes. Last updated: May 19, 2026.