thoughts/plans/YYYY-MM-DD-descriptive-name.md

# 1. LOCATE — find where relevant files live (don't read contents, just map locations)
Agent(subagent_type="Explore", prompt="Find all files related to [feature/domain].
  Group by: routes, use-cases/business logic, components, DB schema, tests.
  Report file paths and directory structure only, don't read contents.")

# 2. PATTERNS — find similar implementations to model after (read code, extract complete examples)
Agent(subagent_type="Explore", prompt="Find similar implementations to [what we're building].
  Read the code thoroughly. Extract complete working examples with imports.
  Note file organization, naming conventions, error handling approach.")

# 3. ANALYZE — trace how an existing related feature works end-to-end
Agent(subagent_type="Explore", prompt="Analyze how [related feature] is implemented.
  Trace the data flow from entry point to DB/API.
  Map key functions, their inputs/outputs, and error handling paths.")

**Package manager:** pnpm/npm/yarn
**Build tool:** turbo/nx/none
**Language:** TypeScript (strict mode?)
**Runtime:** Node.js/Bun/Deno
**Framework:** Fastify/Express/Hono
**Database:** Postgres + Drizzle/Prisma
**Testing:** Vitest/Jest
**Patterns to follow:** [reference existing implementations]

# [Title] - Implementation Plan

## Overview
[1-2 sentences: what we're building and why]

## Current State
[What exists now, what's missing, relevant code locations]

## Desired End State
[What should work when done, how to verify — include example commands/usage]

## Out of Scope
[Explicitly list what we're NOT doing — prevents scope creep]

## Implementation Approach
[High-level strategy and reasoning]

---

## Phase 1: [Descriptive Name]

### What This Accomplishes
[Summary of this phase's goal]

### Changes

**File**: `path/to/file.ext`

```[language]
// Complete code to add or modify
// Not snippets — full implementation

// Complete code

# Step-by-step commands to verify everything works
command1
command2

directory/
├── file1.ext           # Purpose
├── file2.ext           # Purpose
└── subdirectory/
    └── file3.ext       # Purpose

## Phase Guidelines

**Good phases:**
- Each phase is independently verifiable
- Earlier phases don't break existing functionality
- Later phases build on earlier ones
- Can pause between phases if needed

**Phase sizing:**
- Small enough to verify quickly
- Large enough to be meaningful
- Typically 1-3 files per phase
- Each phase should have clear verification steps

**Code in phases:**
- Include COMPLETE code, not snippets
- Show the full file content or the full function
- Never use "..." or "// rest of code"
- Someone should be able to copy-paste and have it work

## What Makes a Good Plan

**Good** (specific, actionable):
- File paths exist or clearly describe where to create
- Code snippets show COMPLETE implementation
- Verification steps are concrete commands
- Expected outputs documented

**Bad** (vague, hand-wavy):
- "Update the relevant components"
- "Add appropriate error handling"
- "Test thoroughly"
- Code snippets with "..." placeholders

## Example

**Input ticket**: "Add database package with Drizzle ORM"

**Output plan** (abbreviated):

```markdown
# Database Package - Implementation Plan

## Overview
Create `packages/db` with Drizzle ORM for PostgreSQL, following monorepo patterns from jp-partner-platform.

## Current State
- Monorepo exists with Fastify API + Temporal worker
- Postgres in docker-compose (port 5462)
- No database package yet

## Desired End State
```bash
# Package builds successfully
pnpm --filter=@repo/db build

# Migrations work
pnpm --filter=@repo/db generate
pnpm --filter=@repo/db migrate

# Types available in other packages
import { users } from "@repo/db/schema"

{
  "name": "@repo/db",
  "type": "module",
  "exports": {
    ".": { "default": "./dist/index.js" },
    "./schema": { "default": "./dist/schema/index.js" }
  },
  "scripts": {
    "build": "tsc",
    "generate": "drizzle-kit generate",
    "migrate": "drizzle-kit migrate"
  },
  "dependencies": {
    "drizzle-orm": "^0.44.0",
    "postgres": "^3.4.7"
  },
  "devDependencies": {
    "drizzle-kit": "^0.31.0"
  }
}

import { defineConfig } from "drizzle-kit"

export default defineConfig({
  schema: "./src/schema/index.ts",
  out: "./drizzle",
  dialect: "postgresql",
  dbCredentials: {
    url: process.env.DATABASE_URL ?? "postgresql://postgres:postgres@localhost:5462/mydb",
  },
})

## Handoffs

- After plan approval, use `/dev-skills:implement-change` to execute phase by phase
- The plan in `thoughts/plans/` serves as the source of truth during implementation