md-tasks

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:

- [ ] 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:

- [ ] 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.

- [ ] Q: Some open question?
  A: An answer on what to do. The question task is complete when each of the
  potential subtasks is completed or the answer, "A: ..." is implemented.

Finding tasks in the terminal

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

# 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:

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

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