Before generating planning docs, a few quick checks:

1. **Have you built a prototype or POC for this project?** (yes/no)
   - If no: "I recommend building a small spike first to validate key assumptions (especially for new frameworks). Should I help you prototype first, or proceed with planning?"

2. **Any complex setup workflows or gotchas discovered?** (describe or skip)
   - Examples: Database binding order, auth factory patterns, build configuration
   - If described: "I'll create CRITICAL_WORKFLOWS.md to document these."

3. **Tech stack familiarity:** (expert/comfortable/learning)
   - If learning: "I'll add extra time buffer (+30%) for learning curve in estimates."

I'll help structure this project. A few questions to optimize the planning:

1. **Authentication**: Do users need accounts, or is this a public tool?
   - If accounts: Social auth (Google/GitHub)? Roles/permissions?

2. **Data Model**: You mentioned [entities]. Any relationships I should know about?
   - One-to-many? Many-to-many? Hierarchical?

3. **Key Features**: Which of these apply?
   - Real-time updates (websockets/Durable Objects)
   - File uploads (images, documents, etc)
   - Email notifications
   - Payment processing
   - AI-powered features

4. **Scope**: Is this an MVP or full-featured app?
   - MVP: Core features only, can iterate
   - Full: Complete feature set from start

5. **Timeline**: Any constraints? (helps with phase sizing)

⚠️ Phase 4 "Complete User Management" is too large (12 files, 8-10 hours).

Suggested split:
- Phase 4a: User CRUD API (5 files, 4 hours)
- Phase 4b: User Profile UI (6 files, 5 hours)

undefined

undefined

undefined

undefined

undefined

{
  "token": "string"
}

{
  "error": "Human-readable message",
  "code": "ERROR_CODE",
  "details": {} // optional
}

undefined

undefined

┌─────────────────┐
│   Browser       │
└────────┬────────┘
         │
         ↓ HTTPS
┌─────────────────────────────────────┐
│  Cloudflare Worker                  │
│  ┌──────────────┐  ┌──────────────┐│
│  │ Static Assets│  │  API Routes  ││
│  │ (Vite build) │  │    (Hono)    ││
│  └──────────────┘  └───────┬──────┘│
└─────────────────────────────┼───────┘
                              │
            ┌─────────────────┼─────────────────┐
            ↓                 ↓                 ↓
      ┌──────────┐      ┌──────────┐    ┌──────────┐
      │    D1    │      │    R2    │    │  Clerk   │
      │ (Database)│     │(Storage) │    │  (Auth)  │
      └──────────┘      └──────────┘    └──────────┘

undefined

undefined

undefined

undefined

undefined

undefined

undefined

undefined

undefined

undefined

---

undefined

**Key principles**:
- List files in order of importance (entry points first)
- Distinguish new files vs modifications to existing files
- Estimate line counts for new files (helps with effort estimation)
- Show clear dependency graph (what imports what)
- Note which files are "used by" other parts (impact analysis)

undefined

C->>W: POST /api/tasks
W->>A: authenticateUser()
A->>W: user object
W->>V: validateSchema(createTaskSchema)
V->>W: validated data
W->>D: INSERT INTO tasks
D->>W: task record
W->>C: 201 + task JSON

**Example for UI Phase**:
```markdown

**Mermaid Diagram Types**:
- **Sequence diagrams** (`sequenceDiagram`): API calls, auth flows, webhooks
- **Flowcharts** (`flowchart TB/LR`): Component logic, decision trees
- **Architecture diagrams** (`graph TD`): System components, service boundaries
- **ER diagrams** (`erDiagram`): Database relationships (if not in DATABASE_SCHEMA.md)

undefined

**Why this matters**:
- Claude knows exactly what packages to import
- Environment setup is clear before starting
- Breaking changes to dependencies are predictable

undefined

**What to document**:
- Security concerns (auth, validation, ownership)
- Performance issues (pagination, caching, query optimization)
- Data integrity patterns (soft deletes, cascades, constraints)
- Edge cases (empty states, invalid input, race conditions)
- Framework-specific quirks (Cloudflare Workers limitations, Vite build issues)

undefined

undefined

undefined

**In SESSION.md** (during phase):
```markdown

**Benefits**:
- Claude knows exactly where to look (file + line number)
- No grepping needed to find relevant code
- Context switching is faster (fewer files to read)

User: "Add task endpoints"
Claude: [Reads 5-8 files via Glob/Grep to understand structure]
Claude: [Writes code in wrong location]
User: "That should be in routes/tasks.ts, not api/tasks.ts"
Claude: [Reads more files, rewrites code]

User: "Add task endpoints"
Claude: [Reads IMPLEMENTATION_PHASES.md file map]
Claude: [Writes code in correct location on first try]

User: [Describes project]
↓
Skill: "I'll help structure this. A few questions..."
      [Ask 3-5 targeted questions]
↓
User: [Answers]
↓
Skill: "Great! I'll generate:
       - IMPLEMENTATION_PHASES.md
       Should I also create DATABASE_SCHEMA.md? [Y/n]"
↓
User: [Confirms]
↓
Skill: ⚡ [Generates all confirmed docs immediately - this step is key!]
       "Planning docs created in /docs:
       - IMPLEMENTATION_PHASES.md (8 phases, ~15 hours)
       - DATABASE_SCHEMA.md (4 tables)

       Review these docs and let me know if any phases need adjustment.
       When ready, we'll create SESSION.md and start Phase 1."

I've structured your [Project Name] into [N] phases. Here's the planning documentation:

---

---