md-tasks · diff
git:20260611.feff134 to git:20260810.c46c0a3
24 added, 2 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.
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.
+ 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.