Draft Management

Drafts are a lightweight pre-task form in Backlog.md for capturing immature ideas, features pending decomposition, or requirements that need further clarification.

When to Use Drafts

Scenario Description
Quick idea capture Save a title and brief description without filling in all fields
Requirements pending review Collect feedback before creating a formal task
Task-splitting preparation Record a complex feature as a draft first, then refine it into multiple formal tasks
Avoid polluting the task list Drafts do not consume formal task IDs and do not appear in the default board view

Creating Drafts

Via task create

Add the --draft option when creating a task to generate a draft directly:

backlog task create "Future feature idea" --draft

Via draft create

Use the draft-specific subcommand for simpler syntax:

backlog draft create "Future feature idea"

Draft with Description

backlog draft create "Refactor auth module" \
  -d "Consider migrating Session auth to JWT" \
  -l "refactor" \
  -a "@architect"

draft create supports the following options:

Option Description
-d, --description <text> Description
--desc <text> Alias for --description
-a, --assignee <assignee> Assignee
-s, --status <status> Status (default Draft)
-l, --labels <labels> Labels, comma-separated
--due-date <date> Due date (YYYY-MM-DD)
--planned-start / --planned-end <date> Planned start/end dates
--actual-start / --actual-end <datetime> Actual start/end times (stored in UTC)

Drafts share the same creation-time date options as tasks.

Editing Drafts

Use draft edit to modify draft fields directly; options are identical to task edit:

backlog draft edit draft-3 --title "Clearer title" -l "refactor,backend"
backlog draft edit draft-3 --append-notes "Added research conclusions"

Rules:

  • Only a single draft ID is accepted; batch editing is not supported
  • At least one field flag is required; otherwise it errors
  • --status only accepts Draft; to promote to a formal task use backlog draft promote—scripts cannot silently promote a draft in one "edit"
  • Add --plain to output the full edited record

Draft ID Disambiguation Protection

Draft identity resolution is fail-closed: when one ID matches multiple draft files (e.g., draft-3 and draft-03 coexist due to numbering drift), draft view / draft edit / draft archive / draft promote list all candidates and exit non-zero rather than picking one arbitrarily. backlog doctor reports such draft identity issues (duplicate numbering, frontmatter drift, unparseable files).

Listing Drafts

backlog draft list

Default sort is by priority. Optional parameters:

Option Description
--sort <field> Sort by priority or id
--max-count <n> / --skip <n> / --count Paging window: at most n items / skip n items / output count only (semantics in Search & Sequences, "List Paging")
--plain Plain-text output

Promoting Drafts to Tasks

When a draft is clear enough to start executing, promote it to a formal task:

backlog draft promote draft-3

After promotion:

  • The draft file moves from backlog/drafts/ to backlog/tasks/
  • The draft ID (e.g., draft-3) is replaced with a formal task ID (e.g., back-15)
  • The original draft file is archived or deleted

Demoting Tasks to Drafts

If a formal task is found to be immature and needs to be put on hold, demote it back to a draft:

backlog task demote back-10

After demotion:

  • The task file moves from backlog/tasks/ to backlog/drafts/
  • The original formal task ID is freed and can be reused by new tasks
  • A new draft ID is assigned (e.g., draft-5)

Web UI Drafts Page

Visit /drafts in the browser to view the draft list and manage filters.

Filter Bar

The top of the page provides a filter bar consistent with the task list:

Control Description
Keyword search Search by draft ID or title, substring match, with clear button
Status filter Dropdown of all available statuses
Priority filter All / High / Medium / Low
Milestone filter All milestones / No milestone / each active milestone
Label filter Multi-select chip input with autocomplete

The filter result count is shown in real time as Showing X / Y drafts. When active filters exist, a "Clear filters" button appears on the right to reset them in one click.

Filter State Persistence

All filter conditions (including search terms) are automatically synchronized to URL query parameters, so pages can be shared and bookmarked. Supported parameters:

  • ?status= — status filter
  • ?priority= — priority filter
  • ?milestone= — milestone filter (__none means no milestone)
  • ?label= — label filter (can appear multiple times)
  • ?q= — keyword search

Draft Cards and Actions

Each draft card shows the title, priority badge, ID, creation/update time, assignee, and labels. Clicking a card opens the draft detail editor; the "Promote to task" button on the right promotes the draft to a formal task.

Archiving Drafts

For drafts that are no longer needed, archive them directly:

backlog draft archive draft-2

Archived drafts are moved to backlog/archive/tasks/.

Drafts Use an Independent ID Space

Drafts and formal tasks use completely independent numbering systems:

  • Formal task IDs: back-1, back-2, back-3...
  • Draft IDs: draft-1, draft-2, draft-3...

This means:

  • The number of drafts does not affect the formal task ID sequence
  • Promoting a draft assigns the next available formal task ID
  • Demoting a task assigns the next available draft ID
  • Deleting or archiving a draft does not create gaps in formal task numbering

results matching ""

    No results matching ""