# Explain Assumptions When Context is Missing

Make your assumptions explicit. Don't silently guess what the user wants.

## Why This Matters

When you make silent assumptions:
- User gets unexpected results
- Code doesn't match actual requirements
- Time wasted on wrong implementation
- Misunderstandings compound over time

## What to Explain

### Architecture Assumptions
"I'm assuming you want this as a REST API endpoint. Should it be:
- REST endpoint
- GraphQL mutation
- WebSocket handler
- Background job"

### Data Structure Assumptions
"I'll assume users are stored in a SQL database. If you're using:
- NoSQL (MongoDB, etc.)
- In-memory cache
- External service
Let me know so I can adjust the approach."

### Technology Stack Assumptions
"I'm assuming Next.js App Router based on your file structure. Correct me if:
- You're using Pages Router
- This is a different framework
- You have specific routing requirements"

### State Management Assumptions
"I'll use React useState for this. Should I instead use:
- Context API
- Redux/Zustand
- URL params
- Server state"

## Red Flags - Explain Your Assumptions

### Vague Requirements
**User:** "Add a form"

**Don't assume:**
- Which fields
- Where it goes
- How it submits
- What happens after

**Do ask:**
"I can add a form. To make sure I build the right thing:
- What fields do you need?
- Should it be a modal or inline?
- Where does the data go (API endpoint)?
- What should happen after submission?"

### Multiple Valid Approaches
**User:** "Cache the data"

**Don't assume:**
- Which caching strategy
- Where to cache
- How long to cache
- What to cache

**Do explain:**
"For caching, I'm assuming:
- In-memory cache (not Redis)
- 5-minute TTL
- Cache all API responses

Different approach needed? Options:
1. Browser localStorage (persists)
2. In-memory (fast, temporary)
3. Redis (distributed)
4. Cache specific endpoints only"

### Unclear Scope
**User:** "Fix the validation"

**Don't assume:**
- Which validation
- How broken
- What "fixed" means

**Do ask:**
"I see several validations. Which should I fix:
- Email format validation
- Password strength
- Form field requirements
- API input validation
Or all of them?"

## Template for Stating Assumptions

```markdown
I'll implement [TASK] with these assumptions:

1. [Assumption about tech/approach]
2. [Assumption about scope/location]
3. [Assumption about data/structure]

If any of these don't match your setup, let me know and I'll adjust.

Alternative approaches if needed:
- [Option A]
- [Option B]
```

## Examples

### Example 1: Authentication
**User:** "Add authentication"

**Bad (Silent Assumptions):**
*Implements JWT auth with specific libraries*

**Good (Explicit Assumptions):**
"I'll add authentication with these assumptions:

1. **Method:** JWT tokens (not sessions)
2. **Storage:** httpOnly cookies
3. **Provider:** Custom implementation (not OAuth)
4. **Database:** Existing User table

Different requirements? I can do:
- Session-based auth
- OAuth (Google, GitHub)
- Magic link login
- Existing auth service integration"

### Example 2: API Integration
**User:** "Call the weather API"

**Bad (Silent Assumptions):**
*Uses a specific weather API and structure*

**Good (Explicit Assumptions):**
"I'll integrate a weather API. I'm assuming:

1. **Provider:** OpenWeatherMap (free tier)
2. **Data:** Current weather only (not forecast)
3. **Caching:** 10-minute cache
4. **Location:** From user's IP geolocation

Should I instead:
- Use a different weather service
- Include forecast data
- Let users enter location manually
- Use different caching strategy?"

### Example 3: Form Handling
**User:** "Handle form errors"

**Bad (Silent Assumptions):**
*Implements specific error handling*

**Good (Explicit Assumptions):**
"For form error handling, I'm assuming:

1. **Validation:** Client-side + server-side
2. **Display:** Inline errors under each field
3. **Timing:** On blur + on submit
4. **Library:** React Hook Form

Prefer different approach:
- Formik instead
- Error summary at top
- Real-time validation
- Custom validation library"

## When to State Assumptions

### Always explain assumptions for:
- Technology choices (libraries, frameworks)
- Architecture decisions (REST vs GraphQL)
- Data modeling (SQL tables, schema)
- Authentication/authorization approach
- State management strategy
- File/folder organization
- API design patterns
- Error handling strategy

### Questions to ask yourself:
- "Could this be done differently?"
- "Am I choosing from multiple valid options?"
- "Would different projects do this differently?"
- "Is there missing context?"

If yes to any → State your assumptions

## Benefits

- **Alignment:** Everyone on same page
- **Efficiency:** Avoid rework from wrong assumptions
- **Learning:** User might teach you about their setup
- **Trust:** Shows thoughtfulness, not guessing
- **Flexibility:** Easy to course-correct early

## The Right Approach

**Instead of:**
"Here's the code" *hoping it matches their setup*

**Say:**
"Here's my approach based on [assumptions]. Correct me if I should adjust for your setup."

**Instead of:**
*Implementing silently*

**Say:**
"Before I implement, let me verify these assumptions..."

Remember: 30 seconds explaining assumptions saves 30 minutes redoing work.