md-tasks git:20260810.c46c0a3A

Immutable. This exact content never changes and is served at /api/v1/blob/34ba3a37bc4afe0a.

---
name: md-tasks
description: >-
  Apply consistent Markdown checkbox task conventions in READMEs, epics/journals,
  specs, and design docs. Use when the user wants task lists with "- [ ]" /
  "- [x]", nested subtasks, context sub-bullets under items, or terminal
  commands (grep/rg) to list open versus completed tasks in Markdown files —
  especially in repo documentation and planning Markdown.
---

# Markdown tasks and checkbox conventions

Follow these conventions so agents and humans can scan open work reliably.

## Usage guidelines

### Checkbox notation

Denote open tasks or TODOs with standard checkbox notation:

- `- [ ]` for incomplete tasks.
- `- [x]` for done tasks.

Indentation defines subtasks: extra leading spaces nest bullets under a parent item.

In planning/spec documents, default every actionable item at every nesting level
to checkbox notation. Do not hide implementation work in ordinary bullets.

Often add ordinary sub-bullets for status or context beneath a task, but only
when the bullet is not itself work to do. For example:

```markdown
- [ ] Some task
  - Status: maybe some status description or how it was completed
  - More context
  - [ ] Subtask A
```

This keeps review tight: unfinished work sorts visually to checklist lines while
still allowing narrative detail.

### Actionable sub-bullets

If a sub-bullet describes work to do, a decision to resolve, behavior to
implement, a file to create, a test to add, or an acceptance criterion to verify,
write it as a checkbox task too:

```markdown
- [ ] Implement tx archive CLI.
  - [ ] Keep Bash responsible for chain config, keyring preflight, and broadcast.
  - [ ] Make TypeScript responsible for txhash parsing and Markdown formatting.
  - Rationale: TypeScript is easier to test for JSON, filenames, and CLI args.
```

Use ordinary nested bullets only for non-actionable context, rationale, status,
examples, or notes. When unsure whether a sub-bullet is actionable, prefer
`- [ ]`.

### Task Questions

Sometimes we'll pose a question or frame a resolve decision as a task. That can
look like this.

```markdown
- [ ] Q: Some open question?
  A: Record the answer once resolved, mark this decision task complete, and
  create separate open tasks for its actionable consequences.
```

### Decision and implementation tasks

Deciding what to do and implementing that decision are different task
lifecycles. During specification, track an unresolved decision as an open task.
Once resolved, preserve the decision and rationale as settled context or a
completed decision task, then derive separate open tasks for implementation,
validation, rollout, or deferred follow-up:

```markdown
- [x] Decide how referral fees are keyed.
  - Decision: Key fees by market and referral code.
  - Rationale: Code ownership can change without moving accrued state.
- [ ] Change the fee map to use the new key.
- [ ] Migrate existing balances.
- [ ] Test ownership transfer with accrued fees.
```

A completed decision checkbox does not mean its implementation is complete.
When editing an epic or durable spec, follow agent skill `epics` for section
placement and handoff organization. Use agent skill `drill-spec` when material
design questions still need resolution.

### Finding tasks in the terminal

Patterns differ by shell (`**/*.md` is not universal glob). Typical approaches:

```bash
# Completed tasks under a directory (GNU grep fallback)
grep -rF -- '- [x]' <path-or-glob>

# Open tasks — limit to Markdown (example: cwd tree)
grep -rF -- '- [ ]' . --include='*.md'
```

Or use **`rg`** for `**` globs and filters:

```bash
rg --fixed-strings -g '*.md' -- '- [ ]'
rg --fixed-strings -g '*.md' -- '- [x]'
```

Tune paths and `-g`/globbing to match the repo layout.