Writing Effective SIMBL Tasks

Write tasks that Claude Code can execute with ZERO context - even in a fresh session.

Goal

A well-written task contains everything needed to complete it without searching the codebase for context. Future sessions shouldn't need to ask "what did we mean by this?"

Title Formula

Action verb + specific noun + context

Good Titles

• "Add email validation to signup form"
• "Fix null pointer in UserService.getProfile()"
• "Refactor auth middleware to use JWT"
• "Update error messages in checkout flow"
• "Remove deprecated analytics calls"

Bad Titles

• "Fix the bug" (what bug?)
• "Update user stuff" (too vague)
• "Auth" (not actionable)
• "Investigate issue" (no clear outcome)
• "Improvements" (not specific)

Description Structure

1. Context (What Exists Now)

Provide concrete references:

• File paths: src/services/auth.ts
• Function names: validateToken()
• Current behavior: "Returns 500 when token expired"
• Error messages: "TypeError: Cannot read property 'id' of null"

### Context
- File: `src/services/UserService.ts:45`
- Function: `getProfile(userId)`
- Current: Returns 500 on missing user
- Stack trace shows null dereference at line 52

2. Requirement (What Should Change)

Be explicit about:

• Expected behavior: "Return 401 with error message"
• Constraints: "Must be backwards compatible"
• Edge cases to handle: "Null user, expired token, missing permissions"

### Requirement
- Return 404 with `{ error: "user_not_found" }` for missing users
- Keep existing behavior for valid users
- Add null check before accessing user.id

3. Relevant Code Snippets

Paste the specific code that needs changing - don't make Claude search for it:

### Current Code
\`\`\`typescript
// src/services/UserService.ts:45-55
async getProfile(userId: string) {
  const user = await this.repo.findById(userId);
  return {
    id: user.id,  // <-- crashes here when user is null
    name: user.name
  };
}
\`\`\`

Acceptance Criteria

Concrete, testable conditions with checkboxes:

### Acceptance Criteria
- [ ] `getProfile()` returns 404 for non-existent users
- [ ] Response includes `{ error: "user_not_found" }`
- [ ] Existing tests pass
- [ ] New test covers null user case
- [ ] No console errors in browser

Good Criteria

• Specific and verifiable
• Binary (done or not done)
• Testable by running code

Bad Criteria

• "Works correctly" (vague)
• "Handles errors well" (subjective)
• "Is performant" (no metric)

Context Embedding Tips

Paste Error Messages Directly

Error: TypeError: Cannot read property 'id' of null
    at UserService.getProfile (src/services/UserService.ts:52:15)
    at async ProfileController.show (src/controllers/profile.ts:18:22)

Reference Related Work

Related: task-12 (same service), task-8 (similar null handling)
See also: PR #234 where we fixed the same pattern in OrderService

Include External References

Per RFC 7519 section 4.1 - JWT claims must include 'exp'
Following pattern from: https://docs.example.com/auth#tokens

Add File Paths Even If Obvious

Files to modify:
- src/services/UserService.ts (main fix)
- src/services/__tests__/UserService.test.ts (add test)
- src/types/errors.ts (add UserNotFoundError if needed)

Priority Guidelines

Match priority to actual urgency:

Complete Task Example

## task-42 Fix null user crash in getProfile

[p2] [backend] [bug]

### Context
- File: `src/services/UserService.ts:45-55`
- Current: `getProfile()` crashes when user not found
- Error: `TypeError: Cannot read property 'id' of null`
- Reproduces: Call `/api/users/nonexistent-id`

### Current Code
\`\`\`typescript
async getProfile(userId: string) {
  const user = await this.repo.findById(userId);
  return {
    id: user.id,  // crashes when user is null
    name: user.name
  };
}
\`\`\`

### Requirement
Return 404 response instead of crashing. Use existing NotFoundError pattern from OrderService.

### Acceptance Criteria
- [ ] GET /api/users/:id returns 404 for non-existent user
- [ ] Response body: `{ error: "user_not_found", userId: "<id>" }`
- [ ] Existing user tests still pass
- [ ] New test: "returns 404 for missing user"

### Notes
See OrderService.getOrder() for similar pattern.
Related: task-38 (added NotFoundError class)