first-principles-review

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:

   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.