# Unfamiliar — v2 Vision

> **Status:** Exploration notes for post-MVP direction
> **Generated:** 2026-03-22
> **Updated:** 2026-03-22 (customer and TUI revision)

---

## Target Customer

### The Pivot

**Old positioning:** "Onboarding tool for new hires"
- Customer: Engineering managers? HR? The new hire themselves?
- Purchase decision: Employer?
- Usage frequency: Once per job (2-3 years)
- Competition: Employer-provided onboarding, AI chat, "just figure it out"
- Success metric: "Time to productivity"

**New positioning:** "Learn any codebase like a game"
- Customer: The developer themselves
- Purchase decision: Personal choice
- Usage frequency: Every time they're curious about a codebase (monthly?)
- Competition: Nothing does this well for personal learning
- Success metric: "Did I enjoy understanding this?"

### Who This Customer Actually Is

| Attribute | What It Means |
|-----------|---------------|
| **ADHD or gamification-aficionado** | Needs external structure, time boxes, dopamine hits |
| **Self-directed learner** | No manager expecting outcomes — doing it for themselves |
| **AI-assisted builder** | Has "vibe coded" projects they need to retroactively understand |
| **Open source curious** | Wants to contribute but intimidated by unfamiliar codebases |
| **Pattern collector** | Learns by seeing how different projects solve similar problems |
| **Hobbyist mindset** | Values enjoyment over efficiency |

### The Real Use Cases

1. **"I built this with AI and now I need to understand what I made"**
   - Growing category of developer
   - Real problem, no good solution
   - They already have the code, they need the map

2. **"I want to contribute to this open source project"**
   - First step is always "understand the codebase"
   - Self-directed, no deadline, gamification helps
   - Could become a recommended tool in CONTRIBUTING.md

3. **"I want to learn how [popular library] actually works"**
   - Pattern collecting
   - Reading source code for education
   - Gamified = more likely to stick with it

4. **"I'm coming back to my own project after 6 months"**
   - Self-forgetting
   - Need to re-learn what you built
   - Personal codebase archaeology

### What This Changes

| Aspect | Old (Enterprise Onboarding) | New (Personal Learning) |
|--------|---------------------------|------------------------|
| **Tone** | Professional, efficient | Playful, inviting |
| **Success** | "Productive faster" | "Enjoyed learning" |
| **Marketing** | B2B, LinkedIn, devrel | Open source community, Twitter/X, word of mouth |
| **Distribution** | Sales? Never. GitHub stars, Hacker News, Reddit | ✓ |
| **Pricing** | Free forever, maybe donations | Same — this was never about money |
| **Features** | Team campaigns (v3) | Less important |
| **Features** | Case file, progress tracking | MORE important — personal artifact |

### Positioning Statement

> **Unfamiliar is for developers who want to enjoy learning a new codebase.**
>
> Whether you're exploring an open source project, making sense of your AI-generated code, or revisiting your own work after time away — Unfamiliar turns codebase exploration into a structured, gamified investigation. Track your progress, verify your learning, and build a case file you can actually use.

### Why This Positioning Is Better

1. **More honest** — Built by someone who wanted it, for people like them
2. **Better frequency** — "Every time I'm curious" vs "once per job"
3. **Natural distribution** — Open source community, not enterprise sales
4. **Forgiving audience** — Hobbyists want to enjoy it, not optimize it
5. **Actually reachable** — A tweet, a HN post, a Reddit thread. No sales team needed.

---

## The Value Proposition Problem

### The Real Competition

There are two distinct problems:

1. **"I have a question about this codebase"** → AI chat solves this perfectly
2. **"I need to understand this codebase but I'm overwhelmed and can't make myself start"** → Nothing solves this well

Unfamiliar is not competing with AI chat. It's competing with:
- Aimlessly clicking through files
- Getting distracted after 15 minutes
- Reading code but not retaining anything
- Giving up because "I'll never understand all of this"

### What Actually Differentiates This

**Current value prop:** "AI-powered codebase onboarding with gamified missions"

**Better value prop:** "Structured investigation sessions that track your progress, verify your learning, and build a reference you can actually use."

**One-sentence answer to "Why not just ask Claude?":**

> "Because Claude can answer your questions, but it can't tell you where to start, track what you've learned, or tell you when you're done."

---

## The Five Pillars of Value

### 1. Solving the "I don't know where to start" paralysis

AI chat requires you to know what to ask. An overwhelmed dev doesn't know what they don't know.

The tool says: "Start here. This file. This question. 15 minutes."

That's not a mission — that's **removing the decision burden**. For ADHD brains, "I'll figure out where to start" is often where the whole thing dies.

### 2. Creating a bounded commitment

"Understand this codebase" is an unbounded, overwhelming task.
"Look at auth.py lines 44-89 for 15 minutes" is a bounded commitment anyone can start.

The value isn't the mission content — it's **the container**. The time box, the specific scope, the clear endpoint.

### 3. Progress tracking over time

AI chat has no memory across sessions. The tool has a campaign.

Day 1: "I did 3 missions in Architecture."
Day 5: "I've covered 4 of 7 categories."
Day 10: "Case closed."

That narrative arc — the sense of journey — is something no chat interface provides. It's the difference between "I asked some questions" and "I completed an investigation."

### 4. Active verification, not passive reading

Reading code is passive. Answering a question about what you just read is active.

The comprehension question after a mission isn't a nice-to-have — it's **the mechanism that makes learning actually happen**. Without it, users click "done" and forget everything 10 minutes later.

### 5. The case file as lasting artifact

The problem with "I read the codebase" is there's nothing to show for it. No artifact. No reference.

The case file changes the equation:
- "I spent 3 hours" → "I have a document I can use"
- "I think I understand" → "Here's what I learned, organized"
- "What if I forget?" → "It's in my case file"

The value isn't just the learning — it's **the permanence** of what they produce.

---

## TUI vs IDE Extension

### Why the TUI Is the Right Choice

Running the terminal inside the IDE is already a great workflow. There's no context switching. The extension idea was over-indexed.

**What an extension actually buys you:**
- Slightly smoother "click to open file at line" (the TUI can already output `file:line` format that most terminals make clickable)

**What the TUI already does:**
- Works in any IDE (VS Code, JetBrains, Vim, Emacs, etc.)
- Single codebase to maintain
- Terminal-in-IDE workflow is natural
- Progress tracking ✓
- Can add timeboxing ✓
- Can add comprehension questions ✓
- Can add case file generation ✓

**Extension downsides:**
- Per-IDE development (VS Code, JetBrains, etc.)
- Doesn't help with team features (those need external DB anyway)
- Maintenance burden multiplies

**Conclusion:** The TUI is the product. IDE extensions are a v3 "nice to have" at best.

---

## Feature Priorities for v2

| Priority | Feature | Why It Matters |
|----------|---------|----------------|
| 1 | **Timeboxing in TUI** | Timer on active mission, session structure. External time structure for ADHD brains. |
| 2 | **Clickable file:line output** | `path/to/file.py:44` format — most terminals support cmd+click. Removes the last bit of friction. |
| 3 | **Comprehension questions** | Gives gamification teeth, ensures actual learning instead of click-to-complete gaming. |
| 4 | **Case file auto-generation** | Creates lasting value from the work. Each mission completion prompts "What's one thing you learned?" → organized by category. |
| 5 | **"I'm stuck" hints** | Reduces abandonment when things get hard. Generates mission-specific hints, suggests simpler prerequisites, breaks missions into smaller pieces. |
| 6 | **Session pomodoro** | "Start a 25-minute investigation session" with break reminders and mini-reviews. |
| 7 | **Team campaigns** (v3) | Social accountability, shared knowledge. Requires server architecture. Same TUI client, just pointing at shared DB. |
| 8 | **IDE extensions** (v3+) | Nice to have. Only marginally better than TUI, not worth the maintenance burden until core experience is solid. |

---

## ADHD-Specific Value

The tool works for ADHD developers because it addresses specific failure modes:

| Failure Mode | How The Tool Helps |
|--------------|-------------------|
| Can't start (executive dysfunction) | Removes decision burden — "start here, 15 minutes, done" |
| Loses focus during cognitively expensive tasks | Time-boxing, clear endpoints, dopamine hits |
| Overwhelmed by scope | Bounded commitments, visible progress |
| Forgets what was learned | Active recall, case file externalization |
| Needs external accountability | Progress tracking, "case closed" state |
| Dopamine-seeking | Gamification with real stakes (comprehension verification) |

---

## The Reframe

**MVP proves:** Mission generation works. The analysis pipeline produces useful investigation prompts.

**v2 delivers:** An actual *experience* — structured sessions, verified learning, lasting artifacts.

The question isn't "how do we make better missions?" It's "how do we turn missions into a system that actually helps people learn?"

---

## Open Questions

1. **Comprehension verification complexity** — How do we generate good questions without adding massive LLM overhead? Part of mission generation, or a separate pass?

2. **Case file format** — Markdown in campaign directory? Structured data that renders to markdown? Integration with external note-taking tools?

3. **Timeboxing UI** — Inline timer in mission view? Separate "start session" command? How does it interact with mission completion?

4. **Team features scope** — What's the minimum viable "shared campaign"? Central server + Postgres? Or simpler sync mechanism?

---

## Next Steps After MVP

1. Ship MVP, get feedback from real users
2. Add timeboxing to TUI — timer on active mission, session start/end flow
3. Make file references clickable — `file:line` output format
4. Design comprehension question system — likely needs to be part of mission generation, not a separate pass
5. Build case file generation into mission completion flow
6. Re-evaluate priorities based on real user feedback
