Skip to main content
skill CX Codex

first-principles-review · sno-ai — Claude Code skill: what it does

The first-principles-review Claude Code skill challenges product ideas, PRDs, and architecture using first-principles reasoning. It runs only when explicitly named and writes a local review with a PRD handoff.

Apache-2.0 ★ 869 updated 2026-11-16

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add sno-ai/sno-station-skills --skill first-principles-review -a claude-code
Open on GitHub

What first-principles-review does

The skill researches the proposal, tests its assumptions, and compares alternatives before the idea turns into requirements or code. It writes a separate Markdown report with a structured handoff for a PRD author. It does not edit the target PRD or start another skill automatically.

Two scripts in scripts validate the report and extract the handoff: validate-report.py and extract-prd-handoff.py. Both require python3. The skill also needs shell access and permission to read and write files; it leaves the reviewed input unchanged. Its default report path is reports/<input-stem>-first-principles-review.md, with a different filename used if that path already exists. Invocation must be explicit.

What it helps with

  • test a product proposal's assumptions before PRD drafting
  • compare a proposed architecture with existing options
  • separate hard constraints from inherited assumptions
  • record alternatives and evidence that could overturn a recommendation
  • prepare review findings for a PRD author

Example prompts for the agent

  • Run $first-principles-review on the idea in proposal.md and write a report.
  • Use /first-principles-review to assess design.md against the current approach.
  • Run first-principles-review on this PRD and prepare a handoff for its author.

How to install first-principles-review

1Skills CLI (Vercel)

npx skills add sno-ai/sno-station-skills --skill first-principles-review -a claude-code

2Manually: put the files in place

~/.claude/skills/first-principles-review/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/first-principles-review/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about first-principles-review

How do I install first-principles-review in Claude Code?

Run npx skills add sno-ai/sno-station-skills --skill first-principles-review -a claude-code. The skill file is placed at ~/.claude/skills/first-principles-review/SKILL.md.

What does first-principles-review do?

It researches a product idea, PRD, or architecture, challenges its assumptions, and compares possible directions. The output is a local Markdown review with a handoff block for PRD writing.

Does first-principles-review require Python?

Yes. The report validator and handoff extractor both need python3.

Source text

SKILL.md · Apache-2.0
---
name: first-principles-review
description: "MANUAL-ONLY: challenge a product idea, design, PRD, or architecture from first principles. Use only when the user names this skill. Research first, then write a local review and PRD handoff."
requires:
  programs: []
  harness:
    - {slot: 4.shell, need: required}
    - {slot: 4.file-read-write, need: required}
---

# First-Principles Reviewer

Run before a proposal hardens into requirements or source code. The owner is whoever owns the
work and decides what it should be; often that is the user. A PRD is a product requirements
document. Judge the problem framing,
constraints, and solution shape. Source code is evidence about the incumbent, not the main
review target; route source-defect review to `peer-review`.

## Invocation Gate

Proceed only when the human explicitly invokes this skill (`$first-principles-review` or
`/first-principles-review`) or names it in the current request. Do not infer invocation from the presence of a PRD or design.

## Workflow

1. **Freeze the boundary.** Identify the input, record its hash when it is a file, choose a
   local report path, and do not modify the reviewed input. Use
   `reports/<input-stem>-first-principles-review.md` unless the human names another path.
   Use a distinct report filename when the default already exists. If a named input is
   missing or unreadable, locate the canonical artifact, repair access within authority,
   and continue the review. Work on independent evidence meanwhile; ask only for an
   input that only the owner can supply. Never invent the missing artifact or claim
   a completed review without reading it.
2. **Research before challenging.** Read the relevant product intent, prior decisions,
   incumbent behavior, immediate code/design dependencies, and current external solutions.
   Record every source and every material gap. When current external facts matter, browse.
   Stop when another source cannot change a premise state, the disposition, or the next
   evidence-producing action. Record that stopping boundary.
3. **Re-derive the outcome.** State what the user or system must achieve without borrowing
   the proposed implementation.
4. **Classify constraints.** Mark each claim as `hard constraint`, `owner preference`, or
   `inherited assumption`. Cite evidence. A physical, legal, published-contract, measured
   economic, or explicit owner limit may be hard; familiarity is not.
5. **Challenge premises.** Build a ledger of load-bearing premises. Mark each
   `evidence-backed`, `unproven`, `inherited`, or `falsified`. Apply removal, inversion,
   substitution, do-nothing, and incumbent comparison where they can change the decision.
   A settled owner decision stays settled unless a specific new fact changes its basis. Name
   that fact before challenging the ruling; never relabel the ruling as inherited.
6. **Construct real alternatives.** Consider eliminating the need, reusing an incumbent or
   native capability, making the smallest viable change, and redesigning from true
   constraints. Include only materially distinct candidates. Do not force novelty or a
   candidate count.
7. **Choose a disposition.** Use exactly one: `PROCEED`, `REFRAME`, `SIMPLIFY`, `REPLACE`,
   `SPLIT`, `TEST-FIRST`, or `STOP`. For `SPLIT`, record at least two independently
   buildable outcomes inside the single handoff object. `PROCEED` means evidence is strong
   enough to enter PRD authoring, not to skip implementation or production verification.
   Use `TEST-FIRST` only when a missing fact could change the problem framing or selected
   direction before PRD authoring. Repeated benchmarks and rollout checks belong in acceptance
   implications or falsifiers and do not by themselves block `PROCEED`.
8. **Recommend one direction.** Compare the current proposal and surviving alternatives on
   outcome fit, complexity, failure surface, reversibility, time to evidence, and migration
   cost. Name observable evidence that would overturn the recommendation.
9. **Write and validate the report.** Follow `references/report-contract.md`, including its
   embedded JSON handoff. Run:

   ```bash
   python3 <skill-dir>/scripts/validate-report.py <report.md>
   python3 <skill-dir>/scripts/extract-prd-handoff.py <report.md> > <handoff.json>
   ```

   `<skill-dir>` is the folder that contains this SKILL.md. Both scripts need `python3`.

10. **Ask only after the report exists.** Keep questions out of the report. If a genuine
    owner decision survives research, ask one decision at a time in chat. Otherwise hand the
    report and extracted block to whoever writes the PRD (a PRD-writing skill, if one is installed).

## Judgment Rules

- By default this review is one pass (a project may choose otherwise): do not rerun it to confirm
  edits, and do not turn its output into a new review target. Whoever acts on the report records
  how each recommendation was handled, proves fixes deterministically, and continues.
- The report is the record of the review. Do not prewrite or self-author a `PROCEED` result
  before this workflow has inspected the evidence.
- Verified fact, inference, and unknown are different claims. Label them separately.
- A recommendation without falsifiers is advocacy, not review.
- No research or no challenged premise is an instrument failure, not a clean result.
- `PROCEED` means the proposal survived meaningful challenge; it does not mean exhaustive
  proof or production readiness.
- Preserve rejected alternatives and why they lost so the PRD author does not re-derive them.
- When existing source is supplied, use it to establish incumbent behavior, constraints, and
  coupling. Route source defects to `peer-review`.
- The report is bounded and non-exhaustive. Say so explicitly.

## Output

Create one independent local Markdown report. Report the exact path. Do not edit a target PRD
or automatically invoke a PRD skill. The embedded handoff is the downstream contract; prose
remains the human record.

© sno-ai · Apache-2.0 · sno-ai/sno-station-skills

Similar skills

All skills for Design →

first-principles-review by other authors comes first.

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-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 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-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 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 design-principles gotalab The design-principles rule sets checks for architecture, types, documentation, and Mermaid diagrams. Use it when drafting design.md or reviewing component boundaries. CX Codex +1 ★ 3,774repo stars spec-driven-development addyosmani The spec-driven-development Claude Code skill drafts a specification before coding begins. It activates for vague requirements, new features, project plans, and changes to an existing spec. CX Codex +1 81,900installs

From the same set40

The whole set →
rust-coder The rust-coder Claude Code skill implements and refactors Rust code using the project’s own conventions. It activates for feature work, migrations, and substantial edits to .rs files or Cargo.toml. CX Codex +1 ★ 869repo stars python-coder The python-coder skill for Claude Code guides Python implementation and refactoring, including work with FastAPI and Pydantic. It applies to async code and migration tasks. CX Codex +1 ★ 869repo stars owner-intent-audit The owner-intent-audit Claude Code skill checks plans, tests, and code against the project owner’s intent. Run it before approving or merging agent work. CX Codex +1 ★ 869repo stars less-is-more less-is-more — a skill for Claude Code that keeps code changes small and trims overbuilt solutions. It activates for coding, bug fixes, refactors, and diff reviews. CX Codex +1 ★ 869repo stars e2e-red-triage The e2e-red-triage Claude Code skill classifies an unexpected end-to-end test failure as a product defect or an environment fault. Load it manually after the suite runner identifies a specific failure. CX Codex +1 ★ 869repo stars e2e-environment-preflight The e2e-environment-preflight Claude Code skill checks external dependencies before an end-to-end run. It loads only when named or in the specified planning and test-workflow situations. CX Codex +1 ★ 869repo stars charter This Claude Code skill writes, revises, or reviews a charter that defines deliverables, boundaries, and success checks. It runs when work needs a written brief before an executor starts. CX Codex +1 ★ 869repo stars agentic-walkthrough The agentic-walkthrough Claude Code skill checks whether a successful run produced its intended effect. It traces the path from entry point to outcome and looks for evidence at each step. CX Codex +1 ★ 869repo stars

Project sponsors

Companies that keep this analytics open