Usage Guide v1.1.0

Everything you need to start solving problems with uber-polya — the math problem-solver for every AI coding assistant.

uber-polya is a free, open-source skill that implements George Polya's four-phase problem-solving cycle as an executable algorithm. You describe a problem in plain English. It finds the mathematical structure, selects the right algorithm, writes verified solver code, runs it, and gives you the answer with proof.

Don't guess. Solve.

Installation

Claude Code (primary)

$ git clone https://github.com/agtm1199/uber-polya.git

$ cd uber-polya

$ bash install.sh

Where would you like to install the skills?

1) Global (~/.claude/skills/) — available in all projects

2) Local (./.claude/skills/) — current project only

That's it. No virtual environment, no build step. The skills are plain markdown files that your AI agent reads on demand.

Other platforms

uber-polya ships native config files for each platform. Clone the repo and the config is already in place:

Platform	Config File(s)	Format
Claude Code	`CLAUDE.md` + `skills/*/SKILL.md`	Skills with YAML frontmatter
OpenAI Codex	`AGENTS.md`	Cross-tool standard
GitHub Copilot	`.github/copilot-instructions.md`	Markdown
Cursor	`.cursor/rules/uber-polya.mdc`	Markdown with glob targeting
Windsurf	`.windsurf/rules/uber-polya.md`	Markdown
Amazon Kiro	`.kiro/steering/uber-polya.md`	Markdown with YAML frontmatter
Qoder, Antigravity, others	`AGENTS.md`	Cross-tool standard

All reference files (skills/*/references/) are pure markdown readable by any tool. The 36 worked examples use standard Python with no tool-specific dependencies.

Python dependencies

uber-polya generates Python solver code. Install the libraries as needed, or all at once:

# Install everything at once

$ pip install matplotlib numpy pulp scipy sympy networkx cvxpy z3-solver statsmodels

# Or install by category:

$ pip install pulp # ILP/LP (scheduling, knapsack, seating)

$ pip install scipy # Assignment, fair division

$ pip install networkx # Graph coloring, paths

$ pip install cvxpy # Convex optimization, portfolio

$ pip install z3-solver # SAT/SMT, theorem proving

$ pip install sympy # Symbolic algebra, break-even

$ pip install statsmodels # Statistical inference, A/B tests

$ pip install matplotlib numpy # Visualization (all examples)

$ pip install jinja2 fpdf2 # PDF report generation

Quick Start

Open your AI agent and type a problem. Here's an exam scheduling example using the three skills step by step.

Step 1: Model the problem

$ /uber-model I need to schedule 4 exams (A, B, C, D) into the fewest

time slots so no student has two exams at the same time. Students

are enrolled in: {A,B}, {A,C}, {B,D}, {C,D}.

Structure: Graph coloring on conflict graph G = (V, E)

Vertices V = {A, B, C, D} (exams)

Edges E = {(A,B), (A,C), (B,D), (C,D)}

Objective: Minimize k (chromatic number)

Graph is bipartite → chromatic number = 2

Step 2: Solve it

$ /uber-solve

Algorithm: Bipartite 2-coloring via BFS

Answer: chromatic number = 2

Slot 1: {A, D}

Slot 2: {B, C}

Verification: All 4 edges checked — no conflicts. PASS.

Step 3: Interpret the result

$ /uber-interpret

Bottom line: You need exactly 2 time slots. No student has a conflict.

Slot 1 (e.g., Monday 9 AM): Exams A and D

Slot 2 (e.g., Monday 2 PM): Exams B and C

Sensitivity: If a student enrolls in both A and D,

chromatic number rises to 3 (odd cycle created).

Modeling insight: Whenever you need items in the fewest

groups with separation constraints → graph coloring.

Or use the orchestrator to run all three steps automatically:

$ /uber-polya Schedule 4 exams into the fewest slots with no student conflicts

Runs all three phases automatically. Same result, one command.

Polya Phase	Skill	What it does
1-2 Understand & Plan	`/uber-model`	Translates your problem into a formal mathematical model
3 Execute	`/uber-solve`	Classifies, selects algorithm, solves, verifies
4 Look Back	`/uber-interpret`	Translates the solution into actionable insight

The Four Skills

uber-polya ships four skills. Use the orchestrator for most problems, or individual skills for more control.

/uber-polya Orchestrator

Chains Model → Solve → Interpret as one command

When to use: Most of the time. Just describe your problem.

Invocation: /uber-polya <describe your problem>

Full Pipeline — complete model, solve, interpret cycle
Fast-Track — skip Socratic dialogue for well-defined problems
Stop-After-Model — just formalize, don't solve
Stop-After-Solve — solve but skip interpretation
PDF Report — generate a branded PDF report with equations and figures

/uber-model Phase A

Real-world problem → formal mathematical model

When to use: When you want to understand the math without solving yet.

Walks through Polya's Phases 1-2 via Socratic questioning. Classifies the problem, identifies unknowns, data, and constraints, then builds a formal model with a mapping table connecting math variables to real-world meaning.

Phase 0: Problem Reception & Classification
Phase 1: Understanding (unknowns, data, conditions)
Phase 2: Devising a Plan (heuristics, candidate structures)
Phase 3: Formalization (formal model + mapping table)
Phase 4: Bridge (hand off to /uber-solve)

References: heuristics.md, structures.md, problem-classification.md, common-mistakes.md, model-templates.md

/uber-solve Phase B

Formal model → verified solution

When to use: When you already have a well-defined math problem.

Classifies the problem to a named problem class, selects the right algorithm based on instance size and complexity, writes a complete Python solver with Instance/Solution dataclasses, runs it, and independently verifies the answer.

Phase 0: Model Reception & Classification
Phase 1: Algorithm Selection + verification method
Phase 2: Solution Engineering (Python solver code)
Phase 3: Execution & Verification
Phase 4: Optimization & Hardening

References: algorithms.md, solvers.md, algorithms-statistics.md, solvers-statistics.md, solving-protocols.md, optimization-hardening.md

/uber-interpret Phase C

Solution → actionable insight

When to use: When you have a solution and need to explain it to stakeholders.

Translates mathematical output back to real-world meaning. Performs sensitivity analysis, generates visualizations, formulates actionable recommendations, and adapts communication for the audience (technical, decision-maker, or general).

Phase 0: Context Recovery (mapping, objective, audience)
Phase 1: Solution Translation
Phase 2: Robustness & Sensitivity Analysis
Phase 3: Visualization (matplotlib/seaborn)
Phase 4: Recommendations & Communication
Phase 5: Knowledge Transfer

References: interpretation-patterns.md, visualization.md

Problem Gallery

36 worked examples with complete solver code, independent verification, and sample data.

Everyday Problems 16

Shift Scheduling

Schedule 8 nurses across 3 shifts over 7 days with staffing and fairness constraints

ILP (PuLP/CBC)

Budget Optimization

Select projects to maximize ROI under a $500K budget

0/1 Knapsack ILP

Fair Rent

Split $3000 rent fairly among 3 roommates with different-sized rooms

Hungarian + envy-free

Route Planning

Find the shortest delivery route visiting 8 locations

Held-Karp DP (TSP)

Project Prioritization

Rank 8 features by 4 weighted criteria

MCDA (NumPy)

Study Schedule

Create a conflict-free study timetable for 6 subjects

Graph coloring

Meal Planning

Plan 7 dinners minimizing cost within nutrition targets

ILP (PuLP/CBC)

Team Assignment

Assign 6 developers to 6 projects maximizing satisfaction

Hungarian (SciPy)

Break-Even Analysis

Find break-even quantity for a new product launch

Symbolic (SymPy)

Event Seating

Seat 12 wedding guests at 3 tables with must-together/apart constraints

ILP (PuLP/CBC)

Carpool Scheduling

Rotate school drop-offs among 4 families, minimizing total drives

ILP (PuLP/CBC)

Workout Plan

5-day exercise schedule hitting all muscle group volume targets

ILP (PuLP/CBC)

Trip Itinerary

Pick city attractions maximizing enjoyment within time and budget

2D Knapsack ILP

Debt Payoff

Optimal extra-payment allocation across 4 debts to minimize interest

Avalanche (greedy)

Energy Bill

Schedule 5 appliances to time-of-use pricing windows to cut costs

ILP (PuLP/CBC)

Potluck Planning

Assign dish categories to 8 guests matching skills, covering all courses

ILP (PuLP/CBC)

Technical Showcases 6

Milking Cows

Interval merging — find longest milking period and longest idle gap

Sort + sweep O(N log N)

Inspector Assignment

Assign 6 inspectors to 10 facilities maximizing expertise score

ILP + LP relaxation

Portfolio Optimization

Markowitz mean-variance optimization with efficient frontier

Convex QP (cvxpy)

Tournament Hamiltonian

Prove every tournament has a Hamiltonian path via induction

Induction + Z3

A/B Testing

Determine if a checkout flow redesign significantly improved conversions

z-test + Bayesian + bootstrap

Cafe Tips

Does music genre affect tipping? Full Polya cycle demonstration.

t-test + Mann-Whitney + Bayesian

Knowledge Base

uber-polya ships 15 reference files that the AI reads on demand. These are the curated catalogs that power problem classification, algorithm selection, and solution interpretation.

305

Algorithms

Structures

Heuristics

Solver Libraries

Domains

Reference files by skill

Skill	File	Contents
/uber-model	heuristics.md	17 Polya heuristics with Socratic questions
	structures.md	43 structures across 10 domains with pattern matching
	problem-classification.md	Decision tree + quick-lookup table for rapid classification
	common-mistakes.md	16 anti-patterns (modeling, solving, interpretation)
	model-templates.md	5 fill-in-the-blank formal model templates
/uber-solve	algorithms.md	94 algorithms (discrete math + continuous optimization)
	algorithms-statistics.md	45 statistical algorithms (hypothesis tests, regression, Bayesian)
	solvers.md	9 solver libraries (NetworkX, PuLP, Z3, SymPy, SciPy, OR-Tools, cvxpy, ...)
	solvers-statistics.md	6 statistical libraries (scipy.stats, statsmodels, PyMC, ...)
	solving-protocols.md	8 domain-specific solving workflows
	optimization-hardening.md	Performance tuning and production hardening
/uber-interpret	interpretation-patterns.md	Domain-specific math-to-reality translation patterns
/uber-interpret	visualization.md	20+ chart types with matplotlib templates

Domains covered

Domain	Status	What it adds
Graph Theory	Shipped	Coloring, shortest path, matching, flow, connectivity
Combinatorics	Shipped	Counting, permutations, combinations, inclusion-exclusion
Set Theory	Shipped	Set operations, partitions, covers
Logic	Shipped	SAT, SMT, propositional and first-order logic
Number Theory	Shipped	GCD, primality, modular arithmetic
Relations & Orders	Shipped	Topological sort, partial orders, lattices
Optimization	Shipped	ILP, LP, knapsack, assignment, scheduling
Discrete Probability	Shipped	Expected value, random variables, distributions
Continuous Optimization	Shipped	Convex QP, BFGS, gradient descent, interior point
Statistical Inference	Shipped	Hypothesis testing, regression, Bayesian, bootstrap
Game Theory	Shipped	Nash equilibrium, fair division, mechanism design
Machine Learning	Shipped	Classification, clustering, dimensionality reduction
Simulation	Shipped	Monte Carlo, discrete-event, agent-based
Time Series	Shipped	ARIMA, forecasting, anomaly detection
Decision Analysis	Shipped	Multi-criteria, decision trees, utility theory
Linear Algebra	Shipped	Matrix ops, decomposition, systems of equations
Calculus	Shipped	Symbolic differentiation, integration, optimization
Geometry	Shipped	Area, distance, convex hull, triangulation
Financial Math	Shipped	NPV, IRR, amortization, break-even
Multi-Objective	Shipped	Pareto frontier, epsilon-constraint, NSGA-II
Stochastic Processes	Shipped	Markov chains, Poisson, random walks
Survival Analysis	Shipped	Kaplan-Meier, Cox PH, survival curves
Numerical Methods	Shipped	Root finding, interpolation, quadrature
Causal Inference	Shipped	Propensity matching, DiD, doubly robust
Extended OR	Shipped	Inventory, bin packing, lot sizing, scheduling

New domains plug in as reference files without changing the core Polya workflow. See CONTRIBUTING.md for how to add a domain.

Platform Compatibility

uber-polya ships native instruction files for 8 AI coding assistants. Each tool gets the full Polya methodology through its native config format, all pointing to the shared protocol in docs/methodology.md.

Claude Code

Anthropic

CLAUDE.md + skills/*/SKILL.md

Codex

OpenAI

AGENTS.md

GitHub Copilot

GitHub / Microsoft

.github/copilot-instructions.md

Cursor

Cursor Inc.

.cursor/rules/*.mdc

Windsurf

Codeium

.windsurf/rules/*.md

Kiro

Amazon

.kiro/steering/*.md

Qoder

Alibaba

AGENTS.md

Antigravity

Google

AGENTS.md

PDF Report Output v1.1.0

uber-polya can generate professional PDF reports from any solved problem. When you invoke /uber-polya, you choose from three output formats:

Format	Deliverable	System LaTeX needed?
Python (default)	Solver script + console output + `solution.json`	No
LaTeX/PDF	`.tex` source + compiled `.pdf` report	No (uses fpdf2)
Both	Full Python output AND compiled PDF report	No

How it works

The PDF pipeline flows through three stages:

# Data flows through typed dataclasses

Phase A: FormalModel → universe, variables, constraints, objective

Phase B: SolutionReport → answer, algorithm, verification checks

Phase C: InterpretationReport → question, answer, sensitivity, figures

# Jinja2 renders LaTeX source from templates

LatexRenderer.render_tex() → report.tex

# fpdf2 + matplotlib.mathtext compile to PDF

LatexRenderer.render_pdf() → report.pdf

Report structure

Each PDF report contains branded sections matching the three Polya phases:

Section	Template	Contents
Problem Formulation	`section_model.tex.j2`	Universe, variables table, structure, mapping, constraints, objective
Solution	`section_solve.tex.j2`	Answer, metrics, algorithm, verification checks
Interpretation	`section_interpret.tex.j2`	Question, answer, explanation, sensitivity table, figures, recommendations
Appendix	`section_appendix.tex.j2`	Python solver source code (optional)

Generate from existing examples

# Generate a PDF report from any example

$ python utils/render_example.py examples/team-assignment/

Wrote: examples/team-assignment/report/report.tex

Wrote: examples/team-assignment/report/report.pdf

Done. 3 sections rendered.

Dependencies

$ pip install jinja2 fpdf2 matplotlib

# No system LaTeX installation required.

# Optional: install pdflatex for higher-quality output.

Design Principles

Socratic, not didactic

Asks questions that could have occurred to you. Guides discovery through dialogue, never lectures.

Verify everything

Every solution includes independent verification. Feasibility checks, optimality certificates, cross-validation.

Right tool for the job

Algorithm selection based on problem class and instance size. Not the fanciest algorithm — the right one.

Audience adaptation

Results adapted for technical, decision-maker, or general audiences. Same math, different communication.

Knowledge transfer

Every problem teaches a reusable modeling pattern. You learn while getting your answer.

Modular expansion

New domains plug in as reference files without changing the core workflow. The architecture grows, not changes.

FAQ

What Python packages do I need?

It depends on the problem type. ILP problems need pulp, graph problems need networkx, statistics need statsmodels and scipy. uber-polya tells you what to install when it writes solver code. Or install everything at once: pip install matplotlib numpy pulp scipy sympy networkx cvxpy z3-solver statsmodels

Can I use individual skills instead of the orchestrator?

Yes. Use /uber-model to just formalize a problem, /uber-solve to just solve a model, or /uber-interpret to just interpret a solution. Each skill's output feeds the next, but they work independently too.

What if the solver fails or the problem is infeasible?

uber-polya handles this explicitly. If a problem is infeasible, it tells you which constraints conflict. If the solver times out, it reports the best solution found so far with its gap to optimality. The common-mistakes.md reference file documents 16 anti-patterns to avoid.

How do I add a new domain?

Add algorithms to algorithms.md, structures to structures.md, interpretation patterns to interpretation-patterns.md, and at least one worked example. See CONTRIBUTING.md for the full checklist.

Does this work on platforms other than Claude Code?

Yes. uber-polya ships native config files for Claude Code, OpenAI Codex, GitHub Copilot, Cursor, Windsurf, Amazon Kiro, Qoder, and Google Antigravity. Each tool reads its own config format — all pointing to the shared methodology in docs/methodology.md. Clone the repo and the config is already in place.

How do I generate a PDF report?

When invoking /uber-polya, you'll be asked to choose an output format: Python (default), LaTeX/PDF, or Both. Choose LaTeX/PDF or Both to get a branded PDF report. You need pip install jinja2 fpdf2 matplotlib. No system LaTeX installation is required — PDF generation uses fpdf2 (pure Python). The .tex source is always saved for optional higher-quality compilation with pdflatex. You can also generate reports from existing examples with python utils/render_example.py examples/<name>/.

Is the solution really "verified"?

Yes. Every solver includes an independent verify() function that re-checks all constraints without sharing logic with the solver. For optimization problems, uber-polya also checks optimality via LP relaxation bounds or exhaustive comparison on small instances. The verification code is separate from the solver code — it's a genuine independent check.