Clue-Solver

Clue Solver — Project Overview

For LLM context injection, onboarding, marketing-context reference, and product briefs. Last updated: 2026-03-19 Version: Launch v1.0

App Store Identity

Name: Clue Solver: Detective Notepad
Subtitle: Board Game Tracker & Strategy
Primary category: Games > Board, Puzzle
Secondary category: Utilities
Business model: Paid app at launch. Planned transition to free with in-app purchases to unlock additional editions and features.
Launch editions: Classic Clue and Alfred Hitchcock. Additional editions (Master Detective, Simpsons, and more) and custom edition creation will be unlocked via future IAP.

What It Is

Clue Solver is a native iOS companion app for the classic mystery deduction board game Clue (known internationally as Cluedo). It replaces manual paper note-taking with a real-time deduction engine: you choose the edition, set up the table, record every suggestion or accusation, and let the app continuously deduce what must be true about the hidden envelope and each player’s hand.

The app is designed for a single player sitting at a real table game. It is not a digital board game, not online multiplayer, and not a rules simulator. Its job is to be a fast, polished deduction assistant that helps one player capture information accurately and extract more logic from it than a human notepad ever could.

Important distinction for marketing: This is a companion tool for a physical board game, not a standalone game. All messaging should make this clear to avoid purchase confusion.

Core Product Promise

The product is built around four promises:

Faster setup than a paper sheet: the setup wizard gets a real investigation started in under a minute and preserves entered data when the user goes back to adjust choices.
Smarter deduction than any human notepad: every recorded event updates the solver, resolves ambiguity, calculates probabilities, and explains its reasoning in plain language.
Recoverability when mistakes happen: saved case files, undo, contradiction surfacing, and rebuild-from-history flows make it practical to correct errors mid-game.
A premium Clue-themed experience: the app presents the investigation as a mansion case file with a dark mystery palette, gold accents, and atmospheric feedback — not a sterile spreadsheet.

Who It Is For

Players who already know how Clue works and want help tracking information during a real game at a real table.
Players who dislike dense manual note grids and want automated deduction that goes far beyond what paper can do.
Players who want exact reasoning and “why” explanations, not just guesses.
Competitive players who want probability data and card-ownership intelligence to inform their strategy.
People playing classic-style Clue or Cluedo editions (suspect / weapon / room).

Key Value Propositions (for marketing use)

It solves the mystery for you — not a passive tracker, an active solver that reasons through every turn and tells you what must be true.
Probability on every unknown card — see which cards are most likely in the envelope, backed by exhaustive feasibility analysis.
Plain-language explanations — the Insights tab explains why each deduction was made so you can learn and verify.
Faster than paper, smarter than paper — setup takes under a minute, and the app catches deductions humans routinely miss.
Detective notepad with freehand drawing — a structured grid with tap-to-mark cells plus a freehand drawing layer on top for personal notes, hunches, and table reads.
Save and resume across sessions — pause a game, close the app, come back days later and pick up exactly where you left off.
Catches your mistakes — contradiction detection alerts you when a turn entry conflicts with the evidence so far.

Feature Inventory At A Glance

The shipping app at launch includes:

Home screen with branded presentation, new-case creation, quick resume, saved-case browsing, and settings access.
Multi-step setup wizard for edition choice, player count, seat order, card counts, and the app user’s hand.
Two launch editions: Classic Clue and Alfred Hitchcock.
Investigation dashboard with five tabs: Cards, Players, History, Insights, and Notepad.
Suggestion and accusation recording flow with validation around who could show and when “no one showed” is legal.
Automatic deduction engine with contradiction detection and explanation generation.
Saved-case persistence across launches via SwiftData.
Undo for the last recorded turn, including full solver rebuild.
Visual deduction banners and a solved-case celebration flow.
Detective notepad: structured grid with tap-to-mark cells and a freehand drawing overlay for personal notes on the same surface.
Appearance, sound, and haptics settings.

Capabilities in the codebase but not surfaced at launch:

Additional editions (Master Detective, Simpsons, and 20+ themed editions) — gated for future IAP.
Custom edition creation — gated for future IAP.
ExportManager can generate a plain-text investigation report, but there is no dedicated user-facing export flow yet.
UndoRedoManager supports redo internally, but the current dashboard UI only exposes undo.
ProbabilityHeatMapView exists in code, but the active dashboard uses the Cards and Insights tabs instead.

User-Facing Experience

Home And Case File Management

The home screen is the app’s landing surface and case-file hub.

Home screen features

Animated Clue-branded hero treatment with a shimmering title and themed tagline.
New Investigation entry point that resets setup state and launches the setup wizard.
Last Case File quick-resume button when there is a most-recent active investigation with players configured.
Active Case Files button that opens the saved-investigations list when any saved non-empty cases exist.
Settings entry point in the top-right toolbar.

Saved case file list

The saved-case modal presents persisted investigations from SwiftData.

Tap any saved case to resume it.
Swipe-to-delete support for removing a saved case file.
Status badges show whether the case is Active, Closed, or Solved.
Each row shows:
- edition name
- player count
- suggestion count
- relative last-played timestamp

Case file lifecycle

Exiting an investigation from the dashboard returns the user to home without deleting the case.
Partially abandoned setup attempts are cleaned up if they never got as far as creating players.
Completed and solved cases remain in persistence and can still appear in the saved-case list.

Investigation Setup Wizard

The setup flow is a multi-step wizard that creates the game state before the first suggestion is recorded.

Setup goals

Match the real physical game being played.
Capture the table’s seating order and hand sizes.
Seed the solver with the app user’s known cards.
Preserve entered setup data when the user navigates backward or changes editions, as long as the data still fits the new edition constraints.

Step 1: Edition picker

The edition picker is the first screen in setup.

At launch, shows Classic Clue and Alfred Hitchcock editions.
Uses large edition cards with icon, edition name, and three-category card counts.
Requires a selection before enabling Continue.
Restores the previously selected edition if the user returns to the screen.

Step 2: Player count

The player count screen asks how many detectives are in the game, including the app user.

Available counts are clamped to the selected edition’s supported player range.
Shows a visual representation of the selected count.
Marks the app user as You.
Defaults to the edition minimum if no count has been chosen yet.
Displays the selected edition as a reference chip throughout the rest of setup.

Step 3: Player names

The detective naming screen records seating order clockwise around the table.

One text field per player.
The first seat is the app user.
The first field can be left blank and will resolve to Me.
Other blank names are auto-filled as Player N.
Includes a seat-order reminder that explicitly explains who sits to the user’s left.
Supports clear buttons for populated fields.
Advances field-to-field using the keyboard submit button.

Step 4: Cards per player

The card distribution screen records how many cards each player was dealt.

Calculates the total number of dealable cards from the edition.
Provides an Auto-distribute evenly action for quick setup.
Uses steppers to adjust each player’s hand count.
Validates the total against the edition’s dealable-card count.
Blocks forward navigation until the counts are logically valid.
Shows a live total and error feedback when too many or too few cards are assigned.

Step 5: Your hand

The final setup step records the cards held by the app user.

Displays cards grouped by the active edition’s three category labels.
Uses tap-to-select card buttons.
Enforces selecting exactly the number of cards assigned to the app user in the previous step.
Persists the selection inside the setup draft before finalizing the game.
Initializes players, seeds the app user’s known cards, and bootstraps the deduction engine when the user taps Begin Investigation.

Setup data reconciliation

The setup draft is intentionally resilient.

If the user changes edition, the app keeps the existing player count if it still fits the new edition.
Existing names are preserved wherever possible.
Card counts are adjusted to satisfy the new edition’s total dealt-card count.
Selected hand cards are trimmed only if they are no longer valid or exceed the app user’s new hand size.
This prevents the wizard from feeling fragile when the user backtracks to confirm or correct an earlier choice.

The setup flow uses standard navigation-stack behavior.
The native iOS back button is retained.
Back-button copy is customized per step so the breadcrumb text reflects the previous screen.
The selected edition remains visible as a reference chip after the first step and currently uses the full display name, including year, during setup.

Investigation Workspace

Once setup is complete, the user lands in the main dashboard.

Dashboard shell

The dashboard is the main investigation workspace.

Uses a five-tab TabView.
Shows the edition name and current suggestion count in the navigation bar.
Provides a + action for recording a new suggestion or accusation.
Provides an undo action when there is turn history to undo.
Exposes a menu for exiting the investigation and opening settings.
Presents the solved-case reveal when the envelope is fully determined.

Global feedback inside the dashboard

The dashboard can surface two cross-tab feedback banners above the tab content.

Appears when the engine detects contradictions.
Headline: Impossible Situation Detected.
Expandable details list the specific contradiction reasons.
Intended to help the user catch mistaken turn entry quickly.

Appears when the solver announces a new insight.
Uses the engine’s latest announcement text.
Auto-dismisses after a short delay.
Plays haptic and sound feedback when enabled.
Is intentionally keyed to the latest announcement ID so new insights still announce even if counts happen to match previous states.

Solved-case reveal

When all three envelope cards are known, the dashboard presents a solved-case celebration flow.

The flow is triggered automatically after the third envelope card is found.
It displays the solved suspect, weapon, and room.
It is meant to feel like a mystery reveal rather than a silent state change.

Cards Tab

The Cards tab is the primary “what do we know?” surface.

Envelope summary

At the top of the tab, the app summarizes the envelope.

Displays three slots labeled with the active edition’s category names (e.g., “Suspects”, “Weapons”, “Rooms” for Classic Clue).
Shows solved cards directly when known.
Visually tracks how many of the three envelope categories are solved.

Category sections

Cards are grouped by the edition’s three categories (e.g., Suspects, Weapons, Rooms).

Each section behaves differently depending on solve state.

While unsolved, the section header reports counts like possible vs. eliminated.
Once solved, the header switches to a solved presentation such as ✉ solved: Mrs. Peacock.
The solved state keeps the gold-accent styling and removes the need to keep emphasizing possible/eliminated counts for that category.

Card rows

Each card row reflects the engine’s latest understanding.

In envelope state
Held by player state
Unknown state

Unknown cards include a live probability treatment based on feasible envelope solutions.

Inline probability bar
Percentage label
Accessibility summary describing likelihood

This tab is the fastest way to answer questions like:

Which categories are nearly solved?
Which cards are eliminated?
Which player definitely holds a known card?
Which unknown card is most likely to be in the envelope?

Players Tab

The Players tab explains what the app believes about each player’s hand.

Player cards

Each player gets an expandable card.

The app user is visually distinguished.
The app user’s card expands by default.
Each card header shows how many cards are known versus total hand size.

Within each player card

When expanded, the card can show:

Known cards
Possible cards
Showed one of unresolved markers

Unresolved marker display

This is especially useful during live play.

Every unresolved “showed one of these cards” clue is displayed by turn index.
The displayed candidate set narrows as later deductions eliminate options.
If only one candidate survives, that disjunction resolves and feeds the solver.

This makes the Players tab the best screen for checking:

who is nearly fully known
who still has large uncertainty
what ambiguous proofs still need future elimination to resolve

History Tab

The History tab shows the recorded timeline of the investigation.

History presentation

Uses a vertical timeline treatment with numbered badges.
Shows every recorded suggestion and accusation in chronological order.
Includes a timestamp for each turn entry.

Turn row content

Each turn row can show:

the suggesting player
the three suggested cards
whether the turn was an accusation
whether someone showed a card
which player showed
the specific shown card, if it was visible to the app user
a No one showed a card outcome when appropriate

Empty state

Before any turns exist, the tab shows an empty-state prompt encouraging the user to record the first turn.

Insights Tab

The Insights tab is the explanation layer for solver output.

Purpose

Instead of only showing what the solver believes, this tab explains why a deduction was made.

Insight timeline

Displays insights as a vertical timeline.
Uses iconography and badge styling based on insight type.
Can associate an insight with the turn that triggered it.

Each insight card can include

insight type label
title
related card chip
optional turn reference
expandable natural-language reasoning text

Examples of insight value

This screen is where a user can understand logic like:

why a card must be in the envelope
why a player’s ambiguous show has now resolved
why a no-show event eliminated multiple players from holding a card

Notepad Tab

The Notepad tab is a manual note-taking companion layered on top of the solver.

It exists because some players still want a place for intuition, reminders, table reads, or off-model notes that the formal solver does not track. The notepad presents a single unified surface — a structured detective grid with a freehand drawing layer on top — so the user can mark cells and sketch notes on the same “sheet of paper.”

Detective grid

The grid presents a traditional detective matrix.

Rows are cards grouped by category (with themed labels from the active edition).
Columns are players in seat order, capped at a reasonable max width so the grid stays compact and centered.
Each cell cycles through a manual mark state when tapped.
The grid does not scroll horizontally — it is a fixed-width surface that fits on screen.
Vertical scrolling is available when the content exceeds the viewport (e.g., editions with many cards) but the grid does not bounce when it fits entirely.

Available mark states:

none
check
cross
question
star

Grid marks are persisted into the Game model, so the user’s manual notes survive app relaunches and case resumes.

Freehand drawing overlay

A pencil FAB in the bottom-right corner toggles freehand drawing mode. When active, the user can draw directly on top of the grid and surrounding parchment area — the entire visible surface acts as a single drawable sheet.

Pencil-style strokes with color presets (white, gold, crimson, teal, steel)
Pen-size presets (thin, medium, thick)
Eraser mode
Undo last stroke
Clear-all with confirmation
Drawing mode disables grid cell tapping and scrolling so finger drags become strokes

Freehand strokes are encoded and stored on the Game model, then reloaded when the case resumes.

Drawing implementation details

Touch capture uses a UIKit-backed overlay to bypass SwiftUI ScrollView gesture conflicts.
Strokes are simplified before persistence to reduce data size.
Strokes render in viewport coordinates on top of the full parchment area.

Turn Recording Flow

The plus button in the dashboard opens the turn recorder.

Suggestion vs accusation mode

The first decision in the flow is whether the user is entering:

a normal suggestion
an accusation

The screen uses a mode toggle rather than separate entry points.

Turn composition

For both suggestions and accusations, the user selects:

the suggesting player
one suspect
one weapon
one room

Only non-eliminated players are shown as eligible suggesters.

Proof / result entry

After selecting the cards, the user moves to the proof screen.

Suggestion proof flow

The proof screen records what happened after the suggestion.

Did anyone show a card?
If yes, who showed?
If the app user was the suggester, which specific card was shown?

Proof validation

The proof screen prevents a number of invalid entries.

If the app user holds one of the suggested cards and another player suggested, the app will not allow No one showed.
If the app user would have had to show before the selected proving player, the app blocks that selection and explains why.
If the app user was the selected showing player but does not hold any of the suggested cards, the app rejects the choice.
If the app user suggested and already holds all three suggested cards, the UI explains that no one else could have shown one of them.

Accusation result flow

For accusations, the proof screen simplifies to:

Correct
Wrong

The engine uses that outcome to either solve the game or eliminate the accused triple from consideration.

Submission behavior

Turn submission records the turn in history and then rebuilds the solver from the recorded turns rather than relying on a drift-prone incremental mutation path. This keeps normal entry aligned with undo/resume behavior and reduces false contradiction scenarios.

Deduction And Solving Features

The solver is the heart of the product.

What the engine reasons about

The current engine models classic Clue-style games with:

one suspect in the envelope
one weapon in the envelope
one room in the envelope
clockwise suggestion disproval
fixed hand sizes
known-card ownership
ambiguous “showed one of these cards” disjunctions
wrong accusations removing exact suspect/weapon/room triples

Deduction capabilities users benefit from

Propagates direct ownership and exclusion facts.
Resolves disjunctions when only one possible shown card remains.
Deduces from no-show events by eliminating intermediate players from holding suggested cards.
Tracks when a category is solved and updates probabilities accordingly.
Calculates envelope likelihoods from feasible envelope triples rather than from simple heuristics.
Validates global feasibility with a backtracking card-assignment search.
Surfaces contradictions when the recorded game history becomes impossible.

Contradiction handling

Contradictions are not silent internal failures. They are an explicit user-facing feature.

Examples of contradiction categories include:

a card being both in a player’s hand and in the envelope
the same card being assigned to multiple players
a player having too many known cards
a player needing more cards than remain possible
no valid envelope solution remaining
impossible implications from no-show events

Persistence And State Management

Persistence is central to the app experience because Clue games are often paused or revisited.

Persisted game data

Each saved Game stores:

edition identity and display name
creation and last-played timestamps
completion and solved status
players
turns
all cards
envelope cards
the app user’s original hand
notepad grid marks
notepad freehand strokes

Resume behavior

When a saved case is reopened:

the app rebuilds the solver from the recorded turn history
restores the app user’s saved hand
recreates the undo manager
returns the user to the investigation workspace

Undo behavior

The dashboard exposes undo for the most recent recorded turn.

Undo removes the last recorded turn.
The engine is rebuilt from the remaining history.
This avoids trying to hand-maintain reverse deltas for every deduction.

Redo behavior

Redo exists in the undo manager internally, but the current main dashboard does not expose a redo button in the live UI.

Editions

Launch editions

The app launches with two verified editions:

Classic Clue (1949) — 6 suspects, 6 weapons, 9 rooms. The baseline.
Clue: Alfred Hitchcock — 6 suspects, 6 weapons, 9 locations. A verified classic-structure reskin.

Future editions (planned IAP)

The codebase ships with 25 bundled edition JSON files covering themed editions (Master Detective, Simpsons, Harry Potter, Game of Thrones, etc.). Most are currently marked as unsupported because they include side decks or mechanics the solver doesn’t model yet. Additional supported editions and a custom edition creator will be unlocked via in-app purchase.

Settings

The app includes a lightweight settings screen.

Current settings

Appearance mode:
- System
- Light
- Dark
Sound effects toggle
Haptic feedback toggle
App version display

Persistence of settings

Settings are stored in UserDefaults.
Sound and haptic managers are updated immediately when the values change.
UI testing mode can boot the app with a deterministic settings state.

Feedback, Theming, And Atmosphere

The app intentionally avoids looking like a plain spreadsheet utility.

Visual style

Dark mystery palette with gold highlights and mahogany surfaces.
Serif-forward display typography.
Rounded dossier-like cards and chips.
Card-category accent colors for suspects, weapons, and rooms.

Motion and feedback

Animated home-screen title shimmer.
Selection and deduction haptics when enabled.
Sound effects tied to key events when enabled.
Banners and solved-state reveals designed to make deductions feel eventful.

Accessibility And Usability Considerations

The app contains a mix of accessibility support and known UX polish areas.

Existing support

Accessibility identifiers across key controls for UI testing.
Row-level accessibility labels on card state rows.
Settings to disable sound and haptics.
Native navigation patterns in setup and modal flows.

UX philosophy reflected in the current product

The app tries to guide users away from invalid turn entry instead of merely accepting bad data and failing later.
The setup flow now preserves more user-entered information when navigating backward.
Contradictions are exposed clearly rather than silently corrupting the case.
The app favors live, explainable deduction over opaque “magic” solves.

Tech Stack

Layer	Technology
Language	Swift 6
UI	SwiftUI (iOS 17+)
Persistence	SwiftData (`@Model`, `ModelContainer`)
State management	`@Observable` macro (Observation framework)
Concurrency	`@MainActor` isolation
Testing	Swift Testing (`@Suite`, `@Test`, `#expect`) + XCTest (performance, UI)
Build	Xcode 16, XcodeGen (`project.yml`)

Architecture

Models

Game — Top-level persisted case file containing cards, players, turns, envelope state, status flags, and notepad data.
Player — Name, seat index, hand size, ownership knowledge, possible cards, elimination state, and unresolved show-card markers.
Card — Suspect, weapon, or room card with edition identity and transient envelope probability used for display.
Turn — Suggestion or accusation entry with suggesting player, selected cards, proving player, shown card, result state, and timestamp.
CardMarker — Represents unresolved “showed one of these cards” information.
GameEdition — Codable edition definition loaded from bundled or custom JSON.

Engine

DeductionEngine — Propagation-based solver with envelope-triple enumeration and global feasibility search.
StateValidator — Detects contradictions after propagation and rebuild passes.
EngineSnapshot — Deterministic snapshot artifact used by tests to compare full logical state.
Constraint — Encodes the types of facts the engine can reason about.

Supporting infrastructure

AppState — Owns navigation state, setup draft, current game, engine, undo manager, and settings.
EditionRegistry — Loads, saves, deletes, and resolves editions.
UndoRedoManager — Maintains undo/redo stacks and rebuilds the engine from stable history.
ExportManager — Generates plain-text investigation reports.
ClueTheme — Shared color, typography, spacing, and component styling.
HapticManager / SoundManager — Toggleable feedback systems.

Testing

The test suite is intentionally heavier on solver correctness than a typical consumer app because logical trust is the product.

See testing-suite.md for detailed commands and test-architecture notes.

File Layout

ClueSolver/
├── App/                    AppState, ClueSolverApp
├── Models/                 Game, Player, Card, Turn, CardMarker, GameEdition, CardCategory
├── Engine/                 DeductionEngine, Constraint, StateValidator, EngineSnapshot
├── Views/
│   ├── Home/               HomeView, SavedGamesView, SettingsView
│   ├── Setup/              EditionPicker, PlayerCount, PlayerNames, CardDistribution, MyCards
│   ├── Game/               Dashboard, Cards, Players, History, Insights, Notepad
│   ├── Turn/               Suggestion/Accusation entry and proof screens
│   └── CustomEdition/      Custom edition list and creator
├── Editions/               Registry + bundled JSON definitions
├── Theme/                  Theme, animations, sound, haptics
├── Utilities/              UndoRedoManager, ExportManager
└── Extensions/             Shared view helpers

ClueSolverTests/            Domain, regression, integration, and performance tests
ClueSolverUITests/          End-to-end UI automation
Docs/                       Audits, project docs, testing docs
design-system/              Repo-level UI guidance and design tokens

Edition Support Status

At launch, Classic Clue and Alfred Hitchcock are the two available editions. The codebase includes data for 25 editions total, with compatibility metadata that categorizes each as Supported or Unsupported based on whether the physical edition’s rules fit the current 3-category deduction engine.

See edition-support-audit.md for the full breakdown.

Current Limitations

The active solver only models classic-style suspect + weapon + room envelope games.
Side decks, player powers, encounter cards, lying mechanics, and other non-classic rule families are not supported.
Export/report generation exists in code but is not surfaced in the main user flow.
Redo exists internally but is not exposed in the dashboard UI.
No cloud sync, sharing, or multiplayer synchronization.
No Apple Pencil or pressure-sensitive drawing support.

Planned Expansion (IAP Roadmap)

Unlock additional editions (Master Detective, Simpsons, and more as they are verified).
Custom edition creator for homebrew or unsupported variants.
Potential future features: export/share case reports, Apple Pencil support, additional solver rule families.

Short Summary

Clue Solver is a premium native iOS deduction companion for the classic board game Clue / Cluedo. It goes far beyond a paper notepad — it actively solves the mystery by reasoning through every suggestion, tracking card ownership, calculating probabilities from feasible envelope solutions, and explaining its deductions in plain language. The app includes case-file save/resume, a unified detective notepad with freehand drawing, contradiction detection, a themed mystery UI, and is designed for one player sitting at a real table game.