Task Documentation

The Task Spec Structure

# Task 2.1: User Authentication

## Context
Why this task exists and where it fits in the project.

## Requirements
1. POST /auth/login returns JWT token
2. POST /auth/register creates user, returns JWT
3. POST /auth/logout invalidates token
4. All endpoints handle errors with proper HTTP codes

## Technical Approach
- Use /src/lib/auth.ts for auth logic
- Follow patterns in /src/lib/db.ts
- Store tokens in httpOnly cookies (see ARCHITECTURE.md §Auth)

## Acceptance Criteria
- [ ] Login works with valid credentials
- [ ] Login returns 401 for invalid credentials
- [ ] Register rejects duplicates with 409
- [ ] Unit tests for all auth functions (min 6 tests)
- [ ] Smoke test verified

## Dependencies
- Task 1.3 (database setup) must be complete

What Makes a Spec Good

Numbered requirements — each testable on its own. AI can check them off systematically.

Specific file paths — not "update the auth module" but "update /src/lib/auth.ts." Eliminates ambiguity.

Pattern references — "follow patterns in X" prevents inconsistency. AI won't invent a new pattern when you have one already.

Acceptance criteria — checkboxes. Either done or not. No partial credit confusion.

Explicit test requirements — minimum test count in the spec. AI will skip tests if you don't enforce them.

Generating Specs with Claude

In your Claude Project brainstorming conversation, after scoping is done:

Generate detailed task specs for Sprint 1. Each spec should
include context, numbered requirements, technical approach with
specific file paths, acceptance criteria as checkboxes, and
explicit test requirements. Use our TASK_TEMPLATE.md format.

Review every spec Claude generates. Look for vague requirements ("handle errors properly" → "return 400 with an error JSON body for validation failures"), missing test requirements, and unspecified edge cases.

Sprint Plan Structure

# Sprint 1 Plan

## Goal
User auth, profiles, and basic tool library

## Tasks
| # | Task | Estimate | Dependencies | Status |
|---|------|----------|--------------|--------|
| 1.1 | Database schema setup | 2h | None | ✅ |
| 1.2 | Migrations | 1h | 1.1 | ✅ |
| 1.3 | Auth endpoints | 3h | 1.2 | 🔄 |
| 1.4 | User profiles | 2h | 1.3 | ⬜ |

## Rules
- Max 12 tasks per sprint
- Each task ≤ 4 hours
- All tasks must have acceptance criteria

Task Sizing

• Good task size: 1–4 hours. Specific output. Clear done state.
• Too big: "Build the entire auth system." Split it.
• Too small: "Add one CSS property." Combine with related work.

If a task generates more than 300 lines of code, it was probably too big. Split it next time.

Mid-Task Discoveries

AI discovers something that needs fixing during a task. Options:

1. If it's genuinely required to complete the current task: add to acceptance criteria, note it
2. If it's a separate concern: "Write a task doc and add to the sprint backlog"
3. Never: just go fix it without documenting it

Side quests without documentation are how codebases become unmaintainable.