Atomic Tasks

1. Concept Overview & Systemic Problem

In classical development, vague tasks ("Implement authorization", "Rewrite the search module") are a primary source of delays and rework. In the era of AI agent involvement, the cost of poor decomposition has increased exponentially.

When an engineer gives an agent a high-level vague instruction, the agent makes assumptions about dozens of undefined details. As a result, a monolithic diff spanning 40 files is generated, mixing layouts, database schemas, and business rules. Verifying such a diff is practically impossible: the engineer experiences cognitive overload, clicks "Accept", and a week later faces unsolvable conflicts.

Atomic Tasks is an engineering discipline for structuring work based on indivisibility:

• Each subtask focuses on one change in behavior or structure.
• It has clearly defined input parameters and expected output invariants.
• It can be fully implemented, tested, and committed separately from the rest of the system.

Chaotic Monolith (Agent Failure):
[Requirement: "Build me an online store"] ---> [LLM generates a mess across 30 files with stubs]

Atomic Decomposition (Controlled Success):
[Requirement: "Order Processing"]
   |
   +---> Task 1: Create Drizzle schema for Order table + migration (Check: db:push)
   |
   +---> Task 2: Write pure function calculateTotal(items, discount) (Check: 5 unit tests)
   |
   +---> Task 3: Implement POST /api/orders with Zod validation (Check: curl / API test)
   |
   +---> Task 4: Create UI form for order processing (Check: component in browser)

2. Architectural Taxonomy & Mental Model

Task Granularity Spectrum:

1. Macro Level (System Feature / Epic):
   • Business goal (e.g., "Support multilingual site"). Not suitable for direct feeding to the agent chat as a single command.
2. Atomic Module (Feature Slice / Component):
   • Vertical slice of functionality (e.g., "Routing locales through middleware").
3. Atomic Action (Atomic Micro-Task):
   • A specific step modifying one layer: "Create a translation dictionary for the 404 page in JSON format and add strict typing for keywords."
   • Execution time: 2–5 minutes.
   • Number of modified lines: up to 50–100 lines.

3. Technical Pipeline & Internal Mechanics

Template for Engineering Atomic Task (TASK_SPEC.md)

### Task: Create a Repository for Storing Session Tokens

**File Context:**
- Target file: `src/lib/auth/session-store.ts`
- Test file: `src/lib/auth/__tests__/session-store.test.ts`
- Reference contract: `src/lib/auth/types.ts`

**Requirements:**
1. Implement the `RedisSessionStore` class that implements the `SessionStore` interface.
2. The method `saveSession(token, data, ttlSeconds)` must set a key with TTL using the Redis command `SETEX`.
3. The method `getSession(token)` must return a deserialized object or `null` if the key is absent.

**Definition of Done:**
- The command `npx vitest run src/lib/auth/__tests__/session-store.test.ts` returns 100% successful tests.
- No type errors: `npx tsc --noEmit` passes with 0 errors.

Pipeline for Executing an Atomic Step:

1. The engineer formulates TASK_SPEC with clear context and test.
2. The agent reads ONLY the specified 2-3 files (clean context window, zero hallucinations).
3. The agent writes the implementation.
4. Run the autotest -> green light.
5. The engineer reviews the compact diff (20 lines) in 15 seconds.
6. Git commit: `git commit -m "feat(auth): implement redis session store"`

4. Production Engineering Scenarios

01. Safe Database Migration of 10 Million Rows

Instead of a single complex migration, the team breaks the task into 4 atomic tasks: 1) Add a new column as nullable; 2) Write a background batch synchronization script for 1000 rows; 3) Switch records to the new column; 4) Add NOT NULL constraint and remove the old field. Each stage is verified and deployed separately, eliminating the risk of table locking.

02. Breaking Out of a Creative Deadlock During Debugging

An engineer does not understand why a complex route calculation algorithm returns incorrect results. Instead of fruitlessly examining the entire 1000-line file, they break the algorithm into 5 clean sub-functions and write a separate test for each. An error in rounding fractions is discovered in the 3rd sub-function, and the bug is fixed in 3 minutes.

03. Parallel Subagent Workflow

Thanks to atomicity, the architect can run 3 different model sessions simultaneously: one agent writes an XML parser, another generates PDF reports, and a third designs the database schema. Since their contracts are atomic and do not overlap in shared files, there are no merge conflicts.

5. Pitfalls, Common Mistakes & Security

1. Micro-Task Hell: Excessive decomposition of a task into 50 small steps of 30 seconds each creates bureaucratic friction: the time spent formulating prompts and waiting for responses begins to exceed the time spent writing code. Maintain a healthy scale: 1 atomic task should contain a meaningful step toward problem resolution.
2. Local Optimum Trap: Each atomic task may be executed perfectly at its level, but modules may not integrate if a shared interface contract (Contract-First Design) was not established initially.
3. Accumulation of Uncommitted Junk: If git commit is not performed after each atomic task, after 5 iterations the working tree turns into chaos with hundreds of unclear changes, and the benefits of atomicity are completely lost.