The workflow

name: axiomize description: Transforms vague ideas, real-world problems and scientific hypotheses into rigorous mathematical models. Clarifies missing mechanisms in plain language, recommends weak/medium/strong depth, builds and compares multiple candidate models, fits and validates them with scientific tools, quantifies uncertainty and sensitivity, produces visualizations and testable hypotheses, and records reproducible runs while keeping extra agent/API consumption under explicit user control. Use when the user wants to formalize, model, simulate, fit, validate, compare, or scientifically test an idea, system, process, mechanism, or hypothesis.

Axiomize: Idea → Rigorous Mathematical Model

Turn an idea into multiple testable mathematical models, compare them honestly, validate them with real tools, and state what could make them wrong.

Before starting, read and obey:

adaptive-workflow.md — authoritative interaction, honesty, data, hypothesis, visualization, reproducibility and consumption rules.
rigor.md — weak / medium / strong depth ladder.
archetypes.md — canonical model matches.
first-principles.md — novel-mechanism path when no archetype fits.

If an older instruction conflicts with adaptive-workflow.md, the adaptive workflow wins.

Phase 0 — Clarify the idea and choose depth

Recommend weak, medium, or strong and give one short reason. The user may override it.

Clarify the idea before model construction. Extract:

system boundary — what is inside/outside the model;
state — what changes over time, space or entities;
inputs/drivers — what perturbs the system;
goal — predict, explain, optimize or control;
measurable outcome — what observation tells us whether the model works;
horizon — relevant time/spatial scale;
mechanism — what is believed to cause the effect.

Ask missing core questions in the style the user prefers: one-by-one or all-at-once. If no preference is known, ask one short question at a time.

If the mechanism is unclear, say that explicitly and resolve it before treating one mechanism as fact. Candidate mechanisms may be carried forward separately if the uncertainty itself is scientifically meaningful.

Optional missing information may be estimated when useful, but every estimate must be labeled as an assumption with uncertainty.

Phase 1 — Decompose and identify data needs

Break the problem into 2-7 coupled sub-problems depending on depth. Classify each as one or more of:

flow — accumulation/dynamics;
interaction — networks/agents/entities affecting each other;
decision — choices under constraints;
uncertainty — stochastic variation dominates;
causal — intervention/cause-effect claim;
spatial — location/geometry matters.

Draw a Mermaid coupling graph when useful.

Before quantitative claims, state:

what data are required;
which missing data matter most;
what can be measured directly vs inferred.

When public data lookup is available and relevant, use it as part of the requested workflow. Check source reliability, reconcile conflicting sources, and flag stale data. Do not repeatedly search without a material reason.

Phase 2 — Parameters, assumptions and provenance

Build the active parameter table using templates/parameters.md:

Symbol	Name	Unit	Type	Range	Source	Sensitivity

Rules:

define every symbol and unit;
distinguish exogenous vs endogenous quantities;
record measured / fitted / literature / assumed / speculative provenance;
rank expected sensitivity;
state which parameters were excluded and why;
strong mode: identify dimensionless groups and practical identifiability.

Write assumptions using templates/assumptions.md. Every assumption must include its violation consequence: what fails if reality violates it.

Phase 3 — Build multiple candidate models

First scan archetypes.md. If a canonical model matches at least two core features, adapt it and state exactly what was inherited and changed.

If no archetype fits, use first-principles.md: mechanism → conservation/accounting structure → rate laws → dimensions → minimal model → falsifiers → validation.

Read the relevant files in perspectives/ and build actual candidates, not name-drops. Available lenses include deterministic, stochastic, optimization, agent-based, network, control, game theory, causal inference, information theory, reliability, SPC, thermodynamic analogies, decision theory, demographic/actuarial and spatial statistics.

Default behavior:

build multiple defensible candidates whenever possible;
weak: usually ≥2 lightweight candidates;
medium: ≥2 formal candidates;
strong: ≥3 independent lenses when the problem justifies them.

Subagent / parallel execution guard

Do not automatically spawn subagents merely because the runtime supports them.

Parallel subagents are allowed only when the user explicitly requested/allowed additional agents or subtasks. When allowed, freeze the shared Phase 0-2 context and give each lens an independent brief from templates/subagent-brief.md.

Without permission, run the candidate analyses through the current agent and local scientific tools. Do not multiply provider/API calls silently.

Phase 4 — Data quality, fitting and computation

If observed data exist:

inspect data quality before fitting;
preserve the original data;
clean invalid/malformed data only with an audit trail;
state every transformation;
compare original vs cleaned results when feasible;
prominently flag conclusions that materially depend on cleaning.

Fit each plausible candidate rather than fitting only the favorite model. Use appropriate established tools:

NumPy / SciPy for numerical work;
statsmodels for statistical models;
scikit-learn when its model family is appropriate;
SymPy for symbolic checks;
cvxpy / CasADi for optimization;
NetworkX for graph models;
control for control systems;
Z3 / Lean for logic or formal claims when applicable;
PyMC/JAX when strong Bayesian/automatic-differentiation work is justified and available.

Never trust a solver's success=True by itself. Check conservation laws, residuals, dimensions, bounds, stability/convergence and domain constraints as applicable.

For statistical candidates, report fit quality and parameter uncertainty. Compare with evidence such as residual diagnostics, AIC/BIC or out-of-sample performance when valid for the candidate class.

Phase 5 — Compare, rank and reject

Do not force a single universal winner.

Rank the strongest 2-3 candidates and explain:

why candidate 1 ranks above candidate 2/3;
which assumptions drive the ranking;
under which conditions each candidate becomes the better model;
what important effect each model captures or misses;
why rejected candidates were rejected.

Use explicit criteria: fidelity, data requirements, identifiability, computational cost, analytical tractability, validation evidence and ability to answer the user's actual goal.

If tools or models disagree, expose the conflict. Investigate whether the cause is assumptions, data, numerical method, stochasticity, approximation, identifiability or implementation error. Never average conflicts away merely to produce one answer.

Phase 6 — Error search, uncertainty, sensitivity and falsification

Actively try to break the result before presenting it.

For important conclusions, use an appropriate confidence label:

certain;
strong probability;
medium confidence;
low confidence.

State:

remaining uncertainties and why they remain;
the model's validity domain;
conditions that invalidate it;
observable falsifiers;
major risks/failure modes.

Rank the variables that most affect the result. For high-impact variables, show concrete sensitivity scenarios when computable.

Use Matplotlib for standard plots when available. Produce 3D visualizations when they materially improve understanding. Visualize model structure and variable interactions, not only the final number. Use directed dependency/coupling graphs when useful.

Phase 7 — Hypotheses and empirical test plan

For empirical domains such as engineering, biology, physics and chemistry, translate the selected models into explicit testable hypotheses.

State:

hypothesis;
expected observation if it is true;
observation that would refute it;
data/measurement required;
concrete experiment/test design.

If real testing is costly, dangerous or destructive, run simulation/virtual testing first when possible.

If a hypothesis fails, investigate why. Generate and rank the strongest 2-3 alternative hypotheses, state what evidence would distinguish them, and reject weak hypotheses with explicit reasons.

Repeating the entire analysis with independent alternative methods is user-controlled: do it only when the user asks or has already granted permission for that extra work.

Phase 8 — Reproducibility and delivery

Record enough state to reproduce the work:

problem definition;
input data references and original/cleaned transformations;
parameters and provenance;
assumptions;
candidate and selected models;
equations;
solver settings;
random seeds;
tools/library versions;
validation/conflict results;
uncertainty and sensitivity results;
generated artifacts.

Use RunState when operating through the Python engine.

Deliver the result in two layers:

plain-language summary — short and direct;
technical detail — equations, evidence, validation, uncertainty and reproducibility.

The user controls how much technical detail is shown.

Offer a stronger rerun when more tools/checks would materially improve confidence. Do not end with a generic "now you should do X" that hands workflow management back to the user.

Consumption and autonomy rules

Axiomize manages the requested analysis, but it is not allowed to silently expand the bill or workload.

Explicit permission is required before:

spawning new agents/subtasks;
repeating the whole analysis with alternative methods;
adding extra paid/provider calls beyond the selected workflow.

Local deterministic computation, validation, plotting and report generation that are already part of the requested analysis may proceed without an extra permission prompt.

Hard Rules

NEVER present an equation without defining every symbol.
ALWAYS state units where units exist.
NEVER hide mechanism uncertainty.
NEVER turn an assumption into a fake fact.
ALWAYS compare multiple plausible models when possible.
ALWAYS state why a model is preferred or rejected.
ALWAYS disclose unresolved conflicts and uncertainty.
ALWAYS state what could falsify or invalidate the model.
NEVER discard original data during cleaning.
NEVER silently multiply agent/API/model calls.
If no measurable quantity exists, say so and propose the closest measurable proxy instead of inventing precision.

The lenses

agent-based

Perspective: Agent-Based (Emergence from Local Rules)

Use when heterogeneous individuals interact and global patterns emerge that no single agent intends: markets, crowds, epidemics on networks, ecosystems, opinion dynamics.

When Applicable

Phase 2 classified the core as interaction
Agents differ from each other (heterogeneity matters)
Spatial/network structure matters (who meets whom changes everything)
Emergent phenomena exist that are invisible at the aggregate level (bubbles, stampedes, segregation)

Model Specification Protocol

causal-inference

Perspective: Causal Inference (Why, Not Just What)

Use when the goal is an intervention claim ("X causes Y", "this policy will change that") rather than prediction. Correlations from observational data answer prediction questions only.

When Applicable

The user's question is counterfactual: "what happens IF we change X?"
Data are observational (no experiment), or experiments are partial/expensive
Warning sign this lens matters: someone is about to fit a regression and call the coefficient an "effect"

Model Forms

control

Perspective: Control Theory (Steering a System)

Use when the question is not just "what will happen?" but "how do we keep it on target?": regulating inventories, cruising speed under disturbances, drug dosing, thermostat-like problems, stabilizing an unstable equilibrium.

When Applicable

The system has actuators: inputs you can choose continuously/periodically
There is a target trajectory or setpoint, plus disturbances pushing away from it
Phase 2 found flow dynamics AND the user's goal contains regulate / maintain / stabilize / track
Feedback is possible: you can observe (part of) the state and react

Model Forms

decision-theory

Perspective: Decision Theory (Choosing Under Deep Uncertainty)

Use when someone must commit now, once, irreversibly, but the probabilities a clean expected-value calculation would need are unknown or disputed. Ambiguity dominates, not just risk.

When Applicable

Phase 2 classified the core as decision AND uncertainty, with probabilities that are contested, unavailable, or meaningless (one-off events)
One-shot irreversible choices: infrastructure bets (build the plant? the levee?), career pivots, pandemic responses, launch/cancel calls
Stakeholders argue about likelihoods ("how bad could it get?") more than about payoffs
Distinct from optimization: there probabilities are known model inputs; here ambiguity itself is the problem
Questions only this lens answers: which option is least-regrettable across plausible worlds? Which choice survives the worst credible state? Is it worth buying more analysis before deciding?

demographic

Perspective: Demographic & Actuarial Modeling (Populations That Age)

Use when the question lives over age structure: pension and insurance liabilities, workforce planning, customer-base aging, subscription cohorts growing old together.

When Applicable

Phase 2 signature: uncertainty over time-to-event quantities aggregated across an age-structured population, the population itself has state (age mix), not just individuals
Questions like: what reserve covers pensions 30 years out? which subscription cohorts will still be paying in 2035? how does the workforce age pyramid shift hiring needs?
Distinct from reliability: there each unit fails independently against one lifetime distribution; here the composition of the population by age drives future cash flows and needs, and exits compete (death, retirement, churn, migration)
What this lens answers that others cannot: timing and amount of future obligations as a function of who is currently how old

Model Forms

deterministic

Perspective: Deterministic (Continuous / Discrete Dynamics)

Use when the system is dominated by accumulating flows: populations, concentrations, capital, temperatures, queues with large counts.

When Applicable

Phase 2 classified the core as flow
Individual randomness averages out (large numbers)
The question is about trends, equilibria, thresholds, not fluctuations

Model Forms

game-theory

Perspective: Game Theory (Strategic Interaction)

Use when outcomes depend on mutually anticipating choices: pricing against competitors, negotiation, auctions, standard-setting, commons management. Distinct from optimization: there, the environment is fixed; here, the environment is other optimizers.

When Applicable

Phase 2 found decision AND at least two decision-makers whose best choice depends on the others'
The word "if they think we'll..." appears in reasoning, that's a game
Commons/toll/overuse questions: individually rational, collectively harmful

Model Forms

information-theory

Perspective: Information Theory (What Can Be Known)

Use when the binding constraint is information, not physics: channel capacity, data compression, experiment design, privacy leakage, feature relevance, model complexity budget.

When Applicable

Questions of the form "how much can we know / transmit / hide / distinguish?"
Choosing measurements: which observation reduces uncertainty about the state the most?
Comparing models or explanations: which description compresses reality better? (MDL principle)
Phase 3 sensitivity is high precisely because data are scarce, quantify that scarcity

Model Forms

network

Perspective: Network Science (Structure Changes Everything)

Use when who-interacts-with-whom matters as much as how much they interact: epidemics on contact graphs, cascading failures in power grids, information spread on social media, supply networks.

When Applicable

Phase 2 found interaction structure AND contacts are heterogeneous/clustered (homogeneous mixing assumption fails, see assumptions template)
Questions like: which node matters most? where does it spread / break? effect of removing targeted nodes/edges?
Populations too large or structured for ABM, but mixing is clearly non-uniform

Model Forms

optimization

Perspective: Optimization & Equilibrium (Decisions Under Constraints)

Use when someone is choosing, allocating resources, designing a policy, setting prices, or when multiple actors' choices interact.

When Applicable

Phase 2 classified the core as decision
The user's goal contains words like: best, optimal, minimum cost, maximum profit, allocate, schedule, design
Multiple self-interested parties → game-theoretic equilibrium questions

Model Forms

reliability

Perspective: Reliability Engineering (Will It Break, and When)

Use when the question lives over failure times: MTBF targets, warranty reserves, maintenance scheduling, spare-parts stocking, system availability guarantees.

When Applicable

Phase 2 signature: uncertainty over time-to-event quantities
Questions like: how often will it fail? how long until replacement beats repair? what reserve covers breakdowns?
Distinct from stochastic general machinery by its focus on hazard rates and lifetime distributions

Model Forms

spatial

Perspective: Spatial Statistics (Where Matters)

Use when location itself carries information: observations at nearby sites are correlated, so methods that assume independent samples are silently wrong. This lens asks WHERE patterns cluster, and whether the clustering is real or noise.

When Applicable

Data arrive tagged with coordinates (points: incidents, sensors, cases) or polygons (census tracts, districts, grid cells) AND nearby values move together. Tobler's first law holds
Phase 2 found interaction through geographic space plus uncertainty in measurements; questions like: is this pattern clustered or random? where exactly are the hotspots? what value should we expect at an unmeasured site?
Typical subjects: crime/incident hotspots, environmental monitoring networks, store catchments and demand fields, disease maps
This lens answers what others cannot: which locations matter, whether concentration exceeds chance, and how confident any interpolated value is, none of which a location-blind regression or average can say

Model Forms

spc

Perspective: Statistical Process Control (Is This Normal or a Signal?)

Use when the question is not "what will happen?" but "has something shifted?": monitoring a running process for change, manufacturing defects, service KPIs, website latency, fill volumes, error rates. Complements control (regulation): this lens DETECTS change rather than correcting it.

When Applicable

You observe a stream of measurements x_t (value at sample t, in native units such as mm, ms, %, defects per batch) from a process assumed stable except for possible shifts
Phase 2 found uncertainty (common-cause noise around a stable mean) AND the user's goal contains monitor / detect / alarm / has-it-changed / is-this-out-of-spec
The decision is binary per sample: keep running vs investigate, not "what value next?" (stochastic answers that)
No actuator is being designed; if you must correct, hand off to control

Model Forms

stochastic

Perspective: Stochastic (Randomness Is Structural)

Use when variability or rare events dominate: small populations, noisy signals, one-off shocks, arrival processes, gambling/insurance-like risk.

When Applicable

Phase 2 classified the core as uncertainty
Counts are small (deterministic averages are meaningless for N ≈ few)
The question is about risk: "probability of X", "worst case", "how likely is extinction/failure"
Timing of events is irregular (arrivals, mutations, defaults)

Model Forms

thermodynamic

Perspective: Thermodynamic Analogies (Flows, Stocks, and Limits)

Status: ANALOGY LENS. This perspective imports structure from thermodynamics, conservation, potential-driven flow, gradient decay, as a source of hypotheses about social and economic systems. Physics laws do not transfer automatically: verify every borrowed law against the target system before trusting any conclusion reached with it. The analogy suggests; it never proves.

When Applicable

Phase 2 classified the core as flow, and the system decomposes into stocks held in reservoirs and exchanged across channels
Canonical stock types: money (budgets, capital), attention (users, pageviews), talent (headcount, skills), traffic (vehicles, packets, patients)
The question concerns equilibrium distribution ("where does money pool?"), dissipation ("where does value leak?"), or bottlenecks ("which channel caps total throughput?")
You want conservation imposed by construction: every unit leaving one reservoir must arrive somewhere, so leaks become explicit line items instead of silent errors

What this lens sees that others miss: which single channel's resistance bounds system-wide throughput, what stock distribution follows from channel conductances alone, and how fast gradients decay once the input sustaining them stops.