# Whiteboard Suite
**Human Retention Layer for AI Work**
Two agent skills that prevent AI usage from eroding human understanding. Works on Claude Code, GitHub Copilot, Cursor, Windsurf, Cline, Codex CLI, Gemini CLI, and 10+ more platforms.
## The Problem This Solves
You ask an AI agent to build an analytical model. It writes 500 lines of code with gradient boosting, feature engineering, normalization pipelines, and cross-validation. The output looks correct. The stakeholder asks: "How does it work?" You open the code and realize you cannot explain it. Not because you are incompetent, but because you never saw the intermediate math. You trusted the pipeline without inspecting the equations.
This is not a hypothetical. It happens every day to developers, analysts, data scientists, and managers who rely on AI coding assistants. The work gets done, but the understanding does not transfer.
The same thing happens with long AI sessions. You spend 45 minutes going back and forth with an agent — exploring options, making decisions, narrowing scope, choosing approaches. By the end, the final artifact exists, but the reasoning that produced it is buried in a conversation you will never re-read. Three weeks later, someone asks why you chose approach A over approach B, and you cannot remember.
**Whiteboard Suite exists to fix both problems.**
## What It Does
### /whiteboard-math — Understand What Was Built
Takes any AI-generated model, algorithm, scoring logic, optimization, simulation, or analytical pipeline and produces a **hand-solvable mathematical shadow model**. A tiny, faithful analogue that uses 3-5 rows of data and numbers you can compute on paper.
**What you get:**
- Formula extraction — all variables, parameters, assumptions, and governing equations pulled from the code into standard math notation
- Canonical example — a minimal dataset (3-5 rows, simple integers) with every intermediate calculation shown step by step
- Whiteboard sketch — a diagram you could draw on paper (scatter plot, decision boundary, tree diagram, flow chart)
- Math unit tests — deterministic expected outputs for toy inputs (normal case, zero case, extreme case)
- Production mapping — honest explanation of what the toy model preserves and what it simplifies away from the real system
- Edge cases — inputs that reveal model limitations and assumptions that might break
**When to use it:**
- After an agent builds a model or algorithm
- Before presenting analytical work to stakeholders
- During code review when math is involved
- When debugging unexpected model outputs
- When you need to explain a system to someone who was not in the room when it was built
### /session-xray — Understand How You Got There
Takes a long AI-human session and reconstructs the **underlying reasoning machinery**. Not a summary of what was discussed, but a structured extraction of what was decided, what was assumed, and what was left unresolved.
**What you get:**
- Goal map — what you were actually trying to achieve (stated and implied goals, constraints, hidden success criteria)
- Assumption ledger — every assumption in the session classified as explicit, implicit, negotiated, or hidden, with fragility assessment
- Decision log — every choice made, what alternatives were considered, what the rationale was, and whether it is reversible
- Logic skeleton — the irreducible reasoning structure (premises, transformations, conclusions, dependency chain)
- Formula distiller — any quantitative reasoning converted to explicit equations, thresholds, or rules
- Dependency graph — what outputs depend on what inputs, assumptions, and decisions (with critical path highlighted)
- Ambiguity detector — undefined terms, changing definitions, hidden reasoning leaps, contradictions, and weakly justified steps
**When to use it:**
- After a long session where you feel lost in the conversation
- Before presenting work that was developed through AI conversation
- When you need to explain decisions to someone who was not part of the session
- At project milestones to capture reasoning before it fades
- When auditing or reviewing AI-assisted analytical work
### Using Both Together
Run `/session-xray` to extract the reasoning from a session, then run `/whiteboard-math` on any extracted formulas. This creates a complete interpretability chain: **why** it was built (reasoning) + **how** it works (math).
## Real-World Scenarios
**Data scientist building a churn prediction model.** The agent writes a logistic regression with feature engineering. You run `/whiteboard-math` and get: z = -4 + 0.1*tenure + 0.5*complaints, P = 1/(1+e^-z). For a customer with 20 months tenure and 3 complaints: z = -0.5, P = 0.38. You can now explain to the product team exactly how the model scores customers.
**Analyst designing a pricing strategy with an agent.** After 30 minutes of back-and-forth, you run `/session-xray` and discover: three assumptions were never verified, the scope narrowed from "all products" to "top 10 SKUs" without anyone acknowledging it, and the discount threshold of 15% came from nowhere. Now you know what to verify before presenting.
**Engineering manager reviewing AI-generated optimization code.** The agent wrote a constraint solver. You run `/whiteboard-math` and get a 2-variable, 3-constraint example you can solve graphically. The feasible region, the vertices, the optimal point. You can verify the code's logic without reading the implementation.
**Consultant documenting AI-assisted work for a client.** You run `/session-xray` at the end of each working session. The client gets a clean reasoning trail: what was decided, what was assumed, what depends on what. Three months later, when the project needs changes, the reasoning is traceable.
## Installation
No API keys. No dependencies. No external services. These are instruction-only skills — they teach your AI agent how to produce interpretability artifacts.
### macOS / Linux
```bash
git clone https://github.com/FrancyJGLisboa/whiteboard-suite.git
cd whiteboard-suite
chmod +x install.sh
./install.sh
```
### Windows
```powershell
git clone https://github.com/FrancyJGLisboa/whiteboard-suite.git
cd whiteboard-suite
.\install.ps1
```
Both installers auto-detect your platform. To target a specific one:
```bash
# macOS/Linux
./install.sh --platform copilot # GitHub Copilot
./install.sh --platform cursor # Cursor
./install.sh --platform claude-code # Claude Code
# Windows
.\install.ps1 -Platform copilot
.\install.ps1 -Platform cursor
.\install.ps1 -All # Install to every detected platform
```
### Supported Platforms
Claude Code, GitHub Copilot (VS Code + CLI + Agent), Cursor, Windsurf, Cline, Codex CLI, Gemini CLI, Kiro, Trae, Goose, OpenCode, Roo Code, Kilo Code, Factory Droid, Junie, Antigravity, and any tool that reads the universal `.agents/` directory.
### Manual Installation
Copy each skill folder into your platform's skill directory:
| Platform | Path |
|----------|------|
| Claude Code | `~/.claude/skills/` |
| GitHub Copilot | `.github/skills/` |
| Cursor | `.cursor/rules/` |
| Windsurf | `.windsurf/skills/` |
| Cline | `.clinerules/` |
| Codex CLI | `.codex/skills/` |
| Gemini CLI | `.gemini/skills/` |
## Usage
Once installed, open a new session and type:
```
/whiteboard-math Show me the math behind this model
/whiteboard-math Create a canonical example for this scoring algorithm
/whiteboard-math Decompose this optimization into hand-solvable steps
/session-xray Distill this session into its core logic
/session-xray What assumptions did we make?
/session-xray Find contradictions in our discussion
```
The skills also activate automatically when relevant context is detected (e.g., after model building, or when you ask "how does this work" or "what did we decide").
## Structure
```
whiteboard-suite/
├── whiteboard-math-skill/
│ ├── SKILL.md # Skill definition
│ ├── AGENTS.md # Cross-platform companion
│ ├── references/
│ │ ├── model-catalog.md # Strategies for 11 model types
│ │ └── methodology.md # Full methodology framework
│ └── assets/
│ └── output-schema.json
├── session-xray-skill/
│ ├── SKILL.md # Skill definition
│ ├── AGENTS.md # Cross-platform companion
│ ├── references/
│ │ ├── extraction-methods.md # Extraction methodology
│ │ └── output-formats.md # Alternative output formats
│ └── assets/
│ └── output-schema.json
├── shared/
│ └── integration-guide.md # How the two skills connect
├── AGENTS.md # Suite-level companion
├── install.sh # macOS/Linux installer
├── install.ps1 # Windows PowerShell installer
└── README.md
```
## The Principle
Every materially important AI interaction should be reducible to an inspectable model of goals, assumptions, decisions, formulas, and expected conclusions.
This suite enforces that principle across two dimensions:
- **Output dimension**: The built artifact has a hand-solvable mathematical twin
- **Session dimension**: The reasoning path has a compressed, auditable representation
## License
MIT