write-atomic-tasks

What this skill does

# Write Atomic Tasks

## Quick Start

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

```markdown
❌ 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 |
|-----------|-------------|---------|
| **S**pecific | What exactly to do | "Add retry logic to `ClaudeAgentClient.query()`" not "Add retry logic" |
| **M**easurable | How to verify completion | "Tests pass, mypy clean" |
| **A**ctionable | Clear first step | "Create file `src/temet_run/agent/retry.py`" |
| **R**eferenced | File paths, functions, classes | "in `agent/client.py:ClaudeAgentClient`" |
| **T**estable | 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

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

**Complete Example:**
```markdown
- [ ] 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:**
```markdown
## 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:**

```markdown
❌ 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):**
```bash
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 q