planning

Planning with Trekker

Before starting any multi-step task, break it down in Trekker FIRST.

This ensures:

• Work is tracked and resumable
• Dependencies are explicit
• Progress is visible across sessions
• Context survives resets

When to Plan in Trekker

Use this workflow when:

• Task has 3+ steps
• Work spans multiple files
• Implementation requires specific order
• Task might take more than one session
• User asks for a feature/fix that isn't trivial

Planning Workflow

Step 1: Search for Related Work

# ALWAYS search first - previous work may exist trekker search "<what you're about to do>"

Step 2: Create Epic (if substantial)

For features with multiple tasks:

trekker epic create -t "Feature: User Authentication" \
  -d "JWT-based auth with login, registration, and session management"

Step 3: Break Down into Tasks

Create atomic, completable tasks:

# Each task should be independently completable
trekker task create -t "Create User model with email/password" \
  -d "Define User schema with bcrypt password hashing" \
  -e EPIC-1 -p 1

trekker task create -t "Implement login endpoint" \
  -d "POST /api/auth/login - validate credentials, return JWT" \
  -e EPIC-1 -p 1

trekker task create -t "Implement registration endpoint" \
  -d "POST /api/auth/register - create user, hash password" \
  -e EPIC-1 -p 1

Step 4: Set Dependencies

Make execution order explicit:

# Login depends on User model
trekker dep add TREK-2 TREK-1

# Registration depends on User model
trekker dep add TREK-3 TREK-1

Step 5: Mirror to TodoWrite

After Trekker is set up, create matching todos:

TaskCreate for each Trekker task
Set blockedBy relationships matching Trekker deps

Task Quality Rules

Good Task Titles

BAD:  "Fix bug"
GOOD: "Fix null pointer in UserService.getById when user not found"

BAD:  "Add feature"
GOOD: "Add email validation to registration form"

Good Descriptions

Every task MUST answer:

• What: Specific action to take
• Why: Problem being solved
• Where: Files/components involved

Execution Order

1. Check dependencies: trekker dep list TREK-n
2. Verify blockers resolved
3. Start task: trekker task update TREK-n -s in_progress
4. Update TodoWrite status
5. Do the work
6. Add checkpoint comments during work
7. Complete with summary

Before Context Reset

If context is about to reset:

trekker comment add TREK-n -a "claude" -c "Checkpoint:
Done: [what's complete]
Next: [what's remaining]
Files: [modified files]
State: [any important context]"

Example: Planning a Feature

User: "Add user authentication to the API"

# 1. Search first trekker search "authentication"
trekker search "login"

# 2. Create epic
trekker epic create -t "User Authentication System" \
  -d "JWT-based auth with login, registration, password reset"

# 3. Create tasks
trekker task create -t "Design auth database schema" \
  -d "Users table, refresh tokens, password reset tokens" -e EPIC-1 -p 0

trekker task create -t "Implement User model" \
  -d "Drizzle schema with bcrypt password hashing" -e EPIC-1 -p 1

trekker task create -t "Create auth middleware" \
  -d "JWT verification middleware for protected routes" -e EPIC-1 -p 1

trekker task create -t "Implement login endpoint" \
  -d "POST /auth/login - credential validation, JWT generation" -e EPIC-1 -p 1

trekker task create -t "Implement registration endpoint" \
  -d "POST /auth/register - user creation with validation" -e EPIC-1 -p 1

trekker task create -t "Add auth tests" \
  -d "Unit tests for auth service, integration tests for endpoints" -e EPIC-1 -p 2

# 4. Set dependencies
trekker dep add TREK-2 TREK-1   # Model depends on schema
trekker dep add TREK-3 TREK-2   # Middleware depends on model
trekker dep add TREK-4 TREK-2   # Login depends on model
trekker dep add TREK-5 TREK-2   # Register depends on model
trekker dep add TREK-6 TREK-4   # Tests depend on login
trekker dep add TREK-6 TREK-5   # Tests depend on register

# 5. Mirror to TodoWrite with same structure

Key Principle

Plan in Trekker FIRST, then execute. Never start coding multi-step work without a Trekker plan.