
thinking-first-principles
When a constraint is treated as fixed, separate physics from convention, keep only independently supported primitives, and rebuild the simplest solution that satisfies real constraints.
- Installs
- 714
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/tjboudreaux/cc-thinking-skills --skill thinking-first-principles- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads thinking-first-principles automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
First Principles
Strip assumed constraints to independently supported primitives, then rebuild. Escape analogy when convention fails or looks artificially expensive.
When to Use
- A constraint is treated as fixed ("too expensive," "impossible," "always done this way") without independent support.
- Convention or analogy has failed, stalled, or only yields weak incremental variants.
- Greenfield design where industry defaults may smuggle false requirements.
- Cost or feasibility claims rest on pricing, precedent, or authority rather than physics, math, or measured need.
When NOT to Use
- The constraint is verified physics, hard regulation, or measured capacity → accept it and optimize within it.
- A proven standard library, protocol, or known-good pattern already fits → use it; do not re-derive.
- Time-critical incidents → act on the most likely cause first; reserve first-principles rebuild for post-incident redesign.
- Incremental polish of a working system with no false-constraint signal → skip.
Procedure
- State the problem and claimed constraints. List every limit treated as fixed (cost, scale, stack, process, "must use X").
- Classify each constraint. Tag as
physics/math,regulation/contract,measured fact, orconvention/analogy/authority. Keep only the first three as binding unless evidence upgrades a convention. - Decompose to primitives. Required inputs, conservation/complexity bounds, true non-negotiables. Demand independent support (measurement, derivation, primary requirement)—not vendor pricing or competitor precedent.
- Discard unsupported assumptions. For each convention tag, state a falsifier. Drop or renegotiate anything lacking support.
- Rebuild from remaining primitives only. Simplest solution that satisfies binding constraints and ignores artificial ones. Prefer commodity inputs and fewer moving parts over analogy.
- Validate and stop. Check against real physics, contracts, and measured needs. Define the cheapest kill test. Stop when a coherent rebuild plus discriminating validation exists, or when only verified hard constraints remain.
Output
Emit a first-principles rebuild:
claimed_constraints: list with classification tagsprimitives: independently supported truths onlydiscarded_assumptions: conventions dropped and whyrebuild: solution derived only from primitivesbinding_residuals: real limits that remainkill_test: cheapest check that would falsify the rebuild
Verification
- Independence check: every primitive must cite measurement, derivation, or primary requirement—not precedent alone.
- No smuggled analogy: if the rebuild still depends on "how others do it" without a primitive, strip it.
- Constraint honesty: verified physics/regulation must remain; do not wish them away.
- Over-application guard: if a standard solution is already optimal under verified constraints, do not rebuild for novelty.
- Stop: one decompose → classify → rebuild → kill-test pass; do not recurse without new evidence.
FAQ
What does the thinking-first-principles skill do?
When a constraint is treated as fixed, separate physics from convention, keep only independently supported primitives, and rebuild the simplest solution that satisfies real constraints.
How do I install thinking-first-principles?
Run npx skills add https://github.com/tjboudreaux/cc-thinking-skills --skill thinking-first-principles in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/thinking-first-principles/ (personal) or .claude/skills/thinking-first-principles/ (project).
Which AI agents can use thinking-first-principles?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is thinking-first-principles safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains thinking-first-principles?
It is published by tjboudreaux in tjboudreaux/cc-thinking-skills. It has 714 recorded installs.
More from tjboudreaux/cc-thinking-skills
thinking-red-team
tjboudreaux/cc-thinking-skills
For authorized security review of code, auth, or APIs you control, model the attacker, map the attack surface, and report only findings with a reproducible exploit path and verified mitigation.
thinking-pre-mortem
tjboudreaux/cc-thinking-skills
Before committing to a plan or launch, assume it already failed and reason backward through concrete causes — convert failure paths into mitigations, gates, and stop checks.
thinking-theory-of-constraints
tjboudreaux/cc-thinking-skills
When throughput or latency is pipeline-limited, identify the single binding constraint and exploit, subordinate, elevate, then recheck—ignore non-constraints.
thinking-socratic
tjboudreaux/cc-thinking-skills
When a request is vague, assumption-laden, or "obvious," ask the few load-bearing questions that expose hidden requirements before building or committing.
thinking-opportunity-cost
tjboudreaux/cc-thinking-skills
Before committing scarce time, people, or money, name the best forgone use of those resources and the value delta of the chosen path versus that alternative.
thinking-systems
tjboudreaux/cc-thinking-skills
When behavior is emergent across components—fixes elsewhere break, loops/delays dominate—map boundary, stocks/flows, feedback, archetypes, then rank leverage.
Popular education & science skills
teach
mattpocock/skills
Teach the user a new skill or concept, within this workspace.
scaffold-exercises
mattpocock/skills
Create exercise directory structures with sections, problems, solutions, and explainers that pass linting. Use when user wants to scaffold exercises, create exercise stubs, or set up a new course section.
paper-context-resolver
lllllllama/rigorpilot-skills
Rigor Paper Context helper for README-first deep learning repo reproduction. Use only when the README and repository files leave a narrow reproduction-critical gap and the task is to resolve a specific paper detail such as dataset split, preprocessing, evaluation protocol, checkpoint mapping, or runtime assumption from primary paper sources while recording conflicts. Do not use for general paper summary, repo scanning, environment setup, command execution, title-only paper lookup, or replacing README guidance by default.
caveman-learn
juliusbrussee/caveman
Act on a Caveman learn report - review the ranked token sinks, apply cost-lowering fixes with per-edit consent, and report what those fixes returned. Use when asked to lower an agent's token cost, what caveman has saved, to trim a heavy CLAUDE.md, or to offload re-pasted context into cavemem.
gsap-plugins
greensock/gsap-skills
Official GSAP skill for GSAP plugins — registration, ScrollToPlugin, ScrollSmoother, Flip, Draggable, Inertia, Observer, SplitText, ScrambleText, SVG and physics plugins, CustomEase, EasePack, CustomWiggle, CustomBounce, GSDevTools. Use when the user asks about a GSAP plugin, scroll-to, flip animations, draggable, SVG drawing, or plugin registration.
teach-impeccable
pbakaus/impeccable
DEPRECATED: Use /impeccable teach instead. This command has been folded into the impeccable skill.