Codewalkers/docs/archive/task-granularity.md

Task Granularity Standards

A task must be specific enough for execution without interpretation. Vague tasks cause agents to guess, leading to inconsistent results and rework.

The Granularity Test

Ask: Can an agent execute this task without making assumptions?

If the answer requires "it depends" or "probably means", the task is too vague.

---

Comparison Table

Too Vague	Just Right
"Add authentication"	"Add JWT auth with refresh rotation using jose library, store in httpOnly cookie, 15min access / 7day refresh"
"Create the API"	"Create POST /api/projects accepting {name, description}, validates name length 3-50 chars, returns 201 with project object"
"Style the dashboard"	"Add Tailwind classes to Dashboard.tsx: grid layout (3 cols on lg, 1 on mobile), card shadows, hover states on action buttons"
"Handle errors"	"Wrap API calls in try/catch, return {error: string} on 4xx/5xx, show toast via sonner on client"
"Add form validation"	"Add Zod schema to CreateProjectForm: name (3-50 chars, alphanumeric), description (optional, max 500 chars), show inline errors"
"Improve performance"	"Add React.memo to ProjectCard, useMemo for filtered list in Dashboard, lazy load ProjectDetails route"
"Fix the login bug"	"Fix login redirect loop: after successful login in auth.ts:45, redirect to stored returnUrl instead of always '/' "
"Set up the database"	"Create SQLite database at data/cw.db with migrations in db/migrations/, run via 'cw db migrate'"

---

Required Task Components

Every task MUST include:

1. Files

Exact paths that will be created or modified.

files:
  - src/components/Chat.tsx      # create
  - src/hooks/useChat.ts         # create
  - src/api/messages.ts          # modify

2. Action

What to do, what to avoid, and WHY.

action: |
  Create Chat component with:
  - Message list (virtualized for performance)
  - Input field with send button
  - Auto-scroll to bottom on new message

  DO NOT:
  - Implement WebSocket (separate task)
  - Add typing indicators (Phase 2)

  WHY: Core chat UI needed before real-time features

3. Verify

Command or check to prove completion.

verify:
  - command: "npm run typecheck"
    expect: "No type errors"
  - command: "npm run test -- Chat.test.tsx"
    expect: "Tests pass"
  - manual: "Navigate to /chat, see empty message list and input"

4. Done

Measurable acceptance criteria.

done:
  - "Chat component renders without errors"
  - "Input accepts text and clears on submit"
  - "Messages display in chronological order"
  - "Tests cover send and display functionality"

---

Task Types

Type: auto

Agent executes autonomously.

type: auto
files: [src/components/Button.tsx]
action: "Create Button component with primary/secondary variants using Tailwind"
verify: "npm run typecheck && npm run test"
done: "Button renders with correct styles for each variant"

Type: checkpoint:human-verify

Agent completes, human confirms.

type: checkpoint:human-verify
files: [src/pages/Dashboard.tsx]
action: "Implement dashboard layout with project cards"
verify: "Navigate to /dashboard after login"
prompt: "Does the dashboard match the design mockup?"
done: "User confirms layout is correct"

Type: checkpoint:decision

Human makes choice that affects implementation.

type: checkpoint:decision
prompt: "Which chart library should we use?"
options:
  - recharts: "React-native, good for simple charts"
  - d3: "More powerful, steeper learning curve"
  - chart.js: "Lightweight, canvas-based"
affects: "All subsequent charting tasks"

Type: checkpoint:human-action

Unavoidable manual step.

type: checkpoint:human-action
prompt: "Please click the verification link sent to your email"
reason: "Cannot automate email client interaction"
continue_after: "User confirms email verified"

---

Time Estimation

Tasks should fit within context budgets:

Complexity	Context %	Wall Time	Example
Trivial	5-10%	2-5 min	Add a CSS class
Simple	10-20%	5-15 min	Add form field
Medium	20-35%	15-30 min	Create API endpoint
Complex	35-50%	30-60 min	Implement auth flow
Too Large	>50%	-	SPLIT REQUIRED

---

Splitting Large Tasks

When a task exceeds 50% context estimate, decompose:

Before (Too Large)

title: "Implement user authentication"
# This is 3+ hours of work, dozens of decisions

After (Properly Decomposed)

tasks:
  - title: "Create users table with password hash"
    files: [db/migrations/001_users.sql]

  - title: "Add signup endpoint with Zod validation"
    files: [src/api/auth/signup.ts]
    depends_on: [users-table]

  - title: "Add login endpoint with JWT generation"
    files: [src/api/auth/login.ts]
    depends_on: [users-table]

  - title: "Create auth middleware for protected routes"
    files: [src/middleware/auth.ts]
    depends_on: [login-endpoint]

  - title: "Add refresh token rotation"
    files: [src/api/auth/refresh.ts, db/migrations/002_refresh_tokens.sql]
    depends_on: [auth-middleware]

---

Anti-Patterns

Vague Verbs

Bad: "Improve", "Enhance", "Update", "Fix" (without specifics) Good: "Add X", "Change Y to Z", "Remove W"

Missing Constraints

Bad: "Add validation" Good: "Add Zod validation: email format, password 8+ chars with number"

Implied Knowledge

Bad: "Handle the edge cases" Good: "Handle: empty input (show error), network failure (retry 3x), duplicate email (show message)"

Compound Tasks

Bad: "Set up auth and create the user management pages" Good: Two separate tasks with dependency

No Success Criteria

Bad: "Make it work" Good: "Tests pass, no TypeScript errors, manual verification of happy path"

---

Examples by Domain

API Endpoint

title: "Create POST /api/projects endpoint"
files:
  - src/api/projects/create.ts
  - src/api/projects/schema.ts

action: |
  Create endpoint accepting:
  - name: string (3-50 chars, required)
  - description: string (max 500 chars, optional)

  Returns:
  - 201: { id, name, description, createdAt }
  - 400: { error: "validation message" }
  - 401: { error: "Unauthorized" }

  Use Zod for validation, drizzle for DB insert.

verify:
  - "npm run test -- projects.test.ts"
  - "curl -X POST /api/projects -d '{\"name\": \"Test\"}' returns 201"

done:
  - "Endpoint creates project in database"
  - "Validation rejects invalid input with clear messages"
  - "Auth middleware blocks unauthenticated requests"

React Component

title: "Create ProjectCard component"
files:
  - src/components/ProjectCard.tsx
  - src/components/ProjectCard.test.tsx

action: |
  Create card displaying:
  - Project name (truncate at 30 chars)
  - Description preview (2 lines max)
  - Created date (relative: "2 days ago")
  - Status badge (active/archived)

  Props: { project: Project, onClick: () => void }
  Use Tailwind: rounded-lg, shadow-sm, hover:shadow-md

verify:
  - "npm run typecheck"
  - "npm run test -- ProjectCard"
  - "Storybook renders all variants"

done:
  - "Card renders with all project fields"
  - "Truncation works for long names"
  - "Hover state visible"
  - "Click handler fires"

Database Migration

title: "Create projects table"
files:
  - db/migrations/003_projects.sql
  - src/db/schema/projects.ts

action: |
  Create table:
  - id: TEXT PRIMARY KEY (uuid)
  - user_id: TEXT NOT NULL REFERENCES users(id)
  - name: TEXT NOT NULL
  - description: TEXT
  - status: TEXT DEFAULT 'active' CHECK (IN 'active', 'archived')
  - created_at: INTEGER DEFAULT unixepoch()
  - updated_at: INTEGER DEFAULT unixepoch()

  Indexes: user_id, status, created_at DESC

verify:
  - "cw db migrate runs without error"
  - "sqlite3 data/cw.db '.schema projects' shows correct schema"

done:
  - "Migration applies cleanly"
  - "Drizzle schema matches SQL"
  - "Indexes created"

---

Checklist Before Creating Task

• Can an agent execute this without asking questions?
• Are all files listed explicitly?
• Is the action specific (not "improve" or "handle")?
• Is there a concrete verify step?
• Are done criteria measurable?
• Does estimated context fit under 50%?
• Are there no compound actions (split if needed)?