First Principles Thinking
chrisdavidson/first-principles-skill
Decomponha problemas em verdades fundamentais e raciocine a partir delas
Ver no GitHubSkill que implementa uma metodologia sistemática de raciocínio a partir de primeiros princípios. Decompõe problemas em verdades fundamentais verificadas, desafiando suposições e construindo soluções do zero. Ideal para decisões de design, estratégia de produto e análises onde convenção não é justificativa suficiente.
Instalação
npx convez-ai chrisdavidson/first-principles-skill1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Questionar e validar decisões arquiteturais de software
- Avaliar propostas de produto descartando raciocínio por analogia
- Analisar designs desafiando suposições implícitas e explícitas
- Aplicar pré-mortém em iniciativas estratégicas
- Justificar decisões sem apelar a precedentes
Veredito

Skill rigoroso e bem estruturado para quem precisa ir além de suposições. A metodologia de cinco fases (essência, desafio de suposições, verdades fundamentais, raciocínio ascendente, validação) é sólida e auditável — excelente para análises críticas onde o rigor intelectual é o diferencial.
README
A tradução para o português deste README ainda está na fila.
First Principles Thinking
A Claude Code plugin that gives Claude a systematic methodology for decomposing any problem into verified fundamental truths and reasoning upward from there. Use it when you want analysis that traces every conclusion back to a ground truth rather than reasoning by analogy or convention — for software design decisions, product strategy, or any domain where "we've always done it this way" is not a sufficient justification.
When to use it
Trigger the agent when you find yourself asking:
- "Challenge the assumptions behind this design"
- "Is this the right approach, or are we just following convention?"
- "Why are we doing it this way — what are the actual ground truths?"
- "Evaluate this architectural decision from first principles"
- "Justify this decision without appealing to how others have solved it"
- "Apply a pre-mortem to this proposal"
- "Is our reasoning sound, or have we reasoned by analogy?"
Claude will also route to the agent automatically when you ask it to think from scratch, question a design, or avoid reasoning by analogy — without requiring the explicit phrase "first principles."
The methodology
The agent applies a five-phase procedure. Each phase produces a named artifact; that artifact is the entry condition for the next phase — the chain is what makes the analysis auditable.
Phase 1 — Identify Essence: Strips away implementation details, historical framing, and symptoms to expose the core question. Produces an Essence Statement — a single sentence naming the real problem plus a checkable list of success criteria.
Phase 2 — Challenge Assumptions: Identifies every assumption (explicit and implicit), classifies each by type (physical law / current constraint / convention / untested belief), and applies the prescribed treatment per type. Produces a Classified Assumptions Table. Unchallenged assumptions that are false propagate invisibly through every later step — this phase closes that path.
Phase 3 — Establish Ground Truths: Compiles the verified facts that survived Phase 2 scrutiny. Each fact carries a stable GT-ID and a source citation. Unverified inputs may be included but are marked GT-N? and inherit a confidence caveat. Produces the Ground Truths list.
Phase 4 — Reason Upward: Constructs answers from the ground truths using whatever reasoning approach the problem calls for — derivation is free-form but must be self-documenting. Dead-end paths are recorded, not quietly discarded. Produces Derivation Chains in the format GT-N + GT-M → [intermediate claim] → [conclusion].
Phase 5 — Validate: Adversarial pass over the completed chains. Finds the weakest link in each chain, checks whether unverified assumptions are load-bearing, and applies a validation rubric as a systematic gate. Produces the Signed-off analysis — the complete output document with all conclusions traced and all weak links either resolved or explicitly flagged.
For the complete procedure with entry/exit criteria per phase and the exact output document structure, see first-principles/agents/first-principles.md. The agent body is the authoritative spec — the summary above orients; it defines.
Companion tools
Eleven tools extend the methodology when the analysis calls for them. The six companion-reference tools ship both as on-demand reference siblings of the agent (loaded automatically when the relevant trigger fires) and as standalone slash-only skills for direct invocation (/first-principles:<name>). The five focused-mode phase skills are slash-only stubs for direct phase invocation:
- Five Whys (
/first-principles:five-whys) — Root-cause drill-down procedure. Use it during Phase 3 when an analysis is stuck on why something is true and the surface explanation feels insufficient. - Fishbone (Ishikawa) (
/first-principles:fishbone) — Breadth-first cause-category brainstorm. Use it during Phase 2 (Challenge Assumptions) when the assumption space is multi-causal and intuition cannot enumerate it confidently. Branches enter the Classified Assumptions Table asuntested beliefrows; reach for Five Whys instead when the problem is single-chain depth. - Inversion (
/first-principles:inversion) — Failure-enumeration procedure. Use it during Phase 2 (Challenge Assumptions) when a conclusion feels too clean; enumerate what would guarantee failure and hand each unverified precondition back to the Classified Assumptions Table as anuntested beliefrow. - Pre-mortem (
/first-principles:pre-mortem) — Prospective-hindsight failure analysis. Use it during Phase 5 to stress-test a proposed solution by imagining it has already failed and working backward to the failure modes. - Trade-off Analysis (
/first-principles:trade-off) — Weighted-criteria decision procedure. Use it during Phase 4 when multiple viable options remain after ground truths are established. Criteria are weighted before scoring to prevent post-hoc rationalization. - Second-Order Thinking (
/first-principles:second-order) — Downstream-consequence extension procedure. Use it during Phase 4 (Reason Upward) to extend a Derivation Chain with 2nd/3rd-order effects before handing off to Phase 5; contradicting effects route back to Phase 2 for re-challenging. - Identify Essence (
/first-principles:identify-essence) — Phase 1 focused-mode stub. Invoke directly to strip framing artifacts and expose the core question; produces an Essence Statement with success criteria. - Challenge Assumptions (
/first-principles:challenge-assumptions) — Phase 2 focused-mode stub. Invoke directly to classify and test every assumption (physical law / constraint / convention / untested belief) before reasoning upward. - Ground Truths (
/first-principles:ground-truths) — Phase 3 focused-mode stub. Invoke directly to compile GT-ID-anchored verified facts for use as derivation-chain inputs. - Reason Upward (
/first-principles:reason-upward) — Phase 4 focused-mode stub. Invoke directly to build derivation chains upward from named ground truths; records dead-end paths explicitly. - Validate (
/first-principles:validate) — Phase 5 focused-mode stub. Invoke directly to stress-test each derivation chain for weak links and apply the validation rubric before presenting conclusions.
Worked examples
Eleven domain-spread examples show the methodology applied end-to-end, each with a real dead-end and a validation rubric pass:
- Software and systems — Evaluating a microservices migration decision for a monolithic codebase, tracing the actual constraints and ground truths rather than following distributed-systems fashion.
- Product and business — Deciding whether to build a new pricing tier, decomposing the business assumptions and grounding the recommendation in verified market and unit-economics facts.
- Personal and general — Evaluating a career transition, separating the real constraints from conventions and untested beliefs about what the options actually are.
- Science and engineering — Choosing a materials approach for a physical product, grounding the trade-offs in verified physical properties rather than industry convention.
- Ishikawa fishbone — A worked fishbone-style cause-category brainstorm; branches hand back to Phase 2's Classified Assumptions Table as
untested beliefrows. - Composed Inversion + Second-Order — A worked analysis combining Inversion at Phase 2 with Second-Order Thinking at Phase 4; demonstrates the hand-back semantics for both tools and the route-back-to-Phase-2 path on contradicting downstream effects.
- Software and systems 2 — Build vs. Buy software decision: build own auth or adopt a managed identity provider.
- Product and business 2 — Feature prioritization under a binding engineering-capacity constraint.
- Personal and general 2 — Mortgage paydown vs. index investment: a quantitative expected-value analysis.
- Science and engineering 2 — In-service mechanical component failure analysis (diagnostic reasoning shape).
- Self-application — Meta: applying the methodology to a contested design decision about the agent itself (agent body length vs. scope).
Relationship to the original
This project is a fork and enhancement of github.com/chrisdavidson/first-principles-skill, MIT licensed, authored by the same person. The original is a complete, working skill with a 5-phase methodology, a standardized output format, multilingual triggers (English + Chinese), and worked examples.
The v3.8 enhanced successor adds four things the original does not have:
- Validation rubric — a scoring/self-check the model applies after Phase 5 to verify the analysis met the rigor bar, with explicit criteria, levels, and a gate that blocks presenting conclusions until the rubric clears.
- Eleven companion tools — Five Whys, fishbone, inversion, pre-mortem, trade-off analysis, and second-order thinking as fully described on-demand reference siblings of the agent, each with when-to-use guidance tied to a specific phase of the 5-phase spine; plus five focused-mode phase stubs (identify-essence, challenge-assumptions, ground-truths, reason-upward, validate) for direct phase invocation.
- Eleven domain-spread worked examples — software/systems, product/business, personal/general, science/engineering, ishikawa fishbone, and composed inversion + second-order, each demonstrating a real dead-end and a complete validation pass.
- Sharpened 5-phase methodology — explicit entry and exit criteria per phase, named artifacts with stable IDs, a stakes-escalation rule for assumptions, and derivation chain format requirements that close the gaps where the original is loose.
Install
Install the plugin and invoke the agent:
# Local development install:
claude --plugin-dir ./first-principles
# In a Claude Code session:
@agent-first-principles:first-principles
# or explicitly:
/first-principles:first-principles
Or install via the Claude Code plugin marketplace — no clone required:
/plugin marketplace add chrisdavidson/first-principles-skill
/plugin install first-principles@first-principles-skill
Verify with /doctor inside Claude Code; the first-principles agent should appear in the listing.
The v2.x dual install (root monolith + 7 namespaced plugin skills) was removed in v3.0.0. In v3.8.0, eleven companion-tool slash-only skills were re-added under first-principles/skills/ — these are standalone direct-invoke skills, not the full plugin-skill surfaces from v2.x. See CHANGELOG.md for the full upgrade path.
Project-scoped install
The plugin can also be installed into a single project (committed to that repo's VCS) by placing it under .claude/plugins/ inside the project. Use this when a team wants the agent version-controlled with a specific codebase.
Builder
An interactive CLI that generates a candidate SKILL.md or agent .md from templates. By default, generated files land in generated/<slug>.md — they are candidates ready for review. Passing --install copies the candidate into shared/ and regenerates the plugin surface automatically (see Install flag below).
python3 main.py
uv run main.py
Prompts
| Prompt | What it collects | Constraints / Notes |
|---|---|---|
| Select artifact type | skill or agent | Accepts 1 or skill; 2 or agent; loops until valid |
| Name | The skill/agent name | Required, non-empty; cannot contain the reserved words anthropic or claude; output filename slug is derived from this (lowercased, spaces to hyphens) |
| Description | Description surface text | Required, non-empty; maximum 1024 chars |
| Trigger phrases | One phrase per line, blank line to finish | Skill-only — not asked when building an agent |
Output
The rendered candidate is written to generated/<slug>.md in the repo root, where <slug> is the lowercased, hyphenated name. The generated/ directory is created automatically. If a file with that name already exists, the builder prompts before overwriting.
Validation
After writing the file, main.py prints an advisory Validation: section:
check-description-budget— warns if the description surface exceeds 2000 chars (skill artifacts).check-trigger-collisions— warns if the description shares a 4-gram with an installed skill (skill artifacts).check-agent— runs structural checks fromscripts/check-agent.py(agent artifacts only).
Validation is advisory — the candidate file stays in generated/ regardless of PASS/FAIL and main.py exits 0. Under --install, validation becomes a hard block: a FAIL aborts the install before any file is written to shared/.
Install flag
Passing --install promotes the generated candidate directly into the source-of-truth tree and regenerates the plugin surface:
python3 main.py --install
Copy → sync behavior. After generating the candidate, --install copies it to its shared/ destination and then runs python3 scripts/sync-content.py --write to regenerate the first-principles/ plugin surface:
- Skills land at
shared/skills/<slug>/SKILL.md(the<slug>/subdirectory is created as needed). - Agents land at
shared/agent/<slug>.md(a flat file).
Conflict policy. If the target path already exists under shared/, the install aborts with exit 1 and prints the conflicting path. No file is overwritten — source-of-truth content is protected. Resolve the conflict manually before re-running with --install.
Rollback on sync failure. If sync-content.py --write exits non-zero, the just-copied shared/ file is deleted (rollback), the sync error is printed to stderr, and the builder exits 1 — leaving shared/ in its pre-install state so the pre-commit sync-drift gate does not fire.
Agent-manifest caveat. Installing an agent writes shared/agent/<slug>.md but does NOT register the agent in the plugin manifest (first-principles/.claude-plugin/plugin.json). sync-content.py regenerates only the canonical first-principles agent, so declaring a new agent in the manifest is a separate manual step.
Contributing
Canonical content lives in shared/. The agent surface (first-principles/agents/first-principles.md) and its on-demand reference siblings under first-principles/agents/references/ are generated from shared/ by scripts/sync-content.py. Edit shared/ — never the generated agent tree directly.
One-time setup — opt into the pre-commit drift gate (recommended):
git config core.hooksPath .githooks
With the gate on, every git commit runs scripts/sync-content.py --check and fails the commit if shared/ and the generated agent tree have drifted. Remediation:
python3 scripts/sync-content.py --write && git add -u
Python requirement: the sync script needs Python ≥ 3.12 and PyYAML. Easiest is uv run scripts/sync-content.py --check (install uv); alternatively pip install --user 'pyyaml>=6.0' and use plain python3.
The hook opt-in is per-clone (Git does not propagate core.hooksPath automatically), so each contributor configures it once locally.
One-time setup — opt into the body-budget pre-commit hook (recommended):
./scripts/install-hooks.sh
The installer symlinks scripts/git-hooks/pre-commit into .git/hooks/pre-commit (preserving any existing hook as .bak on first run, idempotent on re-run). The hook blocks commits that would push the generated agent body (first-principles/agents/first-principles.md) over the ~500-line target. Bypass for intentional in-progress work: git commit --no-verify.
Why a 500-line budget: keeps the generated agent body under ~500 lines so it loads quickly into model context and stays under Claude Code's recommended budget for skill body length.
Note: the body-budget installer composes BOTH gates (body budget + sync drift) into a single
.git/hooks/pre-commit, so contributors who use the installer do not also need thecore.hooksPath = .githooksopt-in above. Conversely,.githooks/pre-commitnow also runs the body-budget check, so either opt-in path gives full coverage. The two mechanisms are mutually exclusive at the Git level (Git honors one hooks path or the other); pick whichever you prefer. The installer prints a WARNING if it detectscore.hooksPathis set.
Testing the agent
The first-principles agent's routing (when it should and shouldn't auto-delegate) is tested via a reproducible headless battery: scripts/check-routing.py --catalog tests/routing-catalog.md issues each prompt through claude -p and scores DELEGATE / NO-DELEGATE from the stream-json event stream. Sequential execution against a fresh session per prompt; exit code 0 iff the P-case and N-case thresholds are both met.
The underlying methodology (why stream-json is required, the two-signal detection rule, jq extraction strategies, and the --permission-mode bypassPermissions requirement) is documented in docs/testing-agents-headlessly.md. For the battery thresholds and the pass criterion, see tests/routing-catalog.md.
License
MIT. See LICENSE.