convez.ai
SkillProdutividadeAvançado
chrisdavidson

First Principles Thinking

chrisdavidson/first-principles-skill

Decomponha problemas em verdades fundamentais e raciocine a partir delas

Ver no GitHub
InicialPluginScore · de 0 a 100

Skill 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-skill

1 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

Estrelas
2
Forks
0
Acompanhando
0
Saúde
57%
Último commit
há 1 mês
Versão
v9.21.0
Issues abertas
0
Contribuidores
2

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 as untested belief rows; 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 an untested belief row.
  • 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 belief rows.
  • 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:

  1. 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.
  2. 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.
  3. 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.
  4. 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.

Validation

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

PromptWhat it collectsConstraints / Notes
Select artifact typeskill or agentAccepts 1 or skill; 2 or agent; loops until valid
NameThe skill/agent nameRequired, non-empty; cannot contain the reserved words anthropic or claude; output filename slug is derived from this (lowercased, spaces to hyphens)
DescriptionDescription surface textRequired, non-empty; maximum 1024 chars
Trigger phrasesOne phrase per line, blank line to finishSkill-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 from scripts/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 the core.hooksPath = .githooks opt-in above. Conversely, .githooks/pre-commit now 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 detects core.hooksPath is 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.

Ver o original no GitHub

Bom para

Relacionados