# Unfamiliar — v1.1 Requirements

> **Status:** Planned — deferred until MVP is complete. These features layer onto the working MVP foundation.

This document contains all features planned for v1.1. They are documented here to:
- Keep MVP requirements focused
- Preserve the detailed thinking done during initial planning
- Ensure the MVP data model and architecture support these additions without structural changes

---

## Overview

v1.1 adds depth and personalization to the MVP core loop. Each feature is additive — none changes the foundation.

**Theme:** "Depth & Personalization"

---

## 1. User Stories

### US-v1.1-1: Mode & Character Selection

**As a** developer starting an investigation, **I want to** choose a campaign mode that matches my goal and a character archetype that matches my preferred focus, **so that** the mission campaign is scoped and weighted appropriately.

**Acceptance criteria:**

- After the briefing, user selects a **mode**:
  - **Onboarding** — "I'm new to this codebase." All seven investigation categories are required for campaign completion. Missions cover orientation (architecture, data flow, entry points, conventions) and quality assessment (debt, testing, security)
  - **Assessment** — "I know this codebase, I need to audit it." Technical Debt, Testing, and Security missions are required for campaign completion. Architecture, Data Flow, Dependencies, and Conventions missions are available but optional — not required for "case closed"
- Then user selects a **character** (operates within the chosen mode):
  - **The Detective** — architecture-focused. "Map the territory," trace how components connect
  - **The Forensic Analyst** — testing/evidence-focused. "Examine the evidence," find gaps in coverage
  - **The Fixer** — debt/improvement-focused. "Where the bodies are buried," identify and prioritize problems
- Character choice weights which mission chains are presented first (~60% from specialty track, ~40% from other categories) within the mode's mission pool
- Character choice does NOT lock the user out of any content — all missions are accessible regardless of character
- In assessment mode, orientation missions are accessible but marked as optional. Completing them contributes to stats but is not required for "case closed"
- **The selection UI explicitly states** what mode and character affect (mode = what's required, character = what's prioritized)
- Film Noir theme is applied to all mission presentation from this point forward

### US-v1.1-2: Staleness Detection

**As a** developer returning to a campaign after the codebase has changed, **I want to** know which missions might be outdated, **so that** I can refresh them and ensure I'm investigating current code.

**Acceptance criteria:**

- Staleness is detected via file content hash comparison at session start
- User sees which missions reference changed files
- User can choose to refresh stale missions (triggers targeted LLM call) or proceed anyway
- Refreshed missions retain prerequisite relationships

### US-v1.1-3: Annotation & Field Report Completion

**As a** developer completing a mission, **I want to** optionally add documentation to the codebase or answer a targeted question, **so that** I reinforce my learning and contribute to the codebase's maintainability.

**Acceptance criteria:**

- **Code annotation:** User adds comments/documentation to the codebase where comments are lacking. The AI provides lightweight feedback if the annotation is misleading or incomplete. Preferred when the code genuinely needs better documentation
- **Field report:** User answers a targeted question about what they investigated (e.g., "What would break if this module were removed?"). The AI provides lightweight feedback on completeness. Preferred as a fallback when the code is already well-documented
- AI feedback is lightweight, not blocking — it may flag issues but does not prevent completion
- Self-report remains available as the zero-token option

---

## 2. Data Model Additions

### New Entities

#### Entry Point

A file or location that serves as a "door into" the codebase. Tracked as structured data so progress can be measured against entry point coverage ("You've traced 4 of 7 entry points").

- file_path
- entry_type — (cli | api_route | event_handler | main | scheduled_task)
- description — what this entry point does

**Relationship:** Module 1──* Entry Point

#### Dependency

An external library, service, or API the codebase relies on. Tracked as structured data so missions can be linked to specific dependencies and coverage measured ("You've investigated 6 of 15 external dependencies").

- name
- version_spec — version declared in manifest (nullable, for unversioned services)
- dep_type — (library | service | api | database)
- manifest_source — which file declared it (requirements.txt, package.json, etc.)
- security_relevant — boolean

**Relationship:** Module *──* Dependency (via Module-Dependency Link)

#### Module-Dependency Link (junction)

Many-to-many relationship between modules and dependencies. A module can use multiple dependencies, and a dependency can be used across multiple modules.

### Entity Changes

#### Campaign

- `mode` field becomes active (onboarding | assessment)
- `character` field becomes active (detective | forensic_analyst | fixer)
- Status gains `ready` state between initialization and mode/character selection

### Relationship Diagram Addition

```
Module   1──* Entry Point
Module   *──* Dependency       (via Module-Dependency Link)
```

---

## 3. Feature Additions

| Feature | What it adds |
|---|---|
| Mode selection | Filters which missions are required for campaign completion. MVP runs onboarding mode only |
| Character selection | Sorts mission presentation order by specialty track (60/40 weighting). MVP uses balanced default order |
| Annotation & field report completion | Two additional completion methods with LLM feedback. Requires LLM feedback subsystem |
| Staleness detection | File hash comparison on session resume, stale mission flagging, targeted LLM refresh |
| TypeScript/JavaScript adapters | Additional language support using the adapter interface built in MVP |
| User-customizable standards | `~/.unfamiliar/standards/` directory with universal and per-language overrides |
| Entry Point & Dependency entities | Promoted from Module descriptions to full entities. Enables entry point and dependency coverage gamification |
| Notebook | `notebook.md` creation in campaign directory with default headings. System references notebook entries in mission context (passive — no active parsing) |
| Plain mode (`--plain`) | Screen-reader-compatible plain text output. Same commands and data, no ANSI/TUI |
| `reconnect` command | Re-link orphaned campaigns when repo path changes |
| Command alias system | Themed aliases alongside canonical commands (e.g., `investigate` for `next`) |
| Mutation testing analysis | Auto-detect mutation reports (mutmut). "Kill the mutant" missions for weak tests. Requires user to have mutation testing configured |

---

## 4. UI/UX Changes

### First Launch Flow (Updated)

1. Codebase analysis runs with a progress indicator (static analysis pass, then LLM pass)
2. Briefing renders in the main content area — plain language, no theme
3. **Character selection** — three options with descriptions, styled as a choice panel
4. **Explicit note** that character affects mission order only
5. Campaign reveal — initial mission chains appear with themed titles and descriptions
6. Transition to the main investigation loop

### Mission Chain Ordering

- ~60% of initial chains align with the character's specialty track
- ~40% from other categories
- All missions remain accessible regardless of character choice

### Completion View (Updated)

- Choose completion method (annotation / field report / self-report)
- If annotation or field report: lightweight AI feedback
- Themed narrative outro connecting what was learned to the bigger picture
- Unlock notification if new missions/chains became available
- Updated progress stats

---

## 5. Business Rule Changes

### Campaign Completion Criteria

**Onboarding mode:**
- Coverage across all seven investigation categories required

**Assessment mode:**
- Technical Debt, Testing, and Security categories required
- Architecture, Data Flow, Dependencies, and Conventions optional (contribute to stats but not "case closed")

### Token Economy

- Annotation and field report completion trigger LLM calls for feedback
- Self-report remains the zero-token option
- Staleness refresh triggers targeted LLM calls for affected missions only

---

## 6. Technical Implementation Notes

### LLM Feedback Subsystem

Required for annotation and field report completion. Must:
- Accept user-submitted content (code comments or written answers)
- Compare against mission context and codebase understanding
- Provide lightweight, non-blocking feedback
- Handle failures gracefully (fallback to self-report if LLM unavailable)

### Entry Point Detection

- MVP uses AST heuristics to detect entry points (`if __name__ == "__main__"`, Flask/FastAPI app instances, CLI entry functions, async event handlers)
- v1.1 promotes these to structured Entry Point entities for gamification

### Module-Dependency Linking

- Parse requirements.txt/pyproject.toml/package.json for dependency declarations
- Use import analysis to link dependencies to modules
- Enable "dependency coverage" stat: dependencies linked to modules with completed missions

---

## 7. Migration from MVP

The MVP data model is designed to support v1.1 without destructive changes:

- `mode` and `character` fields exist in MVP schema (not exposed in UI)
- Entry Point and Dependency are new tables (additive)
- Module-Dependency junction is a new table (additive)
- `ready` status is a new enum value (additive)

Users run `unfamiliar upgrade` to populate new entities via static analysis. No LLM calls, no mission regeneration, no loss of progress.
