Task Creation Skill

Converts conversational task descriptions into structured work items (beads) with automatic categorization, priority assignment, and dependency tracking.

When to Use

Activate this skill when users ask to:

• Create or add a new task or issue
• Track work that needs to be done
• Convert conversational descriptions into structured work items
• Document something to remember or do later
• Set up tasks with blocking relationships
• Categorize and prioritize work

Required Information

Gather from conversation:

Field	Type	Example	Notes
Title	String	"Fix blog pagination bug"	Clear, specific task name
Description	String	"The blog archive page shows 404 on pages 2+ after deployment"	Detailed context and acceptance criteria

Optional Information

Field	Type	Example	Notes
Tags	Array	["bug", "urgent", "frontend"]	For categorization and filtering
Blocking	Array	["task-id-123"]	Task IDs this blocks (dependent tasks)
BlockedBy	Array	["task-id-456"]	Task IDs that block this one
Priority	Number	1-5	1=critical, 5=low (inferred if not provided)

Auto-Categorization Rules

The system automatically determines task type and priority from natural language patterns:

Task Type Detection

Pattern	Type	Emoji
"fix", "resolve", "patch", "bug"	bug	🐛
"add", "create", "implement", "build"	feature	✨
"improve", "enhance", "optimize", "refactor"	enhancement	🔧
"update", "upgrade", "bump", "patch version"	chore	⚙️
"document", "write", "add docs", "update README"	documentation	📝
"investigate", "research", "explore", "investigate"	research	🔍

Priority Inference

Pattern	Priority	Rationale
"critical", "urgent", "blocking", "ASAP", "now"	1 (P0)	Immediate action needed
"important", "high", "soon", "before release"	2 (P1)	Next cycle priority
"normal", "should", "eventually"	3 (P2)	Standard priority
"nice-to-have", "consider", "backlog"	4 (P3)	Lower priority
"someday", "maybe", "if time"	5 (P4)	Lowest priority

Generation Process

Step 1: Gather Task Information

Collect through conversation:

1. "What needs to be done?" (Title)
2. "Can you describe more details?" (Description)
3. "Any context on why or when?" (Optional tags/priority hints)

If user provides conversational description like "The blog is broken on mobile", extract and clarify:

• Title: "Fix mobile layout on blog pages"
• Description: Expanded context about the issue

Step 2: Auto-Detect Category and Priority

Parse the description and title for keywords:

• Identify task type from verb patterns
• Infer priority from urgency keywords
• Extract dependencies if mentioned

Step 3: Invoke Task Agent

Run the TypeScript agent to create the task:

bun run packages/agents/src/cli/agent-cli.ts task-create \
  --title "{{title}}" \
  --description "{{description}}" \
  --type {{type}} \
  --priority {{priority}} \
  --tags "{{tags}}" \
  --blocking "{{blocking}}" \
  --blocked-by "{{blocked_by}}"

The agent will:

1. Parse natural language input
2. Create a structured bead in .beads/issues.jsonl
3. Assign a unique task ID
4. Set up blocking relationships if provided
5. Return task details and confirmation

Example output:

--- Task Agent ---

Creating task from description...

[SUCCESS] Task created

Task ID: PROJ-123
Title: Fix blog pagination bug
Type: bug (🐛)
Priority: P1 (High)
Status: pending

Description:
The blog archive page shows 404 on pages 2+ after deployment.
Root cause appears to be missing pagination handler in router.

URL: [task details URL]

Step 4: Display and Confirm

Show the user:

• Generated task ID
• Auto-detected category and priority
• Full description as it was stored
• Any blocking relationships
• Next steps for the task (assignment, workflow)

Task Type Definitions

Bug (🐛)

Something is broken or not working as expected.

• Markers: "fix", "broken", "bug", "error", "issue", "not working"
• Default Priority: P1 or P2 depending on urgency keywords

Feature (✨)

New functionality to add.

• Markers: "add", "create", "implement", "build", "new"
• Default Priority: P2 or P3 (features are typically planned)

Enhancement (🔧)

Improving existing functionality.

• Markers: "improve", "enhance", "optimize", "refactor", "speed up", "better"
• Default Priority: P2 or P3

Chore (⚙️)

Maintenance, dependency updates, configuration changes.

• Markers: "update", "upgrade", "bump", "version", "dependencies"
• Default Priority: P3 (non-blocking)

Documentation (📝)

Writing or updating documentation.

• Markers: "document", "write docs", "add README", "update guide"
• Default Priority: P3 (can document in parallel)

Research (🔍)

Investigation or evaluation needed.

• Markers: "investigate", "research", "explore", "evaluate", "compare"
• Default Priority: P3 or P4 (time-bounded research)

Dependency Management

Setting Up Blocking Relationships

If a task depends on another or blocks others, express as:

User: "I need to refactor the API before we can optimize the cache layer"

Response: Extract two tasks:

• Task A: "Refactor the API" → Type: enhancement, Priority: P1
• Task B: "Optimize cache layer" → Type: enhancement, Priority: P2
• Set: Task B is blocked by Task A

bun run packages/agents/src/cli/agent-cli.ts task-create \
  --title "Optimize cache layer" \
  --description "..." \
  --type enhancement \
  --blocked-by "{{task-a-id}}"

Querying Blockers

After creating tasks, show dependencies:

Task PROJ-124 (Optimize cache) is blocked by:
  └─ PROJ-123 (Refactor API) - pending

Cannot start until PROJ-123 is completed.

Writing Task Descriptions

Do:

• Be specific about what needs to happen
• Include context: why, where, what problem it solves
• Add acceptance criteria if applicable ("The page should load in < 1s")
• Mention any related tasks or tickets
• Include error messages or reproduction steps for bugs

Avoid:

• Generic descriptions like "fix stuff"
• Assumptions about implementation details (let the executor decide)
• Combining multiple unrelated tasks in one item
• Vague impact statements ("make it better")

Example Interactions

Example 1: Simple Bug Report

User: "The checkout button on the homepage is broken"

Response:

1. Clarify: "Can you describe what's broken? Is it not clickable, hidden, or showing an error?"
2. Gather details about browser, reproduction steps
3. Create task:

   Task ID: PROJ-201
   Title: Fix checkout button functionality on homepage
   Type: bug (🐛)
   Priority: P1 (Critical - affects conversions)
   

Example 2: Feature Request with Dependencies

User: "I want to add an analytics dashboard, but first we need to set up event tracking"

Response:

1. Create two tasks:

   Task ID: PROJ-301
   Title: Implement event tracking infrastructure
   Type: feature (✨)
   Priority: P1
   
   Task ID: PROJ-302
   Title: Build analytics dashboard
   Type: feature (✨)
   Priority: P2
   Blocked By: PROJ-301
   

2. Show the dependency chain
3. Explain that PROJ-302 cannot start until PROJ-301 is completed

Example 3: Enhancement with Optimization Context

User: "We should optimize the blog query performance, it's getting slow with more posts"

Response:

1. Gather: "How slow? Do you have metrics? Which queries are slow?"
2. Create task:

   Task ID: PROJ-401
   Title: Optimize blog query performance
   Type: enhancement (🔧)
   Priority: P2
   
   Description:
   Blog queries are getting slower as post count increases.
   Goal: Sub-100ms response time for archive pages.
   Consider indexing strategy, caching layer, and query optimization.
   

File Locations

Purpose	Path
Task tracking	.beads/issues.jsonl
Task agent	packages/agents/src/task/task-agent.ts
CLI handler	packages/agents/src/cli/agent-cli.ts
Type definitions	packages/agents/src/types/index.ts

Task Lifecycle

Tasks created with this skill start in pending status:

pending → in_progress → completed
            ↓
        (if issues)
          resolved

Use beads commands to manage lifecycle:

bd update <task-id> --status in_progress
bd update <task-id> --status completed
bd close <task-id>

Common Patterns

Multi-step Breakdown

If user describes complex work, offer to break into subtasks:

User: "Redesign the checkout flow"

Suggest:

• Task 1: "Design checkout wireframes"
• Task 2: "Implement checkout form component"
• Task 3: "Integrate payment processing"
• Task 4: "Add order confirmation page"

Set dependencies so they work in sequence.

Adding Context from Errors

For bug reports, include error messages and logs in description:

Task: Fix authentication redirect loop

Description:
Users report infinite redirect when accessing /dashboard after login.

Error log:
  [ERROR] /auth/callback → /dashboard → /login → /auth/callback

Environment: Production
Affected users: ~15% of login attempts
First reported: 2026-01-24

Voice Learning

Record feedback on task creation for improvement:

Location: .cody/project/library/style-docs/task-style.json

Track:
- Effective task titles (what works)
- Common categorization errors (what to fix)
- Useful description patterns (what to encourage)

Integration with Workflows

After task creation, users can:

1. Assign - bd update <task-id> --owner <name>
2. Add labels - bd label add <task-id> bug frontend
3. Link dependencies - bd dep add <task-a> --blocks <task-b>
4. Start working - bd update <task-id> --status in_progress