Skip to main content
subagent CX Codex

first-principles-thinking · voltagent/awesome-codex-subagents — Codex subagent: setup

The first-principles-thinking subagent strips a problem down to basic facts, tests its assumptions, and rebuilds the solution. Use it when the current approach may be misleading.

MIT ★ 6,505 updated 2026-10-05

Install into Codex · Manually: put the files in place All methods and platforms ↓
.codex/agents/first-principles-thinking.toml
Open on GitHub

What first-principles-thinking does

The subagent restates the problem without carrying over the current solution, then inventories assumptions about technology, process, business, and users. It tests the evidence behind each one and marks it valid, invalid, or partially valid.

It then identifies technical constraints, actual user needs, and economic realities. The output includes 2–3 rebuilt directions, tradeoffs across impact, effort, risk, and reversibility, plus a recommended next step with an owner. Operational work can follow the Define, Diagnose, Diverge, Decide, Deploy pass. It does not default to small tweaks when the existing approach rests on untested assumptions unless the parent agent asks for that.

What it helps with

  • restate a problem without solution framing
  • test assumptions across technology, process, and users
  • identify constraints and underlying needs
  • compare 2–3 rebuilt directions by risk and effort
  • assign an owner to the next step

Example prompts for the agent

  • Break this problem down from first principles, separate facts from assumptions, and propose 2–3 directions.
  • Audit the current approach, list every assumption, and give each one a validity verdict.
  • Rebuild the solution from the underlying constraints and include the consequences of doing nothing.

How to install first-principles-thinking

Manually: put the files in place

.codex/agents/first-principles-thinking.toml

Codex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/

Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean

Questions about first-principles-thinking

How do I install first-principles-thinking in Codex?

Add the subagent file to Codex at .codex/agents/first-principles-thinking.toml. Then run Codex in the project.

What does first-principles-thinking do?

It restates a problem, challenges inherited assumptions, identifies fundamental constraints, and develops several solution paths before recommending a next step.

How does the subagent evaluate assumptions?

It checks the evidence, considers what changes if an assumption is reversed, and labels the assumption valid, invalid, or partially valid.

Source text

first-principles-thinking.toml · MIT
# first-principles-thinking

Use when a task needs assumptions challenged, a complex problem broken down to fundamentals, or a solution rebuilt from scratch rather than from convention or analogy.

Own first-principles reasoning: reduce a problem to irreducible truths and rebuild solutions from the ground up.

Strip solution framing and inherited assumptions before proposing any direction.

Working mode:
1. Define the problem precisely, removing embedded solution language.
2. List every assumption baked into the current approach (technology, process, business, user).
3. Challenge each assumption: is it true, what evidence supports it, what changes if reversed.
4. Identify the fundamental truths that remain, then rebuild the simplest solution from them.

Focus on:
- problem restatement that targets the real outcome, not the current mechanism
- explicit assumption inventory across technology, process, business, and user dimensions
- evidence test for each assumption with a valid / invalid / partially valid verdict
- fundamental truths: physical/technical constraints, true user needs, economic realities
- "what would a new entrant with no legacy build" as a rebuild lens
- structured 5D pass (Define, Diagnose, Diverge, Decide, Deploy) for operational problems
- evaluation on impact, effort, risk, and reversibility before committing

Quality checks:
- confirm the restated problem is free of solution framing
- verify each assumption has an explicit verdict and supporting reasoning
- ensure at least 2-3 rebuilt directions are generated before recommending one
- check that recommendations trace back to fundamental truths, not convention
- include a "do nothing" option and its consequences where relevant

Return:
- problem restated in first-principles language
- challenged assumptions with verdicts
- fundamental truths identified
- 2-3 rebuilt solution directions with tradeoffs
- recommended next step with owner

Do not default to incremental tweaks of the existing approach when the assumptions behind it are unproven unless explicitly requested by the parent agent.

© VoltAgent · MIT · VoltAgent/awesome-codex-subagents

Similar subagents

All subagents for Agent setup: memory, context, orchestration →

first-principles-thinking by other authors comes first.

first-principles-thinking VoltAgent Community first-principles-thinking deconstructs problems down to irreducible truths and removes legacy assumptions. Useful when conventional fixes fail or when designing an architecture from scratch. CX Codex ★ 26,718repo stars thinking-first-principles tjboudreaux thinking-first-principles — a skill for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode that separates real constraints from inherited convention and rebuilds from primitives. CX Codex +1 844installs first-principles Lex Christopherson first-principles deconstructs problems down to irreducible truths, removes conventions, and designs solutions from the ground up. CX Codex +1 ★ 1,988repo stars principle-redesign-from-first-principles backnotprop principle-redesign-from-first-principles — a skill that makes the agent rebuild an existing design as if the new requirement had been there from day one. Use it when a change ripples through types, docs, and examples. CX Codex +1 10,200installs first-principles-review GanyuanRan first-principles-review is a Claude Code skill that checks decisions against first principles and Occam's razor before an agent locks in a direction. It skips ordinary bug fixes. CX Codex +1 ★ 1,450repo stars thinking-second-order tjboudreaux thinking-second-order traces consequences beyond an immediate fix, including reactions, timing, probability and feedback. Use it for architecture or strategic decisions with lasting effects. CX Codex +1 717installs thinking-partner mattnowdev thinking-partner — a skill that pushes back on your assumptions and picks mental models for the problem at hand. Useful when you are stuck on a decision or want a plan stress-tested. CX Codex +1 564installs

From the same set176

The whole set →
scientific-literature-researcher scientific-literature-researcher gathers published research, checks sample sizes and methodologies, and synthesizes findings weighted by study quality. CX Codex ★ 6,505repo stars research-analyst research-analyst — a Codex subagent for structured technical research, source checks, and confidence-rated conclusions. Use it when an implementation or design decision needs evidence. CX Codex ★ 6,505repo stars project-idea-validator project-idea-validator — a Codex subagent that hunts fatal flaws in a product idea — rivals, demand, moat — and returns a kill, pivot or proceed call before you build. CX Codex ★ 6,505repo stars market-researcher market-researcher runs market and competitor research for technical product decisions. Helps evaluate build-vs-buy trade-offs, switching costs, and positioning. CX Codex ★ 6,505repo stars docs-researcher docs-researcher — a subagent that verifies APIs, version-specific behavior and framework options against official documentation. CX Codex ★ 6,505repo stars data-researcher The data-researcher subagent for Codex gathers and synthesizes datasets, metrics, and quantitative evidence for engineering and product decisions, rather than dumping raw links. CX Codex ★ 6,505repo stars competitive-analyst competitive-analyst compares tools, products, libraries, and implementation options against criteria for a specific decision. Useful when adoption and maintenance matter as much as features. CX Codex ★ 6,505repo stars cohort-analysis cohort-analysis — a subagent for diagnosing product health via retention curves and user cohort behavior. Separates product-market-fit problems from growth issues and identifies activation moments that predict long-term engagement. CX Codex ★ 6,505repo stars

Project sponsors

Companies that keep this analytics open