Design Doc And Task Board
Overview
Decide where intent, design, work state, and acceptance criteria should live so they do not drift.
Design docs explain why and how; a work-state surface tracks current tasks, statuses, acceptance criteria, and task-to-change traceability; exec plans describe how to execute a complex batch of changes. tasks.md or docs/tasks.md is the lightweight repo-local default when no reliable Jira, Linear, GitHub Issues, internal board, or equivalent tracker exists. For shared harness terms, see ../../references/harness-patterns.md; when planning files are absent, use references/build-when-missing.md.
When To Use
- The user asks whether a requirement belongs in a design doc,
tasks.md, an external task system, or an exec plan.
- README, design docs, tasks, and exec plans start to duplicate or drift.
- Requirements need to become tasks, statuses, acceptance criteria, and commit-linked change records.
Inputs Needed
- Current requirement or change goal.
- Existing task tracker or
tasks.md, design docs, exec plans, README, and docs index.
- Change size, cross-module scope, and whether long-term tracking is needed.
Execution Order
- First: Read existing planning and work-state sources of truth and identify how this project expresses intent and status.
- Then: Decide whether this requirement belongs in a design doc, existing task system, repo-local task board, exec plan, or combination.
- Finally: Output the doc/task sync strategy, acceptance criteria, and update order.
Step-by-Step Process
- Search for
tasks.md, PLANS.md, docs/design*, docs/exec-plans, README, issue references, and documented external task systems.
- Identify each file's actual responsibility; do not infer solely from names.
- If no reliable work-state surface exists, bootstrap the minimum design/task/exec-plan set from
references/build-when-missing.md, using tasks.md or docs/tasks.md as the repo-local default.
- Classify by complexity: small fixes update tasks only; architecture or cross-module changes start with a design doc; multi-day batches use an exec plan.
- Write task entries with owner, status, acceptance criteria, linked paths, and the expected commit or change reference; do not put chat notes into
tasks.md.
- When design changes, update the design source of truth first, then sync task state and acceptance criteria.
- When a tracked task is completed, changed, or invalidated by a commit, include that task-state update in the same logical commit as the related change.
- Output drift checks: one conclusion has one source of truth, and other files reference it.
Checks
- Responsibility: design doc, work-state surface, and exec plan each have a clear role.
- Sync: task status matches current code and design decisions.
- Acceptance: every task has executable acceptance criteria.
- Granularity: tasks are small enough to verify and large enough to express user value.
- Commit coupling: task-state updates travel with the logical commit that fulfills, changes, or invalidates them.
- Pollution:
tasks.md does not become a chat log or unordered TODO list.
Output Format
# Design Doc And Task Board Decision
## Detected Mapping
- design source:
- work-state:
- exec plan:
## Where This Belongs
- Design doc:
- Work-state surface:
- Exec plan:
## Update Order
- First:
- Then:
- Finally:
## Task Entries
-
## Commit Coupling
-
## Acceptance Criteria
-
## Drift Checks
-
Common Mistakes
- Putting task status into a design doc where it cannot be maintained.
- Updating only the task surface while leaving the design source of truth stale.
- Completing a task in code while leaving its task-state update for a later unrelated commit.
- Opening a large exec plan for every small requirement.
- Writing tasks with no acceptance criteria, such as "improve" or "optimize."
Example Prompts
- "Should this requirement live in a design doc, an issue tracker, or tasks.md?"
- "Turn this design into a task board and acceptance criteria."
- "Our task board and design docs have drifted; how should we converge them?"
1---2name: design-doc-and-task-board3description: Use when deciding how requirements should be captured in design docs, tasks.md, external task systems, exec plans, acceptance criteria, status updates, or planning source-of-truth files.4metadata:5 source: https://skillmd.com/skills/concertonotes/design-doc-and-task-board6---78# Design Doc And Task Board910## Overview1112Decide where intent, design, work state, and acceptance criteria should live so they do not drift.1314Design docs explain why and how; a work-state surface tracks current tasks, statuses, acceptance criteria, and task-to-change traceability; exec plans describe how to execute a complex batch of changes. `tasks.md` or `docs/tasks.md` is the lightweight repo-local default when no reliable Jira, Linear, GitHub Issues, internal board, or equivalent tracker exists. For shared harness terms, see `../../references/harness-patterns.md`; when planning files are absent, use `references/build-when-missing.md`.1516## When To Use1718- The user asks whether a requirement belongs in a design doc, `tasks.md`, an external task system, or an exec plan.19- README, design docs, tasks, and exec plans start to duplicate or drift.20- Requirements need to become tasks, statuses, acceptance criteria, and commit-linked change records.2122## Inputs Needed2324- Current requirement or change goal.25- Existing task tracker or `tasks.md`, design docs, exec plans, README, and docs index.26- Change size, cross-module scope, and whether long-term tracking is needed.2728## Execution Order2930- First: Read existing planning and work-state sources of truth and identify how this project expresses intent and status.31- Then: Decide whether this requirement belongs in a design doc, existing task system, repo-local task board, exec plan, or combination.32- Finally: Output the doc/task sync strategy, acceptance criteria, and update order.3334## Step-by-Step Process35361. Search for `tasks.md`, `PLANS.md`, `docs/design*`, `docs/exec-plans`, README, issue references, and documented external task systems.372. Identify each file's actual responsibility; do not infer solely from names.383. If no reliable work-state surface exists, bootstrap the minimum design/task/exec-plan set from `references/build-when-missing.md`, using `tasks.md` or `docs/tasks.md` as the repo-local default.394. Classify by complexity: small fixes update tasks only; architecture or cross-module changes start with a design doc; multi-day batches use an exec plan.405. Write task entries with owner, status, acceptance criteria, linked paths, and the expected commit or change reference; do not put chat notes into `tasks.md`.416. When design changes, update the design source of truth first, then sync task state and acceptance criteria.427. When a tracked task is completed, changed, or invalidated by a commit, include that task-state update in the same logical commit as the related change.438. Output drift checks: one conclusion has one source of truth, and other files reference it.4445## Checks4647- Responsibility: design doc, work-state surface, and exec plan each have a clear role.48- Sync: task status matches current code and design decisions.49- Acceptance: every task has executable acceptance criteria.50- Granularity: tasks are small enough to verify and large enough to express user value.51- Commit coupling: task-state updates travel with the logical commit that fulfills, changes, or invalidates them.52- Pollution: `tasks.md` does not become a chat log or unordered TODO list.5354## Output Format5556```markdown57# Design Doc And Task Board Decision5859## Detected Mapping60- design source:61- work-state:62- exec plan:6364## Where This Belongs65- Design doc:66- Work-state surface:67- Exec plan:6869## Update Order70- First:71- Then:72- Finally:7374## Task Entries75-7677## Commit Coupling78-7980## Acceptance Criteria81-8283## Drift Checks84-85```8687## Common Mistakes8889- Putting task status into a design doc where it cannot be maintained.90- Updating only the task surface while leaving the design source of truth stale.91- Completing a task in code while leaving its task-state update for a later unrelated commit.92- Opening a large exec plan for every small requirement.93- Writing tasks with no acceptance criteria, such as "improve" or "optimize."9495## Example Prompts9697- "Should this requirement live in a design doc, an issue tracker, or tasks.md?"98- "Turn this design into a task board and acceptance criteria."99- "Our task board and design docs have drifted; how should we converge them?"