task-creation

What this skill does

# Task Creation

Create well-formed tasks in an issue tracker. The input is either a decomposition document (from the pipeline) or a
standalone request from a user. The output is a tracked task with enough context for an implementer to start work
without asking questions.

## When to Use

**From the pipeline:** After `frame` produces a frame document with vertical slice phases, this skill handles creating
tasks from those phases in the issue tracker with proper fields, categorization, and linking.

**Standalone:** When a user requests a task directly — "create a bug for the pagination issue" or "add a task to upgrade
the dependency." No decomposition document needed; gather context from the conversation.

## Creating a Task

### Step 1: Gather Context

This is an active discovery step — use available tools, don't rely on inference.

1. **Identify the tracker** — Check which task tracking tools are available (MCP servers, APIs, CLI integrations). If
   multiple trackers are present, ask the user which one to use. Don't assume.
2. **Discover the project** — Use the tracker's project listing or configuration tools to find the target project. Infer
   from conversation context (directory, subsystem, prior tasks) when possible, but validate against the tracker. If
   ambiguous, ask the user.
3. **Explore project configuration** — Query the tracker for the project's field setup:
   - What fields exist (type, priority, severity, component, sprint, etc.)
   - Which fields are required vs optional
   - What values are valid for each field (the tracker defines these, not this skill) Don't hardcode assumptions — field
     names, types, and valid values differ across projects and trackers.
4. **Determine task type** — Based on the user's intent and the project's available types, select the closest match:
   - Something is broken → bug/defect type
   - Implementation work → task/story type
   - New capability → feature/story type The exact type name comes from the tracker, not from a universal list.
5. **Identify source material** — Link to decomposition document, design document, or technical design if available. If
   standalone, the conversation is the source.

### Step 2: Draft the Task

1. **Write the title.** The title is what people see in lists, boards, and notifications:
   - **Imperative mood:** "Add pagination to search results" not "Pagination was added"
   - **Specific:** "Fix negative offset in paginator navigation" not "Fix pagination bug"
   - **5-10 words:** Long enough to be meaningful, short enough to scan
   - **No tracker noise:** Don't prefix with project codes, parent references, or type labels — the tracker handles
     metadata

2. **Write the description.** Structure depends on task type, but every description needs:

   **Context** — Why this task exists. Connect it to the larger effort. Link to the design document or technical design
   if one exists. One or two sentences.

   **What to do** — The specific work. Concrete enough that the implementer knows the scope, abstract enough that they
   choose the approach. Describe the change, not the code.

   **Acceptance criteria** — How to know it's done. See the dedicated section below.

   **References** (optional) — Links to resources that already exist: design documents, technical designs, external
   specs, documentation URLs, mockups. Every item must be a real, verifiable resource — a file that exists on disk or a
   URL that resolves. Never include code paths, file paths to source code, or references to files that will be created
   during implementation. Code-level details belong in implementation, not task descriptions. Never reference other
   tasks in the same tracker — inter-task relationships are handled exclusively through native tracker links in Step 4.
   Omit this section entirely when there are no existing resources to link.

   Every task needs a description. Extract intent, structure it, and link to the conversation if someone needs the raw
   thread — never copy-paste chat messages directly.

3. **Set fields** based on what you discovered in Step 1. Carry over estimates from the decomposition document if
   available. Only set fields that the tracker supports and the project uses — don't invent metadata.

### Step 3: Present the Draft

1. Show the complete task to the user before creating it. Include all fields using actual field names and values from
   the project configuration:

```markdown
## Task Draft

**Project:** [project name]
**Type:** [value from tracker]

**Title:** [title]

**Description:**
[full description with context, what to do, acceptance criteria, references]

**Fields:**
[list each field you plan to set with its value, based on project config]
```

2. Wait for explicit approval. Tasks are visible to the entire team once created — a wrong task creates noise and
   confusion.
3. If the user requests changes, revise and present again.

### Step 4: Create in Tracker

After approval:

1. Create the task using the tracker's API or integration.
2. Set all agreed fields.
3. Establish relationships between tasks:
   - Use the tracker's native linking for all relationships (parent-child, blocks/blocked-by, depends-on, relates-to,
     duplicates). A single pair of tasks can have more than one relationship — create every one that applies.
   - Always prefer native links over description text. Native links are visible in dedicated UI, enable dependency
     tracking, and stay current when tasks move or rename.
   - Fallback to description-based references only if the tracker's tools genuinely lack linking capabilities. Check the
     available tools first.
4. Report the created task ID and URL back to the user.

## Acceptance Criteria

Acceptance criteria are the most important part of a task description after context. They transform vague intent ("make
search faster") into verifiable conditions ("search returns results within 200ms for queries under 50 characters").

### What Makes Good Criteria

**Testable** — Each criterion has a clear pass/fail outcome. "User experience is improved" fails this test. "Page loads
in under 2 seconds on 3G" passes.

**Outcome-focused** — Describe what the system does, not how it's built. "Search returns partial matches for inputs of
3+ characters" — not "implement a LIKE query with wildcard prefix."

**Independent** — Each criterion can be verified on its own. If criterion B can only be tested after criterion A,
consider whether they're really one criterion.

**Measurable** — Quantify when possible. Response times, character limits, item counts, error rates. Numbers eliminate
ambiguity. Replace vague conditions like "should be fast" or "user-friendly interface" with measurable thresholds.

### Two Formats

**Rule-oriented (checklist)** — Best for most engineering tasks. Simple, scannable, directly translatable to test cases:

```markdown
- [ ] Search field appears in the top navigation bar
- [ ] Search triggers on button click or Enter key
- [ ] Input accepts up to 200 characters
- [ ] Results display within 500ms for datasets under 10,000 records
- [ ] Empty query shows recent items instead of empty state
```

**Scenario-oriented (Given/When/Then)** — Best for complex user flows where preconditions and sequences matter:

```markdown
Given the user is on the search page with an empty query
When they type 3 or more characters
Then results appear as a dropdown below the search field

Given the user has selected a filter
When they clear the search field
Then the filter remains applied and results update accordingly
```

Use rule-oriented by default. Switch to scenario-oriented when the behavior depends on specific preconditions or
multi-step sequences.

### Common Mistakes

**Too vague:** "Works correctly" or "handles edge cases" — what does correctly mean? Which edge cases? Every criterion
needs a clear pass/fail outcome.

**Too prescriptive:** "Use a Redis cache with TTL of 300 seconds" — that's implementation, not acceptanc