Skip to content

docs(specs): add functional specs for ten roadmap initiatives #1293

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
KaelSensei merged 1 commit into from
Nov 8, 2026
Merged

docs(specs): add functional specs for ten roadmap initiatives #1293

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 22 additions & 0 deletions docs/product/roadmap.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -209,6 +209,8 @@ The November competitive pass did not open a new initiative for work the roadmap

# Initiatives

Detailed functional specs live in [`docs/product/specs/`](specs/README.md): one per initiative, each with a dated market sweep, the current state of the code, and delivery slices with their dependencies.

## I-01: Deck Editor Workflow

**Outcome:** a player can build, reorganize and refine a deck without losing cards, context or intent.
Expand Down Expand Up @@ -312,6 +314,8 @@ A user can move a card between every legal zone, reload the page, change its pri

## I-02: AI Deck Copilot

**Spec:** [`specs/i02-checkable-ai-copilot.md`](specs/i02-checkable-ai-copilot.md)

**Outcome:** a player can describe what they want and receive a legal, budget-aware and explainable plan.

**Status:** In progress
Expand Down Expand Up @@ -796,6 +800,8 @@ A local model is only promoted if it matches the required quality for a clearly

## I-13: Product Visual Redesign

**Spec:** [`specs/i13-visual-direction.md`](specs/i13-visual-direction.md)

**Outcome:** a player can find, build, understand and share a Commander deck in an interface that feels coherent, distinctive and calm even when card data is dense.

**Status:** In progress
Expand Down Expand Up @@ -837,6 +843,8 @@ The deck-library-to-editor-to-share journey is visually coherent and remains at

## I-14: Verifiable Natural-Language Search

**Spec:** [`specs/i14-verifiable-natural-language-search.md`](specs/i14-verifiable-natural-language-search.md)

**Outcome:** a player can describe a card function in English or French, read the Scryfall query that search will run, edit it, and get the cards that query returns.

**Status:** Next
Expand All @@ -862,6 +870,8 @@ For a fixed description and deck context, the player sees one Scryfall query, ca

## I-15: Rule 0 Sheets And Pod Profiles

**Spec:** [`specs/i15-rule-zero-sheets-and-pod-profiles.md`](specs/i15-rule-zero-sheets-and-pod-profiles.md)

**Outcome:** a playgroup can share intentions and house rules before a game, and can tell those preferences apart from official rules.

**Status:** Next
Expand All @@ -886,6 +896,8 @@ Four players can compare consented profiles and see house preferences distinguis

## I-16: Decks Buildable From A Collection

**Spec:** [`specs/i16-decks-buildable-from-a-collection.md`](specs/i16-decks-buildable-from-a-collection.md)

**Outcome:** a player can start from owned cards and see which commanders or lists those cards can build, including free copies and the cost of what is missing.

**Status:** Next
Expand All @@ -911,6 +923,8 @@ A collection produces a ranked, sourced view of buildable lists that shows free

## I-17: Precon Path And Tiered Upgrades

**Spec:** [`specs/i17-precon-path-and-tiered-upgrades.md`](specs/i17-precon-path-and-tiered-upgrades.md)

**Outcome:** a player can open a dated official precon, see the diff from that list, and apply a reversible budget bundle on a separate working copy.

**Status:** Next
Expand All @@ -935,6 +949,8 @@ A player can open a dated precon, preview a budget bundle, apply it to a working

## I-18: Per-Deck Radar Of New Cards

**Spec:** [`specs/i18-per-deck-radar-of-new-cards.md`](specs/i18-per-deck-radar-of-new-cards.md)

**Outcome:** a player can ask which newly released, legal cards matter for one deck, read a sourced reason, and adopt a card only from a visible diff.

**Status:** Later
Expand All @@ -959,6 +975,8 @@ A player can request a sourced, legal shortlist for one deck and accept or ignor

## I-19: Offline Game-Night Viewing

**Spec:** [`specs/i19-offline-game-night-viewing.md`](specs/i19-offline-game-night-viewing.md)

**Outcome:** a player can choose one deck and read that deck, its primer and its tokens without a network.

**Status:** Next
Expand All @@ -983,6 +1001,8 @@ After an explicit download, the chosen deck, primer and tokens remain readable o

## I-20: Collaborative Review

**Spec:** [`specs/i20-collaborative-review.md`](specs/i20-collaborative-review.md)

**Outcome:** an owner can invite someone to propose a deck patch, then accept or reject that patch without handing over the deck.

**Status:** Later
Expand All @@ -1007,6 +1027,8 @@ A collaborator can propose a change, the owner can accept or reject it, and the

## I-21: Reproducible Probability Bench

**Spec:** [`specs/i21-reproducible-probability-bench.md`](specs/i21-reproducible-probability-bench.md)

**Outcome:** a player can compare thousands of simulated hands between two deck snapshots under an explicit mulligan policy, and can rerun the same comparison.

**Status:** Later
Expand Down
42 changes: 42 additions & 0 deletions docs/product/specs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
# Functional specs

One spec per roadmap initiative. The [roadmap](../roadmap.md) says _what_ an initiative must achieve and _why_; a spec here says what it does in detail, what the market already does, what the code looks like today, and how the work splits into slices an agent or a developer can pick up without making a product decision.

Written on 2026-11-08 from a market sweep of the whole category, not only the named incumbents, and from the code as it stood on `dev` that day.

## How to read one

Every spec follows the same shape, matching the house format already used by [`commander-power-meter.md`](../commander-power-meter.md):

**Overview** · **What the market does** (sourced, dated) · **Current state in this codebase** (verified paths) · **Functional requirements** (numbered, testable) · **Data and API** · **Non-goals** · **Testing strategy** · **Delivery slices** (with dependencies) · **Open questions**

The **Delivery slices** table is the part that matters for automation: each slice is independently reviewable, and the dependency column says which ones cannot start yet. Three scheduled agents pick work from this roadmap every day — the dependency edges are what stop them colliding.

## Index

| Spec | Initiative | Status | The one-line reason it exists |
| ------------------------------------------------------------------------------- | ---------- | ------ | ----------------------------------------------------------------------------------------------------- |
| [Checkable AI copilot](i02-checkable-ai-copilot.md) | I-02 | Now | Competitors validate **or** explain; doing both visibly is the cheapest differentiator on the roadmap |
| [Visual direction](i13-visual-direction.md) | I-13 | Next | The audit, the measured failures, and the register chosen over the fantasy one |
| [Verifiable natural-language search](i14-verifiable-natural-language-search.md) | I-14 | Next | Showing the query is already table stakes; deck context and French are not |
| [Rule 0 sheets and pod profiles](i15-rule-zero-sheets-and-pod-profiles.md) | I-15 | Next | Everyone classifies a deck; nobody records what four people agreed |
| [Decks buildable from a collection](i16-decks-buildable-from-a-collection.md) | I-16 | Next | Four products rank by coverage; none excludes copies already committed elsewhere |
| [Precon path and tiered upgrades](i17-precon-path-and-tiered-upgrades.md) | I-17 | Next | The market publishes upgrade articles; none is a reversible operation on your list |
| [Per-deck radar of new cards](i18-per-deck-radar-of-new-cards.md) | I-18 | Later | Spoiler coverage is universal and entirely set-centric; the per-deck join is open |
| [Offline game-night viewing](i19-offline-game-night-viewing.md) | I-19 | Next | Competitors ship offline card databases; the one deck you are about to play is the honest slice |
| [Collaborative review](i20-collaborative-review.md) | I-20 | Later | Archidekt gives collaborators direct write access; propose-and-accept exists nowhere |
| [Reproducible probability bench](i21-reproducible-probability-bench.md) | I-21 | Later | Five tools simulate thousands of hands; none publishes a seed or an interval |

## What the sweep concluded

Three findings shaped every spec above.

**Generation is commoditised; verification is not.** Six products sell conversational Commander building, several free. One of them documents that its own results vary between runs. What no competitor publishes is which claims were checked against card data and which are model reasoning.

**The collection-to-deck direction is crowded; the ownership detail is not.** SuperBrew, DeckFinder, ManaBuilder, MTG Agents and ManaForge all rank decks by collection coverage. None states that a copy already committed to another of your decks is excluded, and none separates Oracle identity (for legality) from printing identity (for price).

**Reproducibility is absent across the whole category.** Hand simulators, bracket calculators and AI builders all return a number without a seed, an interval or a sample size. For a product positioning itself on checkable output, that is the widest opening found in the sweep.

## Discipline

A spec is a plan, not a record. It does not mark anything shipped — the roadmap's `Status` and its scope checkboxes remain the only source of truth for what exists. Competitor rows are claims read from public pages on a stated date, not evidence; revalidate before a row justifies implementation.
96 changes: 96 additions & 0 deletions docs/product/specs/i02-checkable-ai-copilot.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,96 @@
# Spec: Checkable AI Copilot (I-02)

> **Initiative:** [I-02 in the roadmap](../roadmap.md) · **Status:** In progress · **Priority:** Now · **Researched:** 2026-11-08
> **Owns:** making the deterministic verdict visible. **Does not own:** natural-language search (I-14) or meta evidence (I-09).

## Overview

The copilot already validates its own output deterministically and never lets the model decide legality. The player cannot see that. This spec makes the check visible: every claim in a suggestion is marked as **verified against card data** or as **model reasoning**, and the validator's verdict is shown rather than silently applied.

## What the market does

Conversational Commander building is no longer a gap. Six products sell it, several free. Read on 2026-11-08 from each product's own pages:

| Product | Validation | Explanation |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
| **ManaTap** | States deterministic legality and colour-identity validation; a Deck Checker scores legality, curve, ramp, draw, removal, threats, synergy | Chat and an iterative workshop |
| **Farseek** | **States no deterministic legality validation**; performs live Scryfall lookups before each recommendation | Argues why a card fits, reading the whole list |
| **DeckCheck** | DTI, PowerTune, ManaTune, DeckTrim; its support page documents that **AI results vary between runs** | Deckhand chat |
| **MTG Master** | States it enforces legal commander, colour identity and singleton | Bracket and collection-aware generation |
| **ManaForge** | Re-validates saved decks against live ban lists | Build-from-stock, commander swaps |
| **CommanderSalt** | — | A May 2026 community thread calls its report detailed but prone to overrating decks |

**The pattern.** Products either validate **or** explain. ManaTap validates and scores but does not publish which claims were checked. Farseek explains persuasively and does not claim validation at all. DeckCheck openly documents that its output is non-deterministic.

**The opening.** Do both, and say which is which. A suggestion where "this is legal in your colour identity" is a checked fact and "this smooths your turn-three" is model reasoning is a different product from one where both arrive in the same sentence at the same confidence. The validator already exists; it is simply invisible.

This is also the cheapest differentiator on the roadmap: it is a presentation change over machinery that already passes its tests.

## Current state in this codebase

Already shipped, per the roadmap:

- Claude and OpenAI providers, server-side keys, rate limiting, prompt-injection protections.
- A **deterministic post-generation validator**; the LLM never decides legality.
- Structured plan before generation; per-card reasoning; alternatives by budget, power and play pattern.
- Diff before applying; "why is this card here?" and "what is the weakest card?".
- A golden evaluation set for structure and evidence contracts.
- `ExternalRecommendationFreshness` and AI-suggested labelling (#1052) — the labelling vocabulary already exists for external sources.

Open in the roadmap: _"Keep the deterministic validator's verdict visible in the copilot's output instead of only applying it silently."_ This spec details that item.

## Functional requirements

### 1. Two kinds of claim, never mixed

1.1 Every statement attached to a suggestion is typed as **checked** or **reasoned**.
1.2 A checked claim names what verified it — Scryfall card data, the format banlist, the colour-identity rule, the Game Changers list, the singleton rule — and carries the data's observation time.
1.3 A reasoned claim is labelled as model reasoning, with no source, and is never styled to look checked.
1.4 Checked and reasoned claims are visually distinguishable without relying on colour alone.

### 2. The verdict is shown

2.1 After generation, the validator's result is rendered: what passed, what was corrected, what was rejected.
2.2 A suggestion the validator rejected is shown as rejected with the rule that rejected it, not silently dropped. A player learning that the model proposed an illegal card, and that the product caught it, is the proof the feature exists to give.
2.3 The count of corrections is visible at the top of the result, not buried per card.

### 3. Reproducibility is stated

3.1 The result states whether the same brief would reproduce the same plan, and names the provider and model used.
3.2 Where output is non-deterministic, say so — DeckCheck documents this and the product should not pretend otherwise.

### 4. No regression in the existing contract

4.1 The LLM still never decides legality, colour identity, quantities or bracket rules.
4.2 Making the verdict visible changes presentation only; the validator's behaviour is unchanged and its tests are untouched.

## Non-goals

- Increasing generation volume or speed. Explicitly a non-goal in the roadmap: a wrong deck produced instantly is the failure this product exists to avoid.
- Qualitative provider-backed evaluation of usefulness, until a stable review rubric exists — that remains the open golden-set item.
- Replacing I-09's source-and-freshness labelling with a second vocabulary. Reuse it.

## Testing strategy

- **Contract:** every claim in a copilot response carries a type; an untyped claim fails the test.
- **Contract:** a checked claim carries a source and an observation time; a reasoned claim carries neither.
- **Sociable:** a brief that provokes an illegal suggestion renders it as rejected with its rule, and the deck is unchanged.
- **Accessibility:** the checked/reasoned distinction survives greyscale and a screen reader.
- **Regression:** the existing golden set passes unchanged — this spec must not alter validator behaviour.

## Delivery slices

| # | Slice | Depends on |
| --- | -------------------------------------------------------------------------- | ---------- |
| 1 | Type every claim at the API boundary: `checked` with source, or `reasoned` | — |
| 2 | Render the distinction, non-colour-dependent, in the suggestion panel | 1 |
| 3 | Validator verdict panel: passed, corrected, rejected with rules | 1 |
| 4 | Rejected suggestions shown rather than dropped | 3 |
| 5 | Provider, model and reproducibility statement on the result | 1 |

Slice 1 is a contract change and should land with its tests before any UI work; slices 2 and 3 can then proceed in parallel.

## Open questions

- Does showing rejected suggestions undermine confidence, or build it? The argument for showing them is that the product's whole claim is that the check is real — and an invisible check is indistinguishable from no check. Worth watching once it ships.
- Should the verdict be exportable with the deck, so a player can show their pod that the list was validated? That edges into I-15's Rule 0 sheet and may belong there instead.
Loading
Loading