Backlog Task Creation Skill

Core Mission

Create well-defined, atomic tasks with clear acceptance criteria using the Backlog.md CLI tool.

⚠️ CRITICAL: NEVER EDIT TASK FILES DIRECTLY. Edit Only via CLI

ALL task operations MUST use the Backlog.md CLI commands

• ✅ DO: Use backlog task create to create new tasks
• ✅ DO: Use backlog task edit for all modifications
• ✅ DO: Use backlog task create with --ac flags for acceptance criteria
• ❌ DON'T: Edit markdown files directly
• ❌ DON'T: Manually create files in backlog/tasks/
• ❌ DON'T: Add or modify text in task files without using CLI

Why? Direct file editing breaks metadata synchronization, Git tracking, and task relationships.

1. Source of Truth & File Structure

📖 UNDERSTANDING (What you'll see when reading)

• Markdown task files live under backlog/tasks/ (drafts under backlog/drafts/)
• Files are named: task-<id> - <title>.md (e.g., task-42 - Add GraphQL resolver.md)
• Project documentation is in backlog/docs/
• Project decisions are in backlog/decisions/

🔧 ACTING (How to change things)

• All task operations MUST use the Backlog.md CLI tool
• This ensures metadata is correctly updated and the project stays in sync
• Always use --plain flag when listing or viewing tasks for AI-friendly text output

2. Common Mistakes to Avoid

❌ WRONG: Direct File Editing

# DON'T DO THIS:

1. Open backlog/tasks/task-7 - Feature.md in editor
2. Change "- [ ]" to "- [x]" manually
3. Add notes directly to the file
4. Save the file

✅ CORRECT: Using CLI Commands

# DO THIS INSTEAD:
backlog task create "Feature title" -d "Description" --ac "First criterion"
backlog task edit 7 --check-ac 1  # Mark AC #1 as complete
backlog task edit 7 --notes "Implementation complete"  # Add notes

3. Understanding Task Format (Read-Only Reference)

⚠️ FORMAT REFERENCE ONLY - The following sections show what you'll SEE in task files. Never edit these directly! Use CLI commands to make changes.

Task Structure You'll See

---
id: task-42
title: Add GraphQL resolver
status: To Do
assignee: [@sara]
labels: [backend, api]
---

## Description

Brief explanation of the task purpose.

## Acceptance Criteria

<!-- AC:BEGIN -->

- [ ] #1 First criterion
- [x] #2 Second criterion (completed)
- [ ] #3 Third criterion

<!-- AC:END -->

## Implementation Plan

1. Research approach
2. Implement solution

## Implementation Notes

Summary of what was done.

How to Modify Each Section

4. Defining Tasks

Creating New Tasks

Always use CLI to create tasks:

# Basic creation
backlog task create "Task title"

# With description
backlog task create "Task title" -d "Description"

# With acceptance criteria
backlog task create "Task title" -d "Description" --ac "First criterion" --ac "Second criterion"

# Full example with all options
backlog task create "Add user authentication" \
  -d "Implement JWT-based authentication for API" \
  --ac "User can login with valid credentials" \
  --ac "Invalid credentials return 401 error" \
  --ac "JWT token expires after 24 hours" \
  -l auth,security \
  --priority high \
  -a @myself

# Create as draft
backlog task create "Task title" --draft

# Create subtask
backlog task create "Subtask title" -p 42

Title (one liner)

Use a clear brief title that summarizes the task.

Description (The "why")

Provide a concise summary of the task purpose and its goal. Explains the context without implementation details.

Acceptance Criteria (The "what")

Understanding the Format:

• Acceptance criteria appear as numbered checkboxes in the markdown files
• Format: - [ ] #1 Criterion text (unchecked) or - [x] #1 Criterion text (checked)

Managing Acceptance Criteria via CLI:

⚠️ IMPORTANT: How AC Commands Work

• Adding criteria (--ac) accepts multiple flags: --ac "First" --ac "Second" ✅
• Multiple ACs in one command: --ac "AC1" --ac "AC2" --ac "AC3" ✅

# Examples

# Add multiple criteria
backlog task edit 42 --ac "User can login" --ac "Session persists"

# ❌ WRONG - These formats don't work:
# backlog task edit 42 --ac "AC1,AC2"  # No comma-separated values
# backlog task edit 42 --ac "AC1" "AC2"  # Wrong syntax

Key Principles for Good ACs:

• Outcome-Oriented: Focus on the result, not the method.
• Testable/Verifiable: Each criterion should be objectively testable
• Clear and Concise: Unambiguous language
• Complete: Collectively cover the task scope
• User-Focused: Frame from end-user or system behavior perspective

Good Examples:

• "User can successfully log in with valid credentials"
• "System processes 1000 requests per second without errors"
• "CLI preserves literal newlines in description/plan/notes"

Bad Example (Implementation Step):

• "Add a new function handleLogin() in auth.ts"
• "Define expected behavior and document supported input patterns"

Task Breakdown Strategy

1. Identify foundational components first
2. Create tasks in dependency order (foundations before features)
3. Ensure each task delivers value independently
4. Avoid creating tasks that block each other

Task Requirements

• Tasks must be atomic and testable or verifiable
• Each task should represent a single unit of work for one PR
• Never reference future tasks (only tasks with id < current task id)
• Ensure tasks are independent and don't depend on future work

5. CLI Command Reference for Task Creation

Task Creation

Task Modification (Metadata)

Acceptance Criteria Management

6. Quick Reference: DO vs DON'T

Creating Tasks

Remember: The Golden Rule

🎯 Always use backlog task create for new tasks and backlog task edit for modifications. 📖 Use CLI to read tasks, exceptionally READ task files directly, never WRITE to them.

Full help available: backlog --help