PLAN.md

# ADHS Study Agent — Projektplan

## Kontext

Samuel will raus aus der Claude-Code-Optimierung und sein Orchestrierungs-Wissen auf ein echtes Problem anwenden: **Ein AI-Agent der Studenten mit ADHS durch ihr Semester navigiert.** Er IST die Zielgruppe — 569 ChatGPT-Conversations + 232 Claude-Sessions dokumentieren das Problem aus erster Hand.

**Ansatz:** Research First — aber Samuel selbst als User-Interview-Partner, nicht externe Recherche.

---

## Phase 1: User Research (Samuel als Zielgruppe)

Aus dem Portrait + Lernreise destillierte Pain Points:

1. **"Lernplaene die nie halten"** — starre Plaene scheitern an ADHS. Der Plan muss sich anpassen, nicht der Mensch.
2. **"10 von 150 Berichtsheften"** — Routinedokumentation ohne Feedback ist unmoeglich. Braucht Micro-Nudges.
3. **"8 Stunden vor Pruefung"** — Zeitdruck ist der einzige funktionierende Motivator. Das System muss DAS nutzen, nicht bekaempfen.
4. **"5 Uni-Bewerbungen = unueberwindbar"** — Formalia-Angst. Aufgaben muessen in Micro-Steps zerlegt werden.
5. **Stress-Sweet-Spot Phase 2** — Es gibt ein schmales Fenster (eigene Stimme, produktiv). Davor zu formal, danach Panik.
6. **Duplikat-Sessions** — Jede Session beginnt bei Null weil Gedaechtnis fuer eigene fruehere Gedanken unzuverlaessig ist.
7. **Festivals im Pruefungsmonat** — Das System darf nicht moralisieren, sondern muss damit arbeiten.

**Interview-Ergebnis (5. Maerz 2026):**
Samuel waehlt ALLE 4 Pain Points + ergaenzt 2 kritische:
- **#5 Zu viele Dinge anfangen, nichts beenden** — Novelty Bias, WIP explodiert
- **#6 Dopamin kommt beim Task-BEGINN, nicht beim Complete** — DAS ist der Kern

→ Design-Konsequenz: Jeder Micro-Step muss sich wie ein NEUER Anfang anfuehlen (Dopamin beim Start), aber die Steps sind so klein dass Completion automatisch passiert. Nicht "mach die Aufgabe fertig" sondern "fang diesen 5-Min-Block an". WIP-Limit: max 2 aktive Faecher gleichzeitig.

**Tonalitaet:** Buddy (supportiv, kein Guilt-Tripping, ermutigend)

---

## Phase 2: Feature-Design (nach Interview)

### Core Features (MVP)

**F1: Micro-Starts statt Mega-Tasks** (Pain Points #3, #6)
- Jede Aufgabe wird in 5-Min-Bloecke zerlegt
- Jeder Block ist ein NEUER Anfang mit eigenem Titel und Kontext
- "Oeffne Kapitel 3 und lies die erste Seite" — nicht "Lerne Kapitel 3"
- Dopamin-Trigger: jeder Block ist ein frischer Start (nicht "noch 47 uebrig")
- Visuell: Blocks als einzelne Karten, nicht als Checkliste

**F2: WIP-Limiter** (Pain Point #5)
- Max 2 Faecher gleichzeitig aktiv
- Wenn du ein drittes anfangen willst: Buddy sagt "Hey, du hast noch Mathe und OS offen. Willst du eins davon pausieren?"
- Kein Verbot — sanftes Bewusstmachen
- "Parking Lot" fuer Ideen die du spaeter anfangen willst

**F3: Elastischer Plan** (Pain Points #1, #2)
- Importiert Deadlines (manuell oder iCal)
- Plan passt sich an wenn du ihn ignorierst — kein Guilt, einfach neuer Plan
- Nutzt Zeitdruck als Feature: Plan wird automatisch komprimierter je naeher die Deadline
- "Verschieben" statt "Versagt" — der Buddy-Ton

**F4: Panik-Modus** (Pain Point #2)
- Aktiviert sich bei <48h vor Deadline
- Komprimiert auf das absolute Minimum
- Buddy wird zum Coach: "Du hast 12h. Hier sind die 5 wichtigsten Themen. Eins nach dem anderen."
- Kein Moralisieren, nur Klarheit

**F5: Session-Memory** (Pain Point #4)
- Merkt sich was du letzte Session gelernt/gemacht hast
- Zeigt beim Oeffnen: "Letzte Session: Du warst bei Kapitel 3, Seite 42. Weitermachen?"
- Kein "bei Null anfangen" mehr
- Fortschritt visuell als Karte/Map, nicht als Prozentzahl

### Nice-to-have (v2)
- Stimmungs-Check-In (Phase 1-5 erkennen, Buddy passt Ton an)
- WhatsApp-Reminder (Nudges auf dem Handy)
- Lerngruppen-Matching (andere ADHS-Studenten)
- Pruefungsarchiv (was kam letztes Jahr dran)
- "Novelty Shuffle" — wenn ein Fach langweilig wird, schlaegt Buddy vor fuer 15 Min zu einem anderen zu wechseln (innerhalb WIP-Limit)

---

## Phase 3: Tech-Stack

**Empfehlung: Python + FastAPI + SQLite + htmx**

| Komponente | Wahl | Begruendung |
|---|---|---|
| Backend | FastAPI (Python) | Samuels staerkstes Setup, async, schnell |
| Datenbank | SQLite | Ueberwindet DB-Angst sanft — es ist nur eine Datei. Spaeter Postgres. |
| Frontend | htmx + Jinja2 Templates | Kein Framework lernen, trotzdem reaktive UI. Server-rendered. |
| AI Agent | Claude API (Haiku fuer Micro-Steps, Sonnet fuer Plaene) | Kostenoptimierung eingebaut — Samuels Staerke |
| Auth | Keine (MVP) → spaeter Supabase | Nicht overengineeren am Start |
| Deployment | Fly.io oder Railway | Ein-Klick-Deploy, kostenlose Tier |

**Warum nicht Next.js/Svelte:** Samuel ist Python-First. Ein neues Frontend-Framework ist ein separates Lernprojekt und wuerde den Execution Gap vergroessern. htmx gibt 80% der Interaktivitaet fuer 10% der Komplexitaet.

---

## Phase 4: Implementierung

### Sprint 1 (Woche 1-2): Skeleton
- [ ] Projekt-Setup: `~/Projekte/StudyAgent/`
- [ ] FastAPI + SQLite + htmx Grundgeruest
- [ ] Datenmodell: Semester, Faecher, Deadlines, Lerneinheiten
- [ ] Deadline-CRUD (manuell eintragen)
- [ ] FOR_SMLFLG.md anlegen

### Sprint 2 (Woche 3-4): Agent-Logik
- [ ] Tagesplan-Generator (Claude Haiku)
- [ ] Micro-Step-Zerlegung
- [ ] Adaptiver Replan wenn Steps uebersprungen werden
- [ ] Einfache Session-Memory (letzte 3 Sessions)

### Sprint 3 (Woche 5-6): Panik-Modus + Polish
- [ ] Panik-Modus bei <48h
- [ ] Visueller Fortschritt (Fortschrittsbalken, nicht Zahlen)
- [ ] Deployment auf Fly.io
- [ ] 1 Beta-Tester (Samuel selbst mit echten Pruefungen)

---

## Phase 5: Verifikation

- [ ] Laeuft lokal: `uvicorn main:app --reload`
- [ ] SQLite DB wird erstellt und befuellt
- [ ] Deadline eintragen → Tagesplan generieren → Steps sehen
- [ ] Plan ignorieren → neuer Plan wird generiert (kein Guilt)
- [ ] Panik-Modus triggert bei Deadline < 48h
- [ ] Deployment funktioniert (oeffne URL im Browser)

---

## Deliverable

1. [x] User-Interview mit Samuel — erledigt, 6 Pain Points + Buddy-Ton
2. [ ] Plan permanent speichern: `~/Projekte/StudyAgent/PLAN.md`
3. [ ] Visuelles HTML: Projekt-Overview als `~/.agent/diagrams/adhs-study-agent.html`
4. [ ] Projekt-Setup starten (Sprint 1)