Write Atomic Tasks

Quick Start

Transform vague task descriptions into precise, autonomous-execution-ready specifications:

❌ BEFORE (vague):
- [ ] Add error handling

✅ AFTER (precise):
- [ ] Task 1: Add ConnectionError and TimeoutError handling to ClaudeAgentClient.query()
      - Retry 3 times with exponential backoff (1s, 2s, 4s)
      - Raise AgentConnectionError after retries exhausted
      - Location: src/temet_run/agent/client.py:ClaudeAgentClient.query
      - Verify: pytest tests/unit/agent/test_client.py passes

Table of Contents

1. When to Use This Skill
2. What This Skill Does
3. The SMART+ Framework
4. Task Template
5. Precision Checklist
6. Forbidden Vague Patterns
7. Task Decomposition Rules
8. Examples: Vague → Precise Transformation
9. Validation Process
10. Supporting Files
11. Expected Outcomes
12. Requirements
13. Red Flags to Avoid

When to Use This Skill

Explicit Triggers:

• "Write a task for..."
• "Create todo items for..."
• "Break down this feature into tasks"
• "Make this task more precise"
• "How should I write this as a task?"

Implicit Triggers:

• Task description lacks file paths
• No verification command specified
• Vague action verbs ("fix", "add", "update" without specifics)
• Missing success criteria
• Task would require clarifying questions before starting

Debugging/Quality Scenarios:

• Reviewing task list for autonomous execution readiness
• Agent keeps asking clarifying questions about tasks
• Tasks take longer than expected due to ambiguity
• Post-mortem reveals task interpretation issues

What This Skill Does

This skill transforms vague task descriptions into precise, autonomous-execution-ready specifications by:

1. Applying SMART+ Framework - Ensuring every task is Specific, Measurable, Actionable, Referenced, Testable, with Context
2. Adding Critical Metadata - File paths, verification commands, success criteria
3. Decomposing Large Work - Breaking complex tasks into 30-minute chunks
4. Eliminating Vague Patterns - Replacing forbidden phrases with precise alternatives
5. Validating Precision - Checking that tasks answer all 6 precision questions

The SMART+ Framework

Every task MUST include these components:

Component	Description	Example
Specific	What exactly to do	"Add retry logic to ClaudeAgentClient.query()" not "Add retry logic"
Measurable	How to verify completion	"Tests pass, mypy clean"
Actionable	Clear first step	"Create file src/temet_run/agent/retry.py"
Referenced	File paths, functions, classes	"in agent/client.py:ClaudeAgentClient"
Testable	Success criteria	"3 retries with exponential backoff, circuit breaker after 5 failures"
+Context	Why this matters (optional)	"Needed for ADR-016 conversation persistence"

Task Template

- [ ] Task N: [ACTION VERB] [SPECIFIC TARGET] [SUCCESS CRITERIA]
      Location: [file paths or module names]
      Verify: [how to confirm completion]

Complete Example:

- [ ] Task 1: Add ConversationError exception hierarchy to agent/errors.py
      - Create: ConversationError(base), MessageError, StateError
      - Location: src/temet_run/agent/errors.py
      - Verify: mypy passes, errors importable from temet_run.agent

Precision Checklist

Before writing a task, verify it answers ALL these questions:

1. ✅ WHAT file(s)? → Include full path from project root
2. ✅ WHAT function/class? → Name the specific target
3. ✅ WHAT action? → Use precise verbs: Create, Add, Modify, Remove, Rename, Extract, Move
4. ✅ WHAT inputs/outputs? → Specify types, fields, parameters
5. ✅ HOW to verify? → Command to run: pytest path, mypy src/, uv run temet-run ...
6. ✅ WHY doing this? → Link to ADR, issue, or parent task (optional but helpful)

Forbidden Vague Patterns

NEVER write tasks containing these vague phrases:

❌ Forbidden Pattern	✅ Precise Alternative
"Implement the feature"	"Implement X method in Y class with Z behavior"
"Add tests"	"Add unit tests for X covering cases A, B, C"
"Fix the bug"	"Fix TypeError in X:line Y caused by Z"
"Update the code"	"Update X function to accept Y parameter"
"Handle errors"	"Add try/except for ConnectionError in X, retry 3 times"
"Refactor"	"Extract X logic from Y into new Z class"
"Improve performance"	"Reduce X function runtime from 500ms to <100ms by caching Y"
"Add logging"	"Add structlog info-level logging to X function for events A, B, C"
"Document the code"	"Add Google-style docstring to X function with Args, Returns, Raises"

Task Decomposition Rules

Large tasks MUST be broken down:

1. One concern per task - Don't mix "create model AND write tests AND add CLI"
2. Max 30 minutes of work - If longer, split it
3. Dependencies explicit - "Task 3 depends on Task 2" or use sub-numbering (2.1, 2.2)
4. Verification per task - Each task independently verifiable

Decomposition Example:

## Feature: Add conversation history command

- [ ] Task 1: Create ConversationRepository protocol
      Location: src/temet_run/domain/repositories.py
      Verify: mypy passes

- [ ] Task 2: Implement JsonlConversationRepository
      Location: src/temet_run/infrastructure/repositories/conversation.py
      Verify: Unit tests pass (create tests/unit/infrastructure/test_conversation_repo.py)

- [ ] Task 3: Add `history` subcommand to CLI
      Location: src/temet_run/main.py (add to agents group)
      Verify: `uv run temet-run agents history --help` shows usage

- [ ] Task 4: Integration test for history command
      Location: tests/integration/test_cli_history.py
      Verify: pytest tests/integration/test_cli_history.py passes

Examples: Vague → Precise Transformation

See examples/transformation-examples.md for comprehensive examples covering:

• Error handling tasks
• Data model implementation
• Test writing tasks
• Bug fixes
• Feature additions
• Refactoring work

Inline Example:

❌ VAGUE:
- [ ] Add error handling to the client

✅ PRECISE:
- [ ] Add ConnectionError and TimeoutError handling to ClaudeAgentClient.query()
      - Retry 3 times with exponential backoff (1s, 2s, 4s)
      - Raise AgentConnectionError after retries exhausted
      - Location: src/temet_run/agent/client.py:ClaudeAgentClient.query
      - Verify: pytest tests/unit/agent/test_client.py passes

Validation Process

To validate a task for precision:

1. Read the task description
2. Apply the 6-question checklist (Section 5)
3. Check for forbidden vague patterns (Section 6)
4. Verify SMART+ components present (Section 3)
5. Confirm task is <30 minutes of work

Validation Script (if available):

python ~/.claude/skills/write-atomic-tasks/scripts/validate_task.py "task description"

Manual Validation Output:

Task: "Add error handling to the client"

❌ FAILED Precision Check:
- Missing: Specific file path
- Missing: Function/class name
- Missing: Verification command
- Vague pattern: "Add error handling" (see Section 6)

Suggested rewrite:
- [ ] Add ConnectionError handling to ClaudeAgentClient.query()
      Location: src/temet_run/agent/client.py:ClaudeAgentClient.query
      Verify: pytest tests/unit/agent/test_client.py passes

Supporting Files

• examples/transformation-examples.md - 10+ examples of vague → precise transformations
• references/smart-framework-deep-dive.md - Detailed explanation of SMART+ components
• scripts/validate_task.py - Automated task precision validator
• templates/task-template.md - Copy-paste task template with placeholders

Expected Outcomes

Successful Task Writing

When tasks are written with this skill:

✅ Agents can execute autonomously - No clarifying questions needed ✅ Clear verification - Unambiguous success/failure determination ✅ Predictable effort - Tasks complete in <30 minutes ✅ Reduced rework - Fewer interpretation errors ✅ Better planning - Accurate time estimates from precise scoping

Before/After Metrics

Metric	Before (Vague Tasks)	After (Precise Tasks)
Clarifying questions per task	2-5 questions	0 questions
Task completion time variance	±200%	±20%
Rework due to misunderstanding	30% of tasks	<5% of tasks
Autonomous execution success	40%	95%
Time spent planning vs doing	20/80	40/60

Requirements

Knowledge:

• Understanding of SMART goal framework
• Familiarity with project file structure
• Awareness of verification commands (pytest, mypy, etc.)

Tools:

• None (skill is language/framework agnostic)

Environment:

• Works with any task management system
• Compatible with todo.md, Jira, GitHub Issues, etc.

Red Flags to Avoid

Red Flags Checklist:

• ❌ Task description fits on one line but has no metadata
• ❌ No file path mentioned
• ❌ Action verb is generic ("fix", "update", "add")
• ❌ No verification command provided
• ❌ Success criteria is subjective ("make it better")
• ❌ Task mixes multiple concerns (AND, THEN, ALSO in description)
• ❌ Task would take >30 minutes but isn't decomposed
• ❌ Contains forbidden vague patterns (Section 6)
• ❌ Missing inputs/outputs specification for data operations
• ❌ No link to parent task/ADR/issue for context

Common Mistakes:

1. Too granular - "Add import statement" is usually too small, combine with actual work
2. Too high-level - "Implement authentication" needs 10+ subtasks
3. Technology assumption - "Add React component" when framework not decided
4. Implicit dependencies - "Write tests" assumes code exists, make dependency explicit

Notes

• This skill is framework-agnostic - Works for any programming language or project type
• Precision scales with task complexity - Simple tasks need less metadata than complex ones
• Context determines precision level - Solo developer vs distributed team changes requirements
• Tasks are living documents - Update tasks when requirements change, don't let them drift
• Autonomous execution is the goal - If a task requires synchronous communication, it's not precise enough