---
name: markdownto-backlog
description: Create or edit prioritized Markdown To backlogs with clear next actions and blockers.
---
# Markdown To backlog
## Contract and workflow
Read `mdto spec backlog` (or the adjacent `SPEC.md` in a checkout) and the
[shared conventions](https://markdownto.ai/specs/conventions.md) before authoring or
repairing content. Outside a checkout, use the [published spec](https://markdownto.ai/specs/backlog.md).
This skill accompanies `[email protected]`. The spec and its fixtures govern conformance;
editorial advice below is non-normative and should adapt to the user's brief.
If the source declares another version, obtain its matching contract before changing it.
Use `markdownto: [email protected]`. Level-2 headings are the reserved priority bands Now,
Next, Later, Someday, and Done; unused bands may be omitted. The states include `[ ]`,
`[/]`, `[x]`/`[X]`, and `[-]`. Position expresses priority, not execution sequence.
Use the declared blocker syntax and spec-owned verbs; promotion does not start a task.
Read the workspace spec when work needs linked detail notes or cross-file blockers.
## Content quality
Keep the next decision visible: a task should say what outcome is wanted and enough to
start it. Use a blocker only for an actual dependency or unanswered owner decision, not
as a substitute for low priority. Avoid claiming everything is urgent. Separate current
facts from possible approaches in detail notes, and preserve the user's priority order
unless reprioritization is part of the request.
## Check and deliver
Validate the file with `mdto validate <path>` before editing existing content and again
after changes. Read diagnostics against the spec's rationale; preserve meaning when
repairing syntax. Prefer spec-owned verbs for edits they support, checking their current
`--help`; otherwise make a focused source edit, preserving unrelated content and IDs.
Render with `mdto render <path>` and inspect the result when available. Validation checks
structure, not editorial quality: review the content against the user's purpose as well.
Without the CLI, use the contract and examples and report that validation was not run.
Deliver the Markdown source and any requested artifacts, stating what was actually checked.
Give this guide to your agent, or read it as an author. It covers workflow and editorial judgment; the specification defines conformance.
Contract and workflow
Read mdto spec backlog (or the adjacent SPEC.md in a checkout) and the shared conventions before authoring or repairing content. Outside a checkout, use the published spec. This skill accompanies [email protected]. The spec and its fixtures govern conformance; editorial advice below is non-normative and should adapt to the user's brief. If the source declares another version, obtain its matching contract before changing it.
Use markdownto: [email protected]. Level-2 headings are the reserved priority bands Now, Next, Later, Someday, and Done; unused bands may be omitted. The states include [ ], [/], [x]/[X], and [-]. Position expresses priority, not execution sequence. Use the declared blocker syntax and spec-owned verbs; promotion does not start a task. Read the workspace spec when work needs linked detail notes or cross-file blockers.
Content quality
Keep the next decision visible: a task should say what outcome is wanted and enough to start it. Use a blocker only for an actual dependency or unanswered owner decision, not as a substitute for low priority. Avoid claiming everything is urgent. Separate current facts from possible approaches in detail notes, and preserve the user's priority order unless reprioritization is part of the request.
Check and deliver
Validate the file with mdto validate <path> before editing existing content and again after changes. Read diagnostics against the spec's rationale; preserve meaning when repairing syntax. Prefer spec-owned verbs for edits they support, checking their current --help; otherwise make a focused source edit, preserving unrelated content and IDs. Render with mdto render <path> and inspect the result when available. Validation checks structure, not editorial quality: review the content against the user's purpose as well. Without the CLI, use the contract and examples and report that validation was not run. Deliver the Markdown source and any requested artifacts, stating what was actually checked.