Agent skill

First Principles Review

by GanyuanRan in GanyuanRan/Aegis

A skill your agent uses when asked for first-principles or Occam's-razor review, or when high-risk decisions involve competing constraints, fallback growth, duplicate owners, or architecture…

MITAuto-check passedDevelopment

Install First Principles Review

skills CLI
$ npx skills add GanyuanRan/Aegis --skill first-principles-review -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install GanyuanRan/Aegis first-principles-review --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/GanyuanRan/Aegis.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/first-principles-review .claude/skills/first-principles-review && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
first-principles-review
GitHub stars
1.3k
Used in
1 other repo
Token cost
~2.5k tokens
SKILL.md length
803 words
Files
1
Skills in repo
21
Repo updated
First seen
Licence
MIT

At a glance

A skill your agent uses when asked for first-principles or Occam's-razor review, or when high-risk decisions involve competing constraints, fallback growth, duplicate owners, or architecture…

  • Asked for first-principles
  • SKILL.md covers Purpose, Use When, Do Not Use and Five-Line Review, plus 4 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md
  • Occams-razor review

What it does

First Principles Review is an agent skill from GanyuanRan/Aegis. Use when asked for first-principles or Occam's-razor review, or when high-risk decisions involve competing constraints, fallback growth, duplicate owners, or architecture direction risk. Ordinary bug fixes stay on the fast path.

Its SKILL.md is about 2.5k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Development, covering Debugging. The repository describes itself as: Make AI coding agents architecture-aware: baseline-first, evidence-verified, drift-checked, and safe across long tasks. The licence is MIT.

When your agent uses it

  • Asked for first-principles
  • Occams-razor review
  • High-risk decisions involve competing constraints
  • Fallback growth

Example prompts

  • “/first-principles-review”

What it can do on your machine

Read from SKILL.md and the folder at commit 61867e9. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md.

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

First Principles Review loads about 2.5k tokens when it runs. Until then it costs about 63 tokens; SKILL.md has 803 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~63
When it runs · the whole SKILL.md, loaded when a task matches
~2.5k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from GanyuanRan/Aegis at commit 61867e9, republished under its MIT licence (© GanyuanRan). 803 words, ~2,485 tokens.

Download SKILL.mdSave it as .claude/skills/first-principles-review/SKILL.md (or your agent's skills folder).
name
first-principles-review
description
Use when asked for first-principles or Occam's-razor review, or when high-risk decisions involve competing constraints, fallback growth, duplicate owners, or architecture direction risk. Ordinary bug fixes stay on the fast path.

First Principles Review

Purpose

Use this as a lightweight decision review before another Aegis workflow makes a directional choice. It is a compositional skill, not a standalone workflow.

Do not replace brainstorming, systematic-debugging, writing-plans, requesting-code-review, or verification-before-completion. Use it to clean the decision surface those skills will act on.

When this review materially changes the direction, surface Aegis Visibility in natural prose: name the first principle, dropped assumption, smallest sufficient path, or owner / retirement falsifier that changed the decision. Keep it advisory and task-specific; do not turn the lens into approval authority or a generic skill trace.

Use When

  • The user asks for first principles, first-principles thinking, or Occam's razor.
  • A design, plan, or fix has multiple plausible paths and unclear selection criteria.
  • The task has ambiguous goals, competing constraints, or product/architecture direction risk.
  • Debugging is drifting into repeated fixes, fallback growth, duplicate owners, consumer-side patches, or "just add another branch" reasoning.
  • A review finds that the implementation may be locally correct but directionally wrong.

Do Not Use

  • Simple Q&A, status checks, tiny wording/config edits, or clearly bounded single-owner changes.
  • Mechanical execution of an approved plan unless a new directional conflict appears.
  • As a required step for every task, every turn, or every TDD cycle.

Five-Line Review

Answer only what is needed, usually in five short lines:

text
First Principle: What irreducible outcome must this satisfy?
Non-negotiables: What constraints cannot be broken?
Assumptions to Drop: What is habit, inherited shape, or unproven preference?
Smallest Sufficient Path: What is the least complex path that satisfies the first principle?
Escalation Signal: What finding would require spec/design/architecture review?

When the direction depends on a new mechanism or an unfamiliar domain, insert one optional line between path and escalation:

text
Known Prior Art: proven external pattern worth adopting or adapting to project
constraints (cite source), or `unknown` when precedent cannot be verified here

For repair choices, "smallest" means smallest sufficient stable repair, not the smallest textual diff:

text
Minimality Check:
- Smallest textual diff:
- Correct owner:
- Bug class fixed:
- New branch/fallback added:
- Old path retired or scheduled:
- Verdict: sufficient repair | local patch | needs first-principles review

Decision Hygiene Review

Use this escalation only when a design, fix, or plan needs endorsement before it is written into a spec or implementation plan.

Escalate from the five-line review when any of these risk signals appear:

  • multiple plausible paths and no clear selection criteria
  • a new owner, duplicate owner, fallback, adapter, or compat-only carrier
  • an old path that may need delete-first handling or a retirement trigger
  • an unverified assumption that the proposal depends on
  • user language such as "more elegant", "long-term stable", "first principles", or "Occam"
  • a plan could encode the wrong owner, abstraction, compatibility boundary, or retirement schedule
  • an existing object, behavior, responsibility, contract, or relationship may be reinterpreted, narrowed, replaced, or retired, and the proposal could lose a legitimate role or explicit reference while removing invalid authority

Use this compact shape:

text
First-principles invariants:
- Non-negotiable goal:
- Non-negotiable constraints:
- Historical assumptions to delete:

Bounded preservation reminder:
- Evidence-backed behavior that must remain correct:
- Highest-risk counterexample:
- Material unknown / uninspected surface:
- Known explicit anchors / upstream-downstream refs and disposition:
- Role-before-value ambiguity, if any:

Owner / retirement matrix:
- New canonical owner:
- Old owner:
- Compat-only carrier:
- Delete-first / retirement trigger:

Falsification matrix (evaluate in order; stop at the first failing gate):
- Gate 0 - Premise evidence (stage-graded): design stage accepts spec/logic
  refs; implementation/runtime stage requires log, telemetry, or test
  evidence. No evidence -> park as watch-listed, do not enter value
  evaluation.
- Gate 1 - Decidability: no obtainable evidence to judge it -> park as a
  watched falsifier, do not act.
- Gate 2 - Value (any one): lowers future fix probability / shrinks the
  solution set / exposes a missing actionable acceptance criterion / the same
  broken assumption is reused elsewhere. Passing here still requires
  gates 3-5.
- Gate 3 - Cost match: change cost vs business priority, costed at the
  current stage; a valid but deferred counterexample is recorded in the owner
  doc, never parked orally.
- Gate 4 - Goal regression: the constrained solution still meets the original
  goal; re-read the accepted-constraint list at existing checkpoints (design
  review, plan approval, pre-completion verification).
- Gate 5 - Minimize then classify: boundary-shaped destructive claims must be
  minimized first; premise attacks classify as destructive directly.
  Classes: destructive (refactor/retirement track) | supplementary (boundary
  constraint) | watch-listed (falsifier). Conflicting counterexamples are
  decided by business-goal ranking, never by stacking constraints.
- Gate 6 - Adoption trace: the cheapest checkable form (regression test for
  destructive; contract, assertion, or checklist line for supplementary),
  written into the existing owner doc.

Verdict:
- Adopt / revise / reject / needs evidence:
- Blocking gaps:
- Next evidence:
Show full SKILL.md (418 more words)Show less

Architecture Integrity Lens

Use this narrower lens when a proposal is executable but may still encode the wrong owner, abstraction, contract boundary, or retirement path. It is advisory method-pack output and may be embedded inside Decision Hygiene Review when that is enough.

Trigger it when any of these appear before approach selection, task decomposition, review, or completion-risk reporting:

  • responsibilities may overlap or a canonical owner is unclear
  • the smallest diff adds a caller-side fallback, guard, adapter, or compat-only carrier
  • an existing source-of-truth or contract could solve the class of problem at a higher level
  • a stale owner, fallback, or old path may keep carrying real logic
  • the work makes a long-term stability, "cleaner architecture", or higher-level simplification claim

Use this compact shape:

text
Architecture Integrity Lens:
- Invariant: What must remain true for the system to be coherent?
- Canonical owner / contract: Which owner, contract, or source-of-truth should carry the behavior?
- Responsibility overlap: What duplicate owner, caller-side patch, fallback, or stale path might still carry real logic?
- Higher-level simplification: Can the problem be solved at the owner / contract / source-of-truth layer instead of by another local branch?
- Retirement / falsifier: What old path retires, or what evidence would disprove this architecture judgment?
- Responsibility / capability boundary: Which invalid authority retires, and
  does the same carrier still serve a separately evidenced legitimate role?
- Verdict: proceed | revise design | split owner | return to baseline | needs ADR/baseline sync

Bounded preservation reminder is a risk-triggered reasoning aid, not a universal artifact or an exhaustive behavior inventory. Inspect the smallest relevant contract, consumer, test, or history evidence. Preserve, rebind, retire, or reject each known explicit reference; state unresolved relationships as unknown instead of re-inferring them or claiming semantic completeness. The Method Pack does not build an authoritative relationship graph, prove referential integrity or input lineage, calculate complete behavior coverage, or issue a runtime gate.

Do not run this lens for every low-risk task. If it does not change the decision surface, return to the active workflow immediately.

Composition

  • With brainstorming: run before approach selection when the request is broad, ambiguous, likely to inherit a poor product shape, or involves owner / retirement / fallback / adapter risk. Use Decision Hygiene Review or the narrower Architecture Integrity Lens before recommending or selecting an approach when those signals appear.
  • With systematic-debugging: run after evidence shows repeated fixes, fallback growth, duplicate owners, or consumer-side patching.
  • With writing-plans: run before task decomposition when the plan could encode the wrong owner, abstraction, compatibility boundary, fallback, adapter, or retirement schedule. If the approved spec did not already cover this, use Decision Hygiene Review or the Architecture Integrity Lens before writing tasks.
  • With requesting-code-review: run when review should check direction and owner integrity, not just code quality.
  • With verification-before-completion: use only to name residual directional risk. It does not grant completion authority.

Boundaries

  • Prefer evidence from current project files, baseline docs, tests, logs, and user requirements. If evidence is missing, mark the line as unknown rather than inventing a principle.
  • Keep the result advisory. This skill may recommend escalation, but it does not create authoritative GateDecision, PolicySnapshot, or completion authority.
  • If the five-line review does not change the decision surface, return to the active workflow immediately.

© GanyuanRan, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in skills/first-principles-review of GanyuanRan/Aegis.

Open the folder on GitHubat commit 61867e9

Used in 1 other repository

We found 1 copy of this SKILL.md (exact, near-identical or edited) in other folders, from 1 other GitHub owner. This page covers the copy in GanyuanRan/Aegis, which our catalogue first saw on October 7, 2026.

Compare with similar skills

First Principles Review next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

First Principles Review compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
First Principles Review this skillGanyuanRan/Aegis1.3k1 repos~2.5kAutomated safety check: PassMIT
Trellis Session Insightmindfold-ai/Trellis15k4 repos~1.7kAutomated safety check: PassAGPL-3.0
Native Data FetchingCherryHQ/cherry-studio-app4k6 repos~2.9kAutomated safety check: NotesMIT
Debugging Executionsn8n-io/n8n207k—~2.6kAutomated safety check: PassCustom licence
Aoti Debugpytorch/pytorch104k1 repos~1.7kAutomated safety check: PassCustom licence
Herdr Throwaway Reproductionherdrdev/herdr43k—~2.4kAutomated safety check: PassApache-2.0

Similar skills

  • Trellis Session Insight

    mindfold-ai/Trellis

    Reach into past AI conversation history through the trellis mem CLI.

    15k GitHub starsUsed in 4 repos~1.7k tokens
    DevelopmentAuto-check passed
  • Native Data Fetching

    CherryHQ/cherry-studio-app

    A skill your agent uses when implementing or debugging ANY network request, API call, or data fetching.

    4k GitHub starsUsed in 6 repos~2.9k tokens
    DevelopmentAuto-check: notes
  • Official

    Debug failed or wrong-output workflow executions using executions tools.

    207k GitHub stars~2.6k tokensUpdated today
    DevelopmentAuto-check passed
  • Aoti Debug

    pytorch/pytorch

    Debug AOTInductor (AOTI) errors and crashes. An agent skill from pytorch/pytorch.

    104k GitHub starsUsed in 1 repo~1.7k tokens
    DevelopmentAuto-check passed
  • Runs a disposable, uniquely named Herdr session inside an existing one so runtime, pane, terminal or API bugs can be reproduced without touching the main session.

    43k GitHub stars~2.4k tokensUpdated 2 days ago
    DevelopmentAuto-check passed
  • Systematic Debugging

    ultralisp/ultralisp

    A skill your agent uses when encountering any bug, test failure, or unexpected behavior, before proposing fixes

    258 GitHub starsUsed in 52 repos~2.4k tokens
    DevelopmentAuto-check passed

More from GanyuanRan/Aegis

All 21 skills in this repo
  • Anti Entropy Governance

    GanyuanRan/Aegis

    A skill your agent uses when touching retiring old logic, collapsing duplicate owners, removing fallbacks, or schema/persistence/source-of-truth boundaries; identify opportunities automatically…

    1.3k GitHub starsUsed in 1 repo~3.1k tokens
    Auto-check passed
  • Executing Plans

    GanyuanRan/Aegis

    A skill your agent uses when executing a written implementation plan across sessions or with review checkpoints.

    1.3k GitHub starsUsed in 1 repo~2.3k tokens
    Auto-check passed
  • Goal Framing

    GanyuanRan/Aegis

    A skill your agent uses when the user explicitly sets an Aegis goal with /aegis-goal, Aegis goal:, or asks to define goal, success evidence, stop condition, or task boundaries before work.

    1.3k GitHub starsUsed in 1 repo~1.2k tokens
    Auto-check passed
  • A skill your agent uses when the user asks to establish shared project language, or project work exposes a conflicting, renamed, or deprecated domain term that needs active semantic modeling.

    1.3k GitHub starsUsed in 1 repo~1.5k tokens
    Auto-check: warnings
  • A skill your agent uses when the user asks to create, write, update, amend, supersede, or evaluate an ADR, architecture decision record, durable architecture decision, decision log, or baseline sync…

    1.3k GitHub starsUsed in 1 repo~1.5k tokens
    Auto-check passed
  • Requesting Code Review

    GanyuanRan/Aegis

    A skill your agent uses when requesting independent code review, after implementation slices, before merging high-risk work, or when verification exposes evidence, baseline, architecture…

    1.3k GitHub starsUsed in 1 repo~2.2k tokens
    Auto-check passed

Categories

Questions about First Principles Review

What does First Principles Review do?

A skill your agent uses when asked for first-principles or Occam's-razor review, or when high-risk decisions involve competing constraints, fallback growth, duplicate owners, or architecture…. First Principles Review is an agent skill from GanyuanRan/Aegis. Use when asked for first-principles or Occam's-razor review, or when high-risk decisions involve competing constraints, fallback growth, duplicate owners, or architecture direction risk.

When should I use First Principles Review?

First Principles Review fits situations like: asked for first-principles; occams-razor review; high-risk decisions involve competing constraints; fallback growth.

How do I install First Principles Review in Claude Code?

Run `npx skills add GanyuanRan/Aegis --skill first-principles-review -a claude-code`. Or copy the skill folder (skills/first-principles-review in GanyuanRan/Aegis) into .claude/skills/first-principles-review in your project. Claude Code loads it when a task matches its description.

How do I install First Principles Review in Codex?

Run `npx skills add GanyuanRan/Aegis --skill first-principles-review -a codex`. Or copy the skill folder (skills/first-principles-review in GanyuanRan/Aegis) into .agents/skills/first-principles-review in your project. Codex loads it when a task matches its description.

Can I use First Principles Review in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add GanyuanRan/Aegis --skill first-principles-review -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/first-principles-review, .gemini/skills/first-principles-review, .github/skills/first-principles-review and .opencode/skills/first-principles-review in your project.

What does First Principles Review need to run?

SKILL.md names no scripts, command-line tools or credentials: First Principles Review is instructions for the agent only.

Does First Principles Review access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is First Principles Review safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does First Principles Review use?

First Principles Review is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does First Principles Review use?

About 2.5k tokens (SKILL.md is roughly 9.9k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to First Principles Review?

Skills that share tags, products or a category with First Principles Review: Trellis Session Insight (mindfold-ai/Trellis, 15k stars), Native Data Fetching (CherryHQ/cherry-studio-app, 4k stars), Debugging Executions (n8n-io/n8n, 207k stars) and Aoti Debug (pytorch/pytorch, 104k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains First Principles Review?

GanyuanRan (a GitHub user) maintains it in GanyuanRan/Aegis, which has 1,337 GitHub stars. The repository holds 21 skills in this directory. The repository was last updated on October 10, 2026.

Source: GanyuanRan/Aegis on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.