Claude Skill

first-principles-review

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.

LLM Mart · 0 points · 2 views 0 listing impressions 0 install-command copies
Download sno-ai-sno-station-skills-plugins_sno-station-standalone_skills_first-principles-review-8ff231c.zip · 21 KB

Install

skills CLI npx skills add https://github.com/sno-ai/sno-station-skills/tree/main/plugins/sno-station-standalone/skills/first-principles-review
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install sno-ai-sno-station-skills@llmmart
Git git clone https://github.com/sno-ai/sno-station-skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole sno-ai/sno-station-skills collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

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.

Files (sno-station-skills)
  • agents
    • openai.yaml 353 B
      Loading…
  • references
    • report-contract.md 3.2 KB
      Loading…
  • scripts
    • selftest
      • fixtures
        • scenarios
          • inherited-constraint-test-first.md 2.1 KB
            Loading…
          • raw-idea-reframe.md 2.1 KB
            Loading…
          • sound-design-proceed.md 2 KB
            Loading…
        • expected-handoff.json 1.9 KB
          Loading…
        • target-prd.md 347 B
          Loading…
        • valid-report.md 3.9 KB
          Loading…
      • run-extractor-test.sh 1.9 KB
        Loading…
      • run-scenarios.sh 3.2 KB
        Loading…
      • run-selftest.sh 4.9 KB
        Loading…
      • verify-manual-only.sh 2.8 KB
        Loading…
      • verify-workflow-policy.sh 1.8 KB
        Loading…
    • extract-prd-handoff.py 1.1 KB
      Loading…
    • validate-report.py 9.6 KB
      Loading…
  • SKILL.md 5.9 KB
    ---
    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.
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.