md-tasks · diff
git:20260421.c1dbba0 to git:20260611.feff134
33 added, 1 removed. Audit A to A.
---
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.
- Often add ordinary sub-bullets for status or context beneath a task, for example:
+ 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: 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:
```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.