## Task Creation Guide

This guide provides detailed instructions for creating well-structured tasks. You should already know WHEN to create tasks (from the overview).

### Step 1: Search for existing work

**IMPORTANT - Always use filters when searching:**
- Use `task_search` with query parameter (e.g., query="desktop app")
- Use `task_list` with status filter to exclude completed work (e.g., status="To Do" or status="In Progress")
- Never list all tasks including "Done" status without explicit user request
- Never search without a query or limit - this can overwhelm the context window

Use `task_view` to read full context of related tasks.

### Step 2: Assess scope BEFORE creating tasks

**CRITICAL**: Before creating any tasks, assess whether the user's request is:
- **Single atomic task** (single focused PR): Create one task immediately
- **Multi-task feature or initiative** (multiple PRs, or parent task with subtasks): Create appropriate task structure

**Scope assessment checklist** - Answer these questions FIRST:
1. Can this be completed in a single focused pull request?
2. Would a code reviewer be comfortable reviewing all changes in one sitting?
3. Are there natural breaking points where work could be independently delivered and tested?
4. Does the request span multiple subsystems, layers, or architectural concerns?
5. Are multiple tasks working on the same component or closely related functionality?

If the work requires multiple tasks, proceed to choose the appropriate task structure (subtasks vs separate tasks).

### Agent Lifecycle Reality

**Assume the agent who creates tasks will NOT execute them.** Each task is handled by an independent agent session with no memory of prior conversations or other tasks.

- Write tasks as work orders for strangers: include all required context inside the task
- Never reference "what we discussed" without restating the essential decisions and constraints
- Dependencies must explicitly state what the other task provides (e.g., output, schema, artifact)
- Use the `references` field for external references such as GitHub issues, PRs, tickets, or URLs
- Use the `documentation` field for design docs, API specs, manuals, or other reference materials that help understand the task context
- Only include minimal local code context in the description when omitting it would make the task ambiguous or unsafe for a future implementer

### Step 3: Choose task structure

**When to use subtasks vs separate tasks:**

**Use subtasks** (parent-child relationship) when:
- Multiple tasks all modify the same component or subsystem
- Tasks are tightly coupled and share the same high-level goal
- Tasks represent sequential phases of the same feature
- Example: Parent task "Desktop Application" with subtasks for Electron setup, IPC bridge, UI adaptation, packaging

**Use separate tasks** (with dependencies) when:
- Tasks span different components or subsystems
- Tasks can be worked on independently by different developers
- Tasks have loose coupling with clear boundaries
- Example: Separate tasks for "API endpoint", "Frontend component", "Documentation"

**Concrete example**: If a request spans multiple layers—say an API change, a client update, and documentation—create one parent task ("Launch bulk-edit mode") with subtasks for each layer. Note cross-layer dependencies (e.g., "UI waits on API schema") so different collaborators can work in parallel without blocking each other.

### Step 4: Create multi-task structure

When scope requires multiple tasks:
1. **Create the task structure**: Either parent task with subtasks, or separate tasks with dependencies
2. **Explain what you created** to the user after creation, including the reasoning for the structure
3. **Document relationships**: Record dependencies using `task_edit` so scheduling and merge-risk tooling stay accurate

**Follow-up work on an existing task:** Create it as a **subtask** of that parent task (not a new top-level task).

Create all tasks in the same session to maintain consistency and context.

### Step 5: Create task(s) with proper scope

**Title and description**: Explain desired outcome and user value (the WHY). Keep the description focused on outcome and essential handoff context.

**Acceptance criteria**: `acceptanceCriteria` is an array of strings; each item should be specific, testable, and independent (the WHAT)
- Keep each checklist item atomic (e.g., "Display saves when user presses Ctrl+S")
- Include negative or edge scenarios when relevant
- Capture testing expectations explicitly
- Include documentation expectations in the same task (no deferring to follow-up tasks)

**Definition of Done defaults (optional):**
- Project-level defaults are managed with `definition_of_done_defaults_get` / `definition_of_done_defaults_upsert`
- DoD is not acceptance criteria: AC defines product scope/behavior, DoD defines completion hygiene
- Per-task DoD customization should be exceptional; default to project-level DoD plus strong acceptance criteria
- Use `definitionOfDoneAdd` only for task-specific DoD items that apply to this one task
- Use `disableDefinitionOfDoneDefaults` to skip project defaults for this task when needed
- Do **not** duplicate project defaults into `definitionOfDoneAdd` unless you are intentionally customizing this task

**Never embed implementation details** in title, description, or acceptance criteria

**Record dependencies** using `task_edit` for task ordering

**Ask for clarification** if requirements are ambiguous

**Drafts (exceptional):** Default to creating regular tasks (e.g., To Do) for any work you are committing to track. Only create a Draft when the user explicitly requests a draft, or when there is clear uncertainty that makes a commitment inappropriate (e.g., missing requirements and the user wants a placeholder). Use `task_create` with status `Draft` to create a draft, `task_edit` to promote/demote by changing status, and pass status `Draft` to `task_list`/`task_search` to include drafts. Drafts are excluded unless explicitly filtered.

### Step 6: Report created tasks

After creation, show the user each new task's ID, title, description, and acceptance criteria (e.g., "Created task-290 – API endpoint: …"). This provides visibility into what was created and allows the user to request corrections if needed.

### Common Anti-patterns to Avoid

- Creating a single task called "Build desktop application" with 10+ acceptance criteria
- Adding implementation steps to acceptance criteria
- Creating a task before understanding if it needs to be split
- Deferring tests or documentation to "later tasks" (e.g., "Add tests/docs in a follow-up")

### Correct Pattern

"This request spans electron setup, IPC bridge, UI adaptation, and packaging. I'll create 4 separate tasks to break this down properly."

Then create the tasks and report what was created.

**Standalone task example (includes tests/docs):** "Add API endpoint for bulk updates" with acceptance criteria that include required tests and documentation updates in the same task.

### Additional Context Gathering

- Use `task_view` to read the description, acceptance criteria, dependencies, current plan, and notes before acting
- Inspect relevant code/docs/tests in the repository to ground your understanding
- When permitted, consult up-to-date external references (design docs, service manuals, API specs) so your plan reflects current reality
