learn-together

┌─────────────────────────────────────────────────────────────────┐
│  /question-me          vs           /learn-together             │
├─────────────────────────────────────────────────────────────────┤
│  User has answers      ←→          Neither has all answers      │
│  I extract knowledge   ←→          We explore together          │
│  Interrogation mode    ←→          Research & teaching mode     │
│  "What do YOU want?"   ←→          "Here's what I found..."     │
│  Output: refined spec  ←→          Output: decision doc + plan  │
└─────────────────────────────────────────────────────────────────┘

┌─────────────┐    request    ┌─────────────┐    query    ┌─────────────┐
│   Client    │──────────────▶│   Server    │────────────▶│  Database   │
│  (Browser)  │◀──────────────│   (API)     │◀────────────│  (MongoDB)  │
└─────────────┘    response   └─────────────┘    data     └─────────────┘
        │                            │
        │         WebSocket          │
        └────────────────────────────┘
              (real-time updates)

## [Topic/Decision Point]

### What This Is
[2-3 sentence plain-English explanation]

### Why It Matters For You
[Connect to their specific context/goals]

### Options

| Option | Pros | Cons | Best When |
|--------|------|------|-----------|
| A      | ...  | ...  | ...       |
| B      | ...  | ...  | ...       |

### My Recommendation
[Clear recommendation with reasoning, but acknowledge tradeoffs]

### ⚠️ Common Mistakes & Gotchas
[What 80% of beginners get wrong — save them the pain]

### Want to Go Deeper?
[Optional: links to docs, or offer to explain more]

### ⚠️ Common Mistakes & Gotchas

**Mistake #1: [What they do wrong]**

💡 **Why this trips people up**: [explanation of the mental model error]

---

**Mistake #2: [Another common error]**
...

### ⚠️ Common Mistakes & Gotchas

**Mistake #1: Missing dependency array = infinite loop**
```jsx
❌ This runs forever (re-renders → effect → state change → re-render):
useEffect(() => {
  setCount(count + 1);
}); // No dependency array!

✅ Run only on mount:
useEffect(() => {
  setCount(c => c + 1);
}, []); // Empty array = run once

❌ This runs every render (objects create new reference each time):
useEffect(() => {
  fetch(`/api/user/${config.id}`);
}, [config]); // config = { id: 1 } but NEW object each render!

✅ Depend on primitives, or memoize:
useEffect(() => {
  fetch(`/api/user/${config.id}`);
}, [config.id]); // Primitive string/number = stable

❌ count is always 0 in the callback:
useEffect(() => {
  const id = setInterval(() => {
    console.log(count); // Always logs initial value!
  }, 1000);
  return () => clearInterval(id);
}, []); // count not in deps = stale closure

✅ Use ref or add dependency:
const countRef = useRef(count);
useEffect(() => { countRef.current = count; }, [count]);

#### Sourcing Mistakes

When researching a topic, specifically search for:
- "[topic] common mistakes"
- "[topic] gotchas"
- "[topic] beginners errors"
- Stack Overflow: highest voted questions tagged [topic]

**The goal**: Make the user say "Oh! I would have definitely done that wrong"

## Phase 3: Interactive Decision-Making

After presenting information, use `AskUserQuestion` to:
- Confirm understanding before moving on
- Let them choose between options
- Surface their constraints that affect the decision

### Pace Checking (Prevent Mid-Flow Interruptions)

Before presenting multi-choice questions, pause to ask if any concepts need clarification. Users exploring unfamiliar topics may have questions that don't fit the presented options.

**Pattern:**

**When user responds with a question instead of selecting an option:**
- Treat this as a signal to pause and teach that concept
- Answer their question fully with diagrams/analogies as needed
- Then re-present the decision question (don't assume they remember the options)

**Why this matters:** Users in learning mode often don't know what they don't know. A question that seems tangential to you might be blocking their understanding. Create space for these questions before forcing a choice.

**Question Style:**

**NOT interrogation style:**

## Phase 4: Build Understanding Progressively

Structure the session in layers:

Don't jump to implementation details before foundations are clear.
Check understanding at each layer before proceeding.

## Phase 5: Synthesis

When the learning session reaches a natural conclusion, generate:

```markdown
# [Topic] - Learning Summary & Decision Doc

## What We Covered
[Brief overview of topics explored]

## Key Concepts
[Core ideas they need to remember]

## Decisions Made
| Decision | Choice | Reasoning |
|----------|--------|-----------|
| ...      | ...    | ...       |

## Implementation Plan
[If applicable — concrete next steps]

## Resources for Later
- [Official docs link]
- [Tutorial they can reference]
- [Community/support channels]

## Open Questions
[Things to revisit as they learn more]

## Quick Reference
[Cheatsheet of key info they'll need during implementation]

[User's spec.md: "how to use google analytics, new to GA4, using firebase + magic link auth"]

Claude: "Let me research GA4 best practices for your setup and break this down..."

[WebSearch for GA4 + Firebase integration, event taxonomy best practices]

Claude: "Here's what I found:

## GA4 Core Concepts

**Real-world analogy**: Think of GA4 like a security camera system for your app.
Instead of recording continuous video (old pageview-based GA), it's motion-activated —
it only captures specific "events" when something interesting happens.

### How Data Flows

┌──────────────┐    events     ┌──────────────┐    process    ┌──────────────┐
│  Your App    │──────────────▶│   Firebase   │──────────────▶│     GA4      │
│  (frontend)  │               │   (bridge)   │               │  (dashboard) │
└──────────────┘               └──────────────┘               └──────────────┘
       │                              │                              │
       │ logEvent('sign_up')          │ auto-batches                 │ reports
       │ logEvent('purchase')         │ every 60 sec                 │ funnels
       └──────────────────────────────┴──────────────────────────────┘

### ⚠️ Common Mistakes & Gotchas (READ FIRST!)

**Mistake #1: Tracking everything**
❌ logEvent('button_clicked') on every button
✅ Track meaningful user actions that answer business questions

💡 Why this trips people up: More data feels safer. But noise drowns signal.

**Mistake #2: Forgetting the 24-48 hour delay**
❌ "I added tracking yesterday, why is the dashboard empty?!"
✅ GA4 is NOT real-time. Use DebugView for testing.

💡 Why this trips people up: Old Universal Analytics was near real-time.

**Mistake #3: Not setting up conversions**
❌ Tracking 50 events but no "conversion" markers
✅ Mark 3-5 events as conversions (sign_up, purchase, etc.)

💡 Why this trips people up: GA4 doesn't guess which events matter to YOUR business.

---

### Event Categories For Your App

1. **Lifecycle Events** (auto-tracked by Firebase)
   - first_open, session_start, app_remove

2. **Authentication Events** (you'll implement)
   - sign_up, login, magic_link_sent, magic_link_clicked

3. **Engagement Events** (depends on your core feature)
   - [I'd need to know what users DO in your app]

### Magic Link Auth Event Timeline

User clicks "Sign in"          User clicks email link           Session starts
        │                              │                              │
        ▼                              ▼                              ▼
┌───────────────┐             ┌───────────────┐             ┌───────────────┐
│ magic_link_   │────email───▶│ magic_link_   │────auth────▶│    login      │
│   _requested  │   sent      │   _clicked    │  verified   │               │
└───────────────┘             └───────────────┘             └───────────────┘
        │                              │                              │
   Track: email                  Track: time                   Track: method
   (hashed)                      since request                 = 'magic_link'

Which part should we dive into first?"

[User chooses, session continues with progressive depth]