{"id":"4898e833-c3ab-415e-8884-e47010d63bd4","shortId":"rWBp6C","kind":"skill","title":"first-principles-review","tagline":"Use when the user explicitly asks for first principles, first-principles review, Occam's razor, 第一性原理, 奥卡姆剃刀, or when a complex decision has ambiguous goals, competing constraints, repeated fixes, fallback growth, duplicate owners, or architecture/product direction risk.","description":"# First Principles Review\n\n## Purpose\n\nUse this as a lightweight decision review before another Aegis workflow makes a\ndirectional choice. It is a compositional skill, not a standalone workflow.\n\nDo not replace `brainstorming`, `systematic-debugging`, `writing-plans`,\n`requesting-code-review`, or `verification-before-completion`. Use it to clean\nthe decision surface those skills will act on.\n\n## Use When\n\n- The user asks for first principles, first-principles thinking, 第一性原理,\n  Occam's razor, or 奥卡姆剃刀.\n- A design, plan, or fix has multiple plausible paths and unclear selection\n  criteria.\n- The task has ambiguous goals, competing constraints, or product/architecture\n  direction risk.\n- Debugging is drifting into repeated fixes, fallback growth, duplicate owners,\n  consumer-side patches, or \"just add another branch\" reasoning.\n- A review finds that the implementation may be locally correct but directionally\n  wrong.\n\n## Do Not Use\n\n- Simple Q&A, status checks, tiny wording/config edits, or clearly bounded\n  single-owner changes.\n- Mechanical execution of an approved plan unless a new directional conflict\n  appears.\n- As a required step for every task, every turn, or every TDD cycle.\n\n## Five-Line Review\n\nAnswer only what is needed, usually in five short lines:\n\n```text\nFirst Principle: What irreducible outcome must this satisfy?\nNon-negotiables: What constraints cannot be broken?\nAssumptions to Drop: What is habit, inherited shape, or unproven preference?\nSmallest Sufficient Path: What is the least complex path that satisfies the first principle?\nEscalation Signal: What finding would require spec/design/architecture review?\n```\n\n## Decision Hygiene Review\n\nUse this escalation only when a design, fix, or plan needs endorsement before it\nis written into a spec or implementation plan.\n\nEscalate from the five-line review when any of these risk signals appear:\n\n- multiple plausible paths and no clear selection criteria\n- a new owner, duplicate owner, fallback, adapter, or compat-only carrier\n- an old path that may need delete-first handling or a retirement trigger\n- an unverified assumption that the proposal depends on\n- user language such as \"more elegant\", \"long-term stable\", \"长期稳定\",\n  \"first principles\", \"Occam\", or \"奥卡姆\"\n- a plan could encode the wrong owner, abstraction, compatibility boundary, or\n  retirement schedule\n\nUse this compact shape:\n\n```text\nFirst-principles invariants:\n- Non-negotiable goal:\n- Non-negotiable constraints:\n- Historical assumptions to delete:\n\nOwner / retirement matrix:\n- New canonical owner:\n- Old owner:\n- Compat-only carrier:\n- Delete-first / retirement trigger:\n\nFalsification matrix:\n- Dependency-removal test:\n- Counterexample scenario:\n- Must fail / degrade / remain correct cases:\n\nVerdict:\n- Adopt / revise / reject / needs evidence:\n- Blocking gaps:\n- Next evidence:\n```\n\n## Composition\n\n- With `brainstorming`: run before approach selection when the request is broad,\n  ambiguous, likely to inherit a poor product shape, or involves owner /\n  retirement / fallback / adapter risk. Use `Decision Hygiene Review` before\n  recommending or selecting an approach when those signals appear.\n- With `systematic-debugging`: run after evidence shows repeated fixes, fallback\n  growth, duplicate owners, or consumer-side patching.\n- With `writing-plans`: run before task decomposition when the plan could encode\n  the wrong owner, abstraction, compatibility boundary, fallback, adapter, or\n  retirement schedule. If the approved spec did not already cover this, use\n  `Decision Hygiene Review` before writing tasks.\n- With `requesting-code-review`: run when review should check direction and\n  owner integrity, not just code quality.\n- With `verification-before-completion`: use only to name residual directional\n  risk. It does not grant completion authority.\n\n## Boundaries\n\n- Prefer evidence from current project files, baseline docs, tests, logs, and\n  user requirements. If evidence is missing, mark the line as unknown rather\n  than inventing a principle.\n- Keep the result advisory. This skill may recommend escalation, but it does\n  not create authoritative `GateDecision`, `PolicySnapshot`, or completion\n  authority.\n- If the five-line review does not change the decision surface, return to the\n  active workflow immediately.","tags":["first","principles","review","aegis","ganyuanran","add","agent-skills","ai-agents","ai-coding","baseline-first","claude-code","codex"],"capabilities":["skill","source-ganyuanran","skill-first-principles-review","topic-add","topic-agent-skills","topic-ai-agents","topic-ai-coding","topic-baseline-first","topic-claude-code","topic-codex","topic-coding-agents","topic-evidence-driven","topic-first-principles","topic-opencode","topic-software-architecture"],"categories":["Aegis"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/GanyuanRan/Aegis/first-principles-review","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add GanyuanRan/Aegis","source_repo":"https://github.com/GanyuanRan/Aegis","install_from":"skills.sh"}},"qualityScore":"0.581","qualityRationale":"deterministic score 0.58 from registry signals: · indexed on github topic:agent-skills · 262 github stars · SKILL.md body (4,306 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-18T18:54:49.386Z","embedding":null,"createdAt":"2026-05-09T06:55:45.282Z","updatedAt":"2026-05-18T18:54:49.386Z","lastSeenAt":"2026-05-18T18:54:49.386Z","tsv":"'abstract':388,532 'act':100 'activ':655 'adapt':337,481,536 'add':160 'adopt':447 'advisori':623 'aegi':56 'alreadi':546 'ambigu':29,136,468 'anoth':55,161 'answer':224 'appear':206,322,496 'approach':461,492 'approv':199,542 'architecture/product':40 'ask':10,106 'assumpt':251,359,412 'author':591,639 'authorit':634 'baselin':599 'block':452 'bound':190 'boundari':390,534,592 'brainstorm':74,458 'branch':162 'broad':467 'broken':250 'cannot':248 'canon':419 'carrier':342,426 'case':445 'chang':194,648 'check':184,565 'choic':61 'clean':93 'clear':189,328 'code':83,559,572 'compact':396 'compat':340,389,424,533 'compat-on':339,423 'compet':31,138 'complet':89,578,590,638 'complex':26,269 'composit':65,456 'conflict':205 'constraint':32,139,247,410 'consum':155,513 'consumer-sid':154,512 'correct':173,444 'could':383,527 'counterexampl':438 'cover':547 'creat':633 'criteria':132,330 'current':596 'cycl':219 'debug':77,144,500 'decis':27,52,95,284,484,550,650 'decomposit':523 'degrad':442 'delet':350,414,428 'delete-first':349,427 'depend':363,435 'dependency-remov':434 'design':121,293 'direct':41,60,142,175,204,566,584 'doc':600 'drift':146 'drop':253 'duplic':37,152,334,509 'edit':187 'eleg':370 'encod':384,528 'endors':298 'escal':276,289,309,628 'everi':212,214,217 'evid':451,455,503,594,607 'execut':196 'explicit':9 'fail':441 'fallback':35,150,336,480,507,535 'falsif':432 'file':598 'find':166,279 'first':2,12,15,43,108,111,235,274,351,376,400,429 'first-principl':14,110,399 'first-principles-review':1 'five':221,231,313,643 'five-lin':220,312,642 'fix':34,124,149,294,506 'gap':453 'gatedecis':635 'goal':30,137,406 'grant':589 'growth':36,151,508 'habit':256 'handl':352 'histor':411 'hygien':285,485,551 'immedi':657 'implement':169,307 'inherit':257,471 'integr':569 'invari':402 'invent':617 'involv':477 'irreduc':238 'keep':620 'languag':366 'least':268 'lightweight':51 'like':469 'line':222,233,314,612,644 'local':172 'log':602 'long':372 'long-term':371 'make':58 'mark':610 'matrix':417,433 'may':170,347,626 'mechan':195 'miss':609 'multipl':126,323 'must':240,440 'name':582 'need':228,297,348,450 'negoti':245,405,409 'new':203,332,418 'next':454 'non':244,404,408 'non-negoti':243,403,407 'occam':18,115,378 'old':344,421 'outcom':239 'owner':38,153,193,333,335,387,415,420,422,478,510,531,568 'patch':157,515 'path':128,264,270,325,345 'plan':80,122,200,296,308,382,519,526 'plausibl':127,324 'policysnapshot':636 'poor':473 'prefer':261,593 'principl':3,13,16,44,109,112,236,275,377,401,619 'product':474 'product/architecture':141 'project':597 'propos':362 'purpos':46 'q':181 'qualiti':573 'rather':615 'razor':20,117 'reason':163 'recommend':488,627 'reject':449 'remain':443 'remov':436 'repeat':33,148,505 'replac':73 'request':82,465,558 'requesting-code-review':81,557 'requir':209,281,605 'residu':583 'result':622 'retir':355,392,416,430,479,538 'return':652 'review':4,17,45,53,84,165,223,283,286,315,486,552,560,563,645 'revis':448 'risk':42,143,320,482,585 'run':459,501,520,561 'satisfi':242,272 'scenario':439 'schedul':393,539 'select':131,329,462,490 'shape':258,397,475 'short':232 'show':504 'side':156,514 'signal':277,321,495 'simpl':180 'singl':192 'single-own':191 'skill':66,98,625 'skill-first-principles-review' 'smallest':262 'source-ganyuanran' 'spec':305,543 'spec/design/architecture':282 'stabl':374 'standalon':69 'status':183 'step':210 'suffici':263 'surfac':96,651 'systemat':76,499 'systematic-debug':75,498 'task':134,213,522,555 'tdd':218 'term':373 'test':437,601 'text':234,398 'think':113 'tini':185 'topic-add' 'topic-agent-skills' 'topic-ai-agents' 'topic-ai-coding' 'topic-baseline-first' 'topic-claude-code' 'topic-codex' 'topic-coding-agents' 'topic-evidence-driven' 'topic-first-principles' 'topic-opencode' 'topic-software-architecture' 'trigger':356,431 'turn':215 'unclear':130 'unknown':614 'unless':201 'unproven':260 'unverifi':358 'use':5,47,90,102,179,287,394,483,549,579 'user':8,105,365,604 'usual':229 'verdict':446 'verif':87,576 'verification-before-complet':86,575 'wording/config':186 'workflow':57,70,656 'would':280 'write':79,518,554 'writing-plan':78,517 'written':302 'wrong':176,386,530 '奥卡姆':380 '奥卡姆剃刀':22,119 '第一性原理':21,114 '长期稳定':375","prices":[{"id":"b6b4fc64-6717-4cdb-916b-833d0e7091f2","listingId":"4898e833-c3ab-415e-8884-e47010d63bd4","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"GanyuanRan","category":"Aegis","install_from":"skills.sh"},"createdAt":"2026-05-09T06:55:45.282Z"}],"sources":[{"listingId":"4898e833-c3ab-415e-8884-e47010d63bd4","source":"github","sourceId":"GanyuanRan/Aegis/first-principles-review","sourceUrl":"https://github.com/GanyuanRan/Aegis/tree/main/skills/first-principles-review","isPrimary":false,"firstSeenAt":"2026-05-09T06:55:45.282Z","lastSeenAt":"2026-05-18T18:54:49.386Z"}],"details":{"listingId":"4898e833-c3ab-415e-8884-e47010d63bd4","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"GanyuanRan","slug":"first-principles-review","github":{"repo":"GanyuanRan/Aegis","stars":262,"topics":["add","agent-skills","ai-agents","ai-coding","architecture-driven-development","baseline-first","claude-code","codex","coding-agents","evidence-driven","first-principles","opencode","software-architecture","tdd","tlref"],"license":"mit","html_url":"https://github.com/GanyuanRan/Aegis","pushed_at":"2026-05-18T11:05:01Z","description":"Make AI coding agents architecture-aware: baseline-first, evidence-verified, drift-checked, and safe across long tasks.","skill_md_sha":"e00dcf8a655136de0fe06d30e361c4185a9bb85a","skill_md_path":"skills/first-principles-review/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/GanyuanRan/Aegis/tree/main/skills/first-principles-review"},"layout":"multi","source":"github","category":"Aegis","frontmatter":{"name":"first-principles-review","description":"Use when the user explicitly asks for first principles, first-principles review, Occam's razor, 第一性原理, 奥卡姆剃刀, or when a complex decision has ambiguous goals, competing constraints, repeated fixes, fallback growth, duplicate owners, or architecture/product direction risk."},"skills_sh_url":"https://skills.sh/GanyuanRan/Aegis/first-principles-review"},"updatedAt":"2026-05-18T18:54:49.386Z"}}