first-principles-review
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.
Install / Use
npx skills add GanyuanRan/Aegis --skill first-principles-reviewInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
AutomationSupported Platforms
Our assessment of first-principles-review
first-principles-review scores 92/100 on our quality scale, 895th of 2,780 Automation skills we index (top 33%).
Its SKILL.md is 9.7 KB long, well organised into 9 sections with 5 code examples: a thorough specification that gives an agent plenty to work with.
With 1,273 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated about 2 months ago, so first-principles-review is actively maintained.
- Our last check on 2026-10-27 found the source still online.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-10-04. Automated pattern scan on 2026-10-04. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
first-principles-review compared with similar skills
All 4 of these similar skills score higher than first-principles-review; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| first-principles-review (this skill)by GanyuanRan | 92 | 1.3k | 53d ago | SKILL.md |
| Agent-Reachby Panniantong | 100 | 112.3k | 8d ago | CLAUDE.md |
| rufloby ruvnet | 100 | 81.9k | today | CLAUDE.md |
| Claude-Code-Game-Studiosby Donchitos | 100 | 39.7k | 7d ago | CLAUDE.md |
| Scraplingby D4Vinci | 100 | 103.6k | 2d ago | MCP Server |
Frequently asked questions
- How do I install first-principles-review?
- Run
npx skills add GanyuanRan/Aegis --skill first-principles-review. The install tabs above show the steps for each supported agent. - Which AI agents does first-principles-review work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is first-principles-review safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is first-principles-review still maintained?
- The repository was last updated about 2 months ago, so first-principles-review is actively maintained.
Skill content
View source on GitHubname: 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:
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:
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:
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:
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:
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:
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. UseDecision Hygiene Reviewor the narrowerArchitecture Integrity Lensbefore 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, useDecision Hygiene Reviewor theArchitecture Integrity Lensbefore 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.
Related Skills
Agent-Reach
112.3kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
ruflo
81.9k🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
Claude-Code-Game-Studios
39.7kTurn Claude Code into a full game dev studio — 49 AI agents, 72 workflow skills, and a complete coordination system mirroring real studio hierarchy.
Scrapling
103.6k🕷️ The BEST Web Scraping framework that handles everything from a single request to a full-scale crawl! Don't be shy, join here: https://discord.gg/EMgGbDceNQ and follow here for daily tips and tricks: https://x.com/Scrapling_dev
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
