Atomic Tasks

Atomic Tasks Skill

This skill provides patterns for creating well-structured, atomic tasks that follow the principle: One task = One commit = One thing.

Core Principles

Atomicity

Each task should be:

• Self-contained: Completes a single logical unit of work
• Independently verifiable: Can be tested/verified in isolation
• Safely committable: Results in a working codebase if committed alone
• Rollback-friendly: Can be reverted without breaking other tasks

Task Properties

Task Sizing Guidelines

Too Large (Split It)

• Touches more than 5 files
• Has more than 5 actions
• Takes more than 30 minutes
• Multiple logical concerns mixed together
• Commit message needs "and" multiple times

Too Small (Combine It)

• Only renames a variable
• Single-line change with no logic
• Cannot be meaningfully verified
• Would create noise in git history

Just Right

• 1-3 files modified typically
• 2-5 clear actions
• Single responsibility
• Clear verification steps
• Concise commit message

Task Status Flow

pending ─── in_progress ─── completed
    │            │
    │            └── blocked (external dependency)
    │
    └── skipped (no longer needed)

Dependency Management

Dependency Types

1. Code Dependency: Task B needs code from Task A 2. Schema Dependency: Task B needs database changes from Task A 3. Config Dependency: Task B needs configuration from Task A 4. Knowledge Dependency: Task B needs information gathered in Task A

Dependency Rules

• No circular dependencies allowed
• Minimize dependency chains (prefer parallelizable tasks)
• Document why dependency exists
• Re-evaluate if blocked task is taking too long

Verification Patterns

Automated Verification

<verify>
  <step>npm test -- [test-pattern]</step>
  <step>npm run build</step>
  <step>npm run lint -- [file]</step>
</verify>

Manual Verification

<verify>
  <step>Visually confirm [UI element] appears</step>
  <step>Manual test: [test scenario]</step>
</verify>

Combined Verification

<verify>
  <step>npm test -- auth</step>
  <step>Manual: Login with test credentials</step>
  <step>Check logs for errors</step>
</verify>

Done Criteria Patterns

Feature Tasks

<done>
  <criterion>Feature is accessible via [entry point]</criterion>
  <criterion>Tests cover happy path and error cases</criterion>
  <criterion>No new lint warnings introduced</criterion>
</done>

Bug Fix Tasks

<done>
  <criterion>Original issue no longer reproduces</criterion>
  <criterion>Regression test added</criterion>
  <criterion>Related functionality still works</criterion>
</done>

Refactor Tasks

<done>
  <criterion>All existing tests still pass</criterion>
  <criterion>No functional changes detected</criterion>
  <criterion>[Quality metric] improved</criterion>
</done>

Commit Message Convention

Follow Conventional Commits:

<type>(<scope>): <description>

[optional body]

[optional footer]

Types

Examples

feat(auth): add login endpoint
fix(cart): prevent negative quantities
refactor(api): extract validation middleware
test(user): add registration edge cases

Task Decomposition Process

1. Start with the goal: What is the end result? 2. Identify major components: What distinct pieces are needed? 3. Check for dependencies: What order must they happen in? 4. Size each component: Is each one atomic? 5. Split if needed: Break large components down 6. Define verification: How will we know each is done? 7. Write commit messages: Force clarity of purpose

Anti-Patterns to Avoid

The Kitchen Sink

<!-- BAD: Too many unrelated changes -->
<task id="TASK-001">
  <name>Add auth and update styling and fix bugs</name>
  ...
</task>

The Invisible Task

<!-- BAD: No way to verify -->
<task id="TASK-001">
  <name>Improve code quality</name>
  <verify></verify>
</task>

The Dependency Chain

<!-- BAD: Long sequential chain -->
TASK-001 → TASK-002 → TASK-003 → TASK-004 → TASK-005

The Vague Action

<!-- BAD: Not actionable -->
<actions>
  <action>Make it better</action>
  <action>Fix the thing</action>
</actions>

Integration with Workflow

PLAN Phase

• Create all tasks using XML format
• Verify cross-plan consistency
• Establish execution order

EXECUTE Phase

• Process one task at a time
• Mark status transitions
• Run verification after each
• Commit on success

VERIFY Phase

• Review all completed tasks
• Run integration verification
• Confirm done criteria met

See xml-format.md for complete XML schema reference.

XML Task Format Reference

Complete Task Schema

<task id="TASK-XXX" status="pending|in_progress|completed|blocked|skipped">
  <!-- Required: Short, descriptive name (5-10 words) -->
  <name>Implement user authentication service</name>

  <!-- Required: What this task accomplishes (1-2 sentences) -->
  <description>
    Create the core authentication service with login and logout methods,
    integrated with the existing user repository.
  </description>

  <!-- Optional: Task IDs this depends on (comma-separated) -->
  <depends>TASK-001, TASK-002</depends>

  <!-- Required: Files this task will create or modify -->
  <files>
    <file action="create">src/services/AuthService.ts</file>
    <file action="modify">src/config/services.ts</file>
    <file action="delete">src/legacy/OldAuth.ts</file>
  </files>

  <!-- Required: Specific actions to take (2-5 typically) -->
  <actions>
    <action>Create AuthService class with login() and logout() methods</action>
    <action>Inject UserRepository dependency via constructor</action>
    <action>Add AuthService to dependency injection container</action>
    <action>Remove legacy authentication code</action>
  </actions>

  <!-- Required: How to verify task completion -->
  <verify>
    <step>npm test -- AuthService</step>
    <step>npm run build</step>
    <step>Manual: Verify login works with test credentials</step>
  </verify>

  <!-- Required: Criteria that define "done" -->
  <done>
    <criterion>AuthService class exists at specified path</criterion>
    <criterion>Login succeeds with valid credentials</criterion>
    <criterion>Login fails gracefully with invalid credentials</criterion>
    <criterion>Logout clears session state</criterion>
  </done>

  <!-- Required: Conventional commit message for this task -->
  <commit>feat(auth): add AuthService with login/logout functionality</commit>
</task>

Element Reference

<task> (Root Element)

<name>

Short, descriptive task name. Should:

• Be 5-10 words
• Start with a verb (Implement, Add, Create, Fix, Update, Remove)
• Be specific enough to distinguish from other tasks
• Not include technical jargon unless necessary

Examples:

<name>Add user registration endpoint</name>
<name>Fix cart total calculation bug</name>
<name>Create email notification service</name>

<description>

Fuller explanation of what the task accomplishes. Should:

• Be 1-2 sentences
• Explain the "what" and optionally "why"
• Provide context for implementer
• Not duplicate the name

Examples:

<description>
  Implement the /api/users/register endpoint that accepts email and password,
  validates input, and creates a new user account with proper password hashing.
</description>

<depends>

Comma-separated list of task IDs that must complete before this task. Should:

• Only include direct dependencies
• Not create circular references
• Be re-evaluated if dependency is blocked

Examples:

<depends>TASK-001</depends>
<depends>TASK-001, TASK-002, TASK-003</depends>

<files>

Container for file operations. Each <file> element specifies:

Examples:

<files>
  <file action="create">src/services/NewService.ts</file>
  <file action="modify">src/index.ts</file>
  <file action="delete">src/deprecated/OldService.ts</file>
  <file action="rename" from="src/temp.ts">src/final.ts</file>
</files>

<actions>

Container for specific steps. Each <action> should be:

• A single, concrete step
• Written as an imperative statement
• Achievable without ambiguity
• Listed in execution order

Examples:

<actions>
  <action>Create UserService class in src/services/</action>
  <action>Add getById method that queries the database</action>
  <action>Add create method that validates and inserts user</action>
  <action>Export UserService from services/index.ts</action>
</actions>

<verify>

Container for verification steps. Each <step> can be:

• A command to run
• A manual check to perform
• A condition to confirm

Command Steps:

<verify>
  <step>npm test -- UserService.test.ts</step>
  <step>npm run build</step>
  <step>npm run lint -- src/services/UserService.ts</step>
</verify>

Manual Steps:

<verify>
  <step>Manual: Navigate to /users page and confirm list renders</step>
  <step>Manual: Create a user and verify it appears in the list</step>
</verify>

Mixed Steps:

<verify>
  <step>npm test -- integration</step>
  <step>Manual: Verify no console errors in browser</step>
  <step>curl http://localhost:3000/health returns 200</step>
</verify>

<done>

Container for completion criteria. Each <criterion> should be:

• Observable/measurable
• Binary (either met or not)
• Specific to this task

Examples:

<done>
  <criterion>UserService class exists and exports correctly</criterion>
  <criterion>All unit tests pass</criterion>
  <criterion>TypeScript compiles without errors</criterion>
  <criterion>API endpoint returns expected response format</criterion>
</done>

<commit>

Conventional commit message for this task. Format:

<type>(<scope>): <description>

Examples:

<commit>feat(user): add UserService with CRUD operations</commit>
<commit>fix(auth): handle expired token gracefully</commit>
<commit>refactor(api): extract validation into middleware</commit>
<commit>test(cart): add edge case coverage for empty cart</commit>

Task Templates by Type

Feature Task

<task id="TASK-XXX" status="pending">
  <name>Add [feature name]</name>
  <description>Implement [feature] that allows [user action]</description>
  <files>
    <file action="create">[new file path]</file>
    <file action="modify">[integration point]</file>
  </files>
  <actions>
    <action>Create [component/service/class]</action>
    <action>Implement [core functionality]</action>
    <action>Add [integration/wiring]</action>
    <action>Write tests for [scenarios]</action>
  </actions>
  <verify>
    <step>[test command]</step>
    <step>[build command]</step>
  </verify>
  <done>
    <criterion>Feature is accessible via [entry point]</criterion>
    <criterion>Tests cover [scenarios]</criterion>
  </done>
  <commit>feat([scope]): add [feature description]</commit>
</task>

Bug Fix Task

<task id="TASK-XXX" status="pending">
  <name>Fix [bug description]</name>
  <description>Resolve issue where [problem description]</description>
  <files>
    <file action="modify">[file with bug]</file>
  </files>
  <actions>
    <action>Identify root cause in [location]</action>
    <action>Apply fix by [correction]</action>
    <action>Add regression test</action>
  </actions>
  <verify>
    <step>[test command]</step>
    <step>Manual: Verify [original issue] no longer occurs</step>
  </verify>
  <done>
    <criterion>Original issue no longer reproduces</criterion>
    <criterion>Regression test passes</criterion>
    <criterion>No new issues introduced</criterion>
  </done>
  <commit>fix([scope]): [bug fix description]</commit>
</task>

Refactor Task

<task id="TASK-XXX" status="pending">
  <name>Refactor [component] to [improvement]</name>
  <description>Restructure [code area] to improve [quality attribute]</description>
  <files>
    <file action="modify">[files to refactor]</file>
  </files>
  <actions>
    <action>Extract [method/class/module]</action>
    <action>Rename [identifiers] for clarity</action>
    <action>Update [dependent code]</action>
  </actions>
  <verify>
    <step>[full test suite]</step>
    <step>[build command]</step>
  </verify>
  <done>
    <criterion>All existing tests still pass</criterion>
    <criterion>No functional behavior changed</criterion>
    <criterion>[Quality improvement] achieved</criterion>
  </done>
  <commit>refactor([scope]): [refactoring description]</commit>
</task>

Parsing Tasks

Extract Tasks from ITEM-XXX.md

// Regex pattern to extract tasks
const taskPattern = /<task[^>]*>([\s\S]*?)<\/task>/g;

// Extract status
const statusPattern = /status="([^"]+)"/;

// Extract ID
const idPattern = /id="([^"]+)"/;

Update Task Status

// Find task by ID and update status
const updateStatus = (planContent, taskId, newStatus) => {
  const pattern = new RegExp(
    `(<task[^>]*id="${taskId}"[^>]*status=")([^"]+)(")`,
    'g'
  );
  return planContent.replace(pattern, `$1${newStatus}$3`);
};