# Dynasty Live Action Plan

Status: Draft 0.1  
Last updated: 2026-07-28
Related spec: `docs/dynasty-live-spec.md`

Implementation progress as of 2026-07-28:

- Phases 0-3 implemented.
- Phase 4 implemented and validated; see `docs/screenshot-ocr-validation.md`.
- Phase 5 implemented and validated; see `docs/ai-foundation-validation.md`.
- Phases 6-7 not started.

## 1. Objective

Build Dynasty Live as a local-first desktop app that imports a College Football 27 dynasty save, parses weekly facts, displays them in a team-centered portal, then layers screenshots, AI-generated content, and interactive press conferences on top.

The first real target is a working vertical slice:

> Open the desktop app, click `Import Latest`, and see the LSU 66-0 Auburn game parsed correctly in a Game Center page.

## 2. Build Strategy

Work in narrow slices that preserve a factual foundation:

1. App shell.
2. Read-only parser.
3. SQLite persistence.
4. Factual portal.
5. Screenshot OCR.
6. AI generation.
7. Interactive press conferences.

Do not start with AI. AI should consume verified facts, not compensate for missing parser behavior.

## 3. Technical Baseline

Recommended stack:

- Desktop shell: Electron.
- UI: React + Vite + TypeScript.
- Parser/runtime: Node.js.
- Save parser: `madden-franchise` with CFB27 schema support.
- Database: SQLite.
- OCR: local OCR pipeline with crop templates.
- AI: OpenAI-compatible provider abstraction using base URL, API key, and model.

Rules:

- Read-only save handling.
- Copy every imported save into an app archive before parsing.
- Resolve save tables by unique ID and references, not hardcoded table IDs.
- Keep source table/row metadata for debugging.
- Organize imported saves internally by detected dynasty.
- MVP UI shows one active dynasty only.

## 4. Phase 0: Project Scaffold

Goal: Create the app skeleton and development workflow.

Tasks:

- Create package structure.
- Add Electron main process.
- Add React/Vite renderer.
- Add shared TypeScript types package.
- Add parser package placeholder.
- Add database package placeholder.
- Add basic app navigation:
  - Home.
  - Scores.
  - Game Center placeholder.
  - Import.
  - AI.
  - Settings.
- Add config storage for:
  - Save folder.
  - Primary save file.
  - Active dynasty ID.

Deliverables:

- Desktop app launches locally.
- Import screen can select and remember save folder/save file.
- UI can navigate between placeholder screens.

Acceptance checks:

- `npm install` works.
- `npm run dev` launches Electron.
- Config persists after restart.

## 5. Phase 1: Parser Proof

Goal: Read one dynasty save and normalize core football data.

Tasks:

- Wire `madden-franchise` into parser package.
- Load configured save file read-only.
- Compute source file hash.
- Detect dynasty identity.
- Parse:
  - Calendar/stage/week.
  - User team.
  - Teams.
  - Conferences.
  - Coaches.
  - Players/rosters.
  - Schedule/results.
  - Team game stats.
  - Player game stats.
- Include subclass stat tables when resolving player game stats.
- Mark major games:
  - Ranked matchups.
  - Rivalry games.
- Emit normalized JSON.

Known validation case:

- LSU 66, Auburn 0.
- Houston Anderson: 508 passing yards, 7 TD.
- Julian Reese II: 9 catches, 283 yards, 4 TD.
- LSU team stats should match the parsed save facts.

Deliverables:

- CLI or dev endpoint that parses the configured save.
- Normalized JSON output for latest snapshot.
- Validation notes for the LSU/Auburn sample.

Acceptance checks:

- Parser opens the save without writing it.
- Parser identifies current season/week.
- Parser finds the LSU/Auburn game and expected core stats.
- Parser stores source table/row metadata in debug output.

## 6. Phase 2: SQLite Persistence

Goal: Store parsed facts and imports reliably.

Tasks:

- Add SQLite setup and migrations.
- Create initial tables:
  - `dynasty`
  - `snapshot`
  - `team`
  - `coach`
  - `player`
  - `game`
  - `game_team_stats`
  - `game_player_stats`
  - `player_game_grade`
- Add archive directory structure.
- On import:
  - Compute hash.
  - Detect duplicate imports.
  - Copy save to archive.
  - Organize internally by detected dynasty.
  - Parse facts.
  - Upsert normalized rows.
- Add latest snapshot query.

Deliverables:

- `Import Latest` stores parsed facts in SQLite.
- Re-importing the same unchanged file is deduped.
- Save archive contains copied snapshots.

Acceptance checks:

- Import succeeds from configured save file.
- Database contains teams, players, games, team stats, player stats.
- Duplicate import does not create duplicate snapshot data.
- Latest snapshot can be loaded after app restart.

## 7. Phase 3: Factual Portal

Goal: Display parsed facts before adding OCR or AI.

Tasks:

- Build Home screen as a user-team fan-site news layout.
- Add factual feed placeholders.
- Add `Across the Landscape` sidebar:
  - National stories placeholder.
  - Conference stories placeholder.
  - Rival stories placeholder.
  - Upcoming opponent stories placeholder.
- Build Scoreboard.
- Build Game Center:
  - Final score.
  - Quarter scores.
  - Team stats.
  - Player leaders.
  - Box score.
  - Player grades placeholder.
  - Highlights placeholder.
  - Social reaction placeholder.
  - Press conference entry placeholder.
- Add deterministic player grade calculation.
- Pass grade facts to placeholder AI explanation field later.

Deliverables:

- App displays latest imported snapshot.
- User can open the LSU/Auburn Game Center.
- Game Center shows parsed facts accurately.

Acceptance checks:

- No AI required to view factual pages.
- LSU/Auburn page shows correct score and key stats.
- Home screen prioritizes user team.
- `Across the Landscape` exists as a sidebar/section.

## 8. Phase 4: Screenshot Archive and OCR

Goal: Add screenshot ingestion, permanent storage, OCR extraction, and correction.

Tasks:

- Add screenshot upload.
- Store raw screenshots permanently.
- Create `screenshot` table.
- Build screenshot type detection for:
  - Highlight list.
  - Passing stats.
  - Rushing stats.
  - Receiving stats.
- Add crop templates for known screenshot layouts.
- Run OCR on cropped regions.
- Parse OCR output into structured rows.
- Match screenshots to parsed games.
- Dedupe overlapping highlight rows.
- Create `play_highlight` table.
- Build OCR Review screen:
  - Source screenshot.
  - Extracted rows.
  - Edit/correct fields.
  - Approve for generation.

Deliverables:

- User can upload sample screenshots.
- Highlight rows and stat rows are extracted.
- User can correct OCR results.
- Corrected highlights appear in Game Center.

Acceptance checks:

- Raw screenshots remain available after restart.
- OCR result stores raw and corrected values.
- Duplicate highlight rows are not shown twice.
- AI generation can distinguish save-only vs screenshot-enriched mode.

## 9. Phase 5: AI Foundation

Goal: Generate factual content from parsed data and corrected OCR.

Tasks:

- Add AI provider settings:
  - Base URL.
  - API key.
  - Model.
  - Test connection.
- Add content-type-specific provider/model settings.
- Add prompt pack tables:
  - Serious Newsroom.
  - Balanced.
  - Chaotic Social.
- Prompt edits create custom copies.
- Add prompt editor.
- Store:
  - Prompt template.
  - Full rendered prompt text.
  - Source evidence.
  - Model/provider used.
  - Generated output.
- Add recurring personality generation from prompt-pack archetypes.
- Add initial content generation:
  - Long-form game article.
  - Short recap.
  - Headline.
  - Social posts.
  - Player grade explanation.
- Include coach relationship state in relevant prompts.
- Publish generated artifacts immediately.
- Add edit/regenerate controls.

Deliverables:

- AI settings screen works.
- Prompt packs seed editable templates and personalities.
- Game Center can generate article, recap, headline, social posts.
- Generated content stores full prompt and source evidence.

Acceptance checks:

- Generated content does not invent unsupported facts.
- Save-only prompt path avoids play-by-play claims.
- Screenshot-enriched prompt path uses corrected highlights.
- Editing/regenerating content works.

## 10. Phase 6: Interactive Press Conferences

Goal: Add press conferences as an interactive stateful system.

Tasks:

- Add tables:
  - `coach_relationship_state`
  - `coach_relationship_event`
  - `press_conference`
  - `press_conference_question`
  - `press_conference_response_option`
  - `press_conference_answer`
- Initialize relationship scores at `50`.
- Use visible `0-100` score with tiers:
  - Hostile.
  - Cold.
  - Neutral.
  - Warm.
  - Loyal.
- Generate press conference after every user-team game.
- Use 3 questions for normal games.
- Use 5 questions for ranked matchups and rivalry games.
- Select question types from a pool.
- Generate situational response options.
- Show broad effect indicators and exact deltas before selection.
- Support custom typed responses.
- Grade custom responses immediately.
- Explain relationship changes.
- Generate press conference recap and public response.
- Feed relationship state into future prompts.

Deliverables:

- Game Center can start a press conference.
- User answers generated reporter questions.
- Relationship scores update.
- Recap and public response are generated.
- Later AI content reflects relationship state.

Acceptance checks:

- Scores start at `50`.
- Effects are visible before selecting generated responses.
- Custom response grading happens immediately.
- Relationship events are stored with explanations.
- Recap references actual answers and game context.

## 11. Phase 7: Polish and Hardening

Goal: Make the MVP coherent and reliable enough for repeated weekly use.

Tasks:

- Improve error handling around save parsing.
- Add import status and parser diagnostics.
- Add empty/loading/error states.
- Add settings backup/export.
- Add database backup/export.
- Improve OCR correction ergonomics.
- Add prompt restore defaults.
- Add UI polish.
- Add smoke tests for parser and database.
- Add fixtures for sample save/screenshot validation.

Deliverables:

- MVP can survive repeated weekly imports.
- User can recover from bad OCR or AI output.
- Parser failures produce actionable diagnostics.

Acceptance checks:

- Import, restart, reload latest snapshot works.
- Corrupt/unsupported file gives a clear error.
- Prompt defaults can be restored.
- Sample validation stays stable.

## 12. Out of Scope for MVP

- Save writing.
- RTG parsing.
- Recruiting.
- Coaching carousel.
- Rumor/speculation content.
- Multiple active dynasty switching in the UI.
- Hosted/cloud product decisions.
- Storyline pinning/follow controls.
- Screenshot deletion UI.

## 13. First Work Session Checklist

Use this as the first concrete implementation session:

1. Create Electron + React/Vite + TypeScript scaffold.
2. Add basic navigation and placeholder screens.
3. Add config persistence for save folder and primary save file.
4. Add parser package with a read-only save open test.
5. Add `Import Latest` button wired to parser proof output.
6. Validate that the configured save can be opened without writing.
7. Print calendar, user team, and first set of games to dev output.

Stop condition for session 1:

- The desktop app launches.
- A save file can be selected.
- `Import Latest` opens the save read-only and prints basic dynasty facts.

## 14. Development Notes

Known local reference docs:

- `docs/research/01-save-file-format.md`
- `docs/research/02-table-inventory.md`
- `docs/research/03-coaches-and-carousel.md`
- `docs/research/04-recruiting.md`
- `docs/research/05-calendar-and-stages.md`
- `docs/research/06-tool-design-implications.md`
- `research/notes-save-diff.md`

Known constraints:

- Do not write to CFB27 saves.
- Save file size is not a reliable change signal.
- Some player stats live in subclass game stat tables.
- Screenshots are necessary for realistic play-by-play texture.
- OCR needs correction UI.