backlog-workflow

name	backlog-workflow
description	Project-agnostic workflow guidance for Backlog.md MCP task management. Covers search-first protocol, scope assessment, task creation standards, lifecycle management, and cross-session coordination.

Backlog.md MCP Workflow Skill

Core Principle: Track Commitments, Not Activity

Backlog tracks what will be built. Use it when work requires planning, decisions, or coordination across sessions. Skip it for trivial mechanical changes that can be completed immediately.

Use Backlog when:

• Work requires planning or architectural decisions
• Multiple deliverables need coordination
• Other sessions might duplicate effort
• Progress tracking benefits stakeholders
• Work spans multiple sessions

Skip Backlog when:

• Single trivial change (typo fix, simple config update)
• Immediate execution with no planning needed
• Work completes in < 5 minutes
• No coordination required

Search-First Protocol (CRITICAL)

ALWAYS search before creating tasks. Duplicate tasks waste effort and create confusion.

Three-step search:

1. Keyword search:

   task_search(query="relevant keywords", limit=20)
   

2. Status filter:

   task_list(status="To Do", limit=50)
   task_list(status="In Progress", limit=50)
   

3. Label filter (if applicable):

   task_list(labels=["essay", "infrastructure"], limit=30)
   

When you find similar work:

• Same goal, different approach → Comment on existing task, don't create duplicate
• Related but distinct → Create new task with dependency on existing
• Truly unique → Create new task, reference related tasks in description

No search results → Proceed with task creation

Scope Assessment: Single Task vs Epic

Decision framework:

Indicator	Single Task	Epic + Subtasks
Deliverables	One clear output	Multiple distinct outputs
Parallelization	No independent components	Components can run in parallel
Duration	< 4 hours total	> 4 hours or multi-session
Dependencies	Linear execution	Some subtasks have dependencies
Coordination	One person/session	Multiple sessions or models

Single Task Pattern:

• Clear deliverable (e.g., "Fix typography bug in essay paragraphs")
• Straightforward execution
• Completed in one session

Epic Pattern:

• Multiple deliverables (e.g., "Essay 12: Complete 6-step workflow")
• Subtasks can run in parallel (e.g., multiple essays' research phase)
• Requires coordination across sessions or models

When in doubt: Start with single task. Split into epic if scope grows during planning.

Task Creation Standards

Title format: [Action] [Target] [Context if needed]

Good: "Create essay-technical-depth Skill (Step 1.5)" Bad: "Work on skills" (vague action and target)

Description template:

## Goal
[What will be accomplished - one sentence]

## Context
[Why this matters - link to project goals]

## Deliverables
- [Specific output 1 with file path]
- [Specific output 2 with criteria]

## Approach
[High-level implementation strategy - optional but recommended]

Acceptance criteria (measurable):

Good:

• File /path/to/output.md exists with required sections
• All 5 quality standards verified against checklist
• Tests pass and changes committed with task ID reference

Bad:

• Code works (not measurable)
• Quality is good (subjective)

Dependencies:

• List task IDs that must complete before this task starts
• Use Backlog task IDs (e.g., task-35.1, task-37.2)
• Document WHY dependency exists (helps future sessions understand blocking)

Assignee (model assignment):

• Haiku - Simple search/compile work (with Skills for quality)
• Sonnet - Structure/analysis requiring synthesis
• Opus - Complex reasoning, scholarly depth, maximum insight
• Assignee = recommendation, not requirement (delegate to appropriate model)

Task Lifecycle Management

Status transitions:

To Do → In Progress → Done

Critical rules:

1. Mark In Progress BEFORE starting work

   task_edit(id="task-X", status="In Progress")
   

2. Only ONE task In Progress per session (focus)

3. Mark Done IMMEDIATELY after completing

   task_edit(id="task-X", status="Done")
   

4. Use task_complete for archival (moves to completed folder)

   task_complete(id="task-X")
   

Task notes for session handoff:

task_edit(
  id="task-X",
  notesAppend=[
    "Commit abc123: Implemented feature X",
    "Blocked on task-Y completion for integration testing",
    "Next: Run full test suite after task-Y merges"
  ]
)

Implementation plan documentation:

task_edit(
  id="task-X",
  planSet="1. Research existing patterns\n2. Draft implementation\n3. Test with Essay 6\n4. Commit with task ID"
)

Coordinating Across Sessions

Mental model: Other Claude sessions = team members working in parallel.

Before starting work:

1. Check assignees:

   task_view(id="task-X")
   

   • Already assigned to another model/session? Don't duplicate effort
   • Unassigned? Assign to yourself before starting

2. Check status:

   • In Progress by another session? Coordinate in task notes
   • To Do and no assignee? Safe to claim

3. Check dependencies:

   task_view(id="task-X")
   

   • Review dependencies field
   • Verify blocking tasks are Done before starting

Communication via task notes:

task_edit(
  id="task-X",
  notesAppend=[
    "[Session A] Started implementation, 60% complete",
    "[Session B] Waiting for Session A to finish before integration testing"
  ]
)

Parallel work pattern:

Epic: Essay 12 Complete
├── task-12.1 Research (Haiku) - No deps → START NOW
├── task-12.1.5 Technical Analysis (Sonnet) - Deps: 12.1 → WAIT
├── task-12.2 First Draft (Sonnet) - Deps: 12.1, 12.1.5 → WAIT
└── task-12.3 Critique (Opus) - Deps: 12.2 → WAIT

Multiple essays can do Step 1 (research) in parallel:

• Essay 12 research (task-12.1)
• Essay 3 research (task-3.1)
• Essay 5 research (task-5.1)

All three can run simultaneously (no dependencies between essays).

Epic Structure Pattern

Template:

Epic (Parent): [High-level goal]
├── Subtask 1: [Component A] (Dependencies: none)
├── Subtask 2: [Component B] (Dependencies: none)
├── Subtask 3: [Integration] (Dependencies: 1, 2)
└── Subtask 4: [Verification] (Dependencies: 3)

Real example:

Epic: Essay 12 - AI-Native Development (6-step workflow)
├── task-12.1: Research Compilation (Step 1) - Deps: none
├── task-12.1.5: Technical Deep-Dive (Step 1.5) - Deps: task-12.1
├── task-12.2: First Draft (Step 2) - Deps: task-12.1, task-12.1.5
├── task-12.3: Critique (Step 3) - Deps: task-12.2
├── task-12.4: Final Draft (Step 4) - Deps: task-12.3
└── task-12.5: Publication-Ready (Step 5) - Deps: task-12.4

Parallelization opportunities:

Across epics (different essays):

• All essay research tasks (Step 1) can run in parallel
• All technical analysis tasks (Step 1.5) can run in parallel after research completes
• All first drafts (Step 2) can run in parallel after prerequisites complete

Within epic:

• If subtasks have no dependencies, launch multiple subagents simultaneously
• Example: UI component + API endpoint can be built in parallel

Creating epic structure in Backlog:

1. Create parent epic:

   task_create(
     title="Essay 12: AI-Native Development (Complete 6-step workflow)",
     description="...",
     labels=["essay", "epic"],
     priority="high"
   )
   

2. Create subtasks with parentTaskId:

   task_create(
     title="Essay 12.1: Research Compilation (Step 1)",
     parentTaskId="task-12",
     dependencies=[],
     assignee=["Haiku"]
   )
   
   task_create(
     title="Essay 12.1.5: Technical Deep-Dive (Step 1.5)",
     parentTaskId="task-12",
     dependencies=["task-12.1"],
     assignee=["Sonnet"]
   )
   

Quality Checklist Before Marking Done

Before task_edit(status="Done"):

• All deliverables specified in task description created
• All acceptance criteria met (measurable verification)
• Changes committed to git with task ID reference (e.g., [task-12.1] Essay 12 Research)
• Task notes updated with commit hash and completion summary
• Dependencies verified (this task no longer blocks other tasks)
• Output reviewed against quality standards (if applicable)

Git commit pattern:

git commit -m "[task-12.1] Essay 12 Research Compilation

Compiled comprehensive research with RAND, MIT, BCG sources. Full citations verified against essay-research-compilation Skill standards."

Task completion note:

task_edit(
  id="task-12.1",
  status="Done",
  notesAppend=["Commit abc123: Research compilation complete with 100% citation coverage. Ready for Step 1.5."]
)

Common Patterns

Pattern 1: Sequential workflow (one essay)

Step 1 (Research) → Step 1.5 (Technical) → Step 2 (Draft) → Step 3 (Critique) → Step 4 (Final) → Step 5 (Publish)

Each step depends on previous step completing. No parallelization within single essay.

Pattern 2: Parallel workflows (multiple essays)

Essay A Step 1 ┐
Essay B Step 1 ├─ All run in parallel
Essay C Step 1 ┘

After all complete:

Essay A Step 1.5 ┐
Essay B Step 1.5 ├─ All run in parallel
Essay C Step 1.5 ┘

Maximize throughput by running same step across multiple essays simultaneously.

Pattern 3: Mixed parallel/sequential

Epic: Infrastructure Upgrade
├── Database migration (Subtask 1) - Independent
├── API refactor (Subtask 2) - Independent
├── Integration tests (Subtask 3) - Depends on 1 AND 2
└── Deployment (Subtask 4) - Depends on 3

Subtasks 1 and 2 run in parallel. Subtask 3 waits for both. Subtask 4 waits for 3.

Pattern 4: ML Project (4-session workflow)

Epic: [Project Name] - ML Pipeline
├── Session 1: ETL (Data loading, validation, split) - Gate G1
├── Session 2: EDA (Profiling, baseline, features) - Gate G2, Deps: Session 1
├── Session 3: MODELING (Ideation, training, champion) - Gates G3/G4, Deps: Session 2
└── Session 4: DELIVERY (Test eval, SHAP, reports) - Gate G5, Deps: Session 3

ML project task structure:

task_create(
  title="[Project Name] - ML Pipeline",
  description="4-session ML workflow: [problem statement]

  ## Goal
  [Business objective and success criteria]

  ## Data
  [Data sources, target column, problem type]

  ## Sessions
  - Session 1 (ETL): Load, validate, split data
  - Session 2 (EDA): Profile data, establish baseline
  - Session 3 (MODELING): Feature engineering, train models
  - Session 4 (DELIVERY): Test evaluation, reports
  ",
  labels=["ml-project", "4-session"],
  priority="high",
  acceptanceCriteria=[
    "Session 1 (ETL): G1 passed - Data loaded and split",
    "Session 2 (EDA): G2 passed - Baseline established",
    "Session 3 (MODELING): G3/G4 passed - Champion model beats baseline",
    "Session 4 (DELIVERY): G5 passed - Test evaluation complete"
  ]
)

Session execution pattern:

Each session follows this protocol:

1. Start session (fresh chat):

   task_search(query="[project-name]")
   task_edit(
     id="task-X",
     status="In Progress",
     labels=["ml-project", "session-N-<phase>"],
     notesAppend=["Starting Session N (<PHASE>) - <timestamp>"]
   )
   

2. Execute session work: Follow session-specific skill guidance

3. End session (commit + update):

   git commit -m "[task-X] [PHASE] Description
   
   - Key deliverables
   - Gate status: PASSED"
   
   task_edit(
     id="task-X",
     notesAppend=[
       "Session N (<PHASE>) completed - commit: <hash>",
       "Gate G<N>: PASSED",
       "Key metrics: <metric>: <value>",
       "Next: Session <N+1> in fresh chat"
     ],
     acceptanceCriteriaCheck=[<N>]
   )
   

Knowledge transfer between sessions:

• Session 1 → 2: 01_etl_summary.md, project_context.json
• Session 2 → 3: 02_eda_summary.md, eda_handoff.json (critical metrics)
• Session 3 → 4: 03_modeling_summary.md, modeling_handoff.json (champion model)

Task notes supplement handoff files with session-specific context (blockers, decisions, learnings).

Troubleshooting

Problem: Can't find existing task

Solution: Expand search (remove filters, try synonyms, check archived tasks)

Problem: Task blocked by dependency

Solution: Check dependency status with task_view(id="blocking-task-id"). If blocking task stalled, communicate in notes or escalate.

Problem: Multiple sessions working on same task

Solution: First session to mark "In Progress" owns the task. Other sessions should coordinate via task notes or find different work.

Problem: Epic too large to track

Solution: Break into smaller epics or use milestones for grouping. Each epic should represent ~1-2 weeks of work maximum.

Problem: Task scope grew during execution

Solution:

1. Complete original task scope
2. Mark original task Done
3. Create new task for expanded scope with dependency on completed task

MCP Tool Reference

Search:

• task_search(query="keywords", limit=20) - Fuzzy search title/description
• task_list(status="To Do", limit=50) - Filter by status
• task_list(labels=["essay"], limit=30) - Filter by label

CRUD:

• task_create(title, description, acceptanceCriteria, dependencies, assignee, priority, labels)
• task_view(id="task-X") - View full task details
• task_edit(id, status, notesAppend, planSet, ...) - Update task
• task_complete(id="task-X") - Archive to completed folder

Workflow:

• task_edit(id, status="In Progress") - Claim task
• task_edit(id, status="Done") - Mark complete
• task_edit(id, notesAppend=["Session update"]) - Communicate progress
• task_edit(id, planSet="1. Step\n2. Step") - Document approach

Dependencies:

• Set during creation: dependencies=["task-X", "task-Y"]
• Update later: task_edit(id, dependencies=["task-X", "task-Y"])
• Check blocking: task_view(id) and inspect dependencies field