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.
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?
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
Use this compact shape:
First-principles invariants:
- Non-negotiable goal:
- Non-negotiable constraints:
- Historical assumptions to delete:
Owner / retirement matrix:
- New canonical owner:
- Old owner:
- Compat-only carrier:
- Delete-first / retirement trigger:
Falsification matrix:
- Dependency-removal test:
- Counterexample scenario:
- Must fail / degrade / remain correct cases:
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?
- Verdict: proceed | revise design | split owner | return to baseline | needs ADR/baseline sync
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.
1---2name: first-principles-review3description: 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.4metadata:5 source: https://skillmd.com/skills/concertonotes/first-principles-review6---78# First Principles Review910## Purpose1112Use this as a lightweight decision review before another Aegis workflow makes a13directional choice. It is a compositional skill, not a standalone workflow.1415Do not replace `brainstorming`, `systematic-debugging`, `writing-plans`,16`requesting-code-review`, or `verification-before-completion`. Use it to clean17the decision surface those skills will act on.1819## Use When2021- The user asks for first principles, first-principles thinking, or Occam's22 razor.23- A design, plan, or fix has multiple plausible paths and unclear selection24 criteria.25- The task has ambiguous goals, competing constraints, or product/architecture26 direction risk.27- Debugging is drifting into repeated fixes, fallback growth, duplicate owners,28 consumer-side patches, or "just add another branch" reasoning.29- A review finds that the implementation may be locally correct but directionally30 wrong.3132## Do Not Use3334- Simple Q&A, status checks, tiny wording/config edits, or clearly bounded35 single-owner changes.36- Mechanical execution of an approved plan unless a new directional conflict37 appears.38- As a required step for every task, every turn, or every TDD cycle.3940## Five-Line Review4142Answer only what is needed, usually in five short lines:4344```text45First Principle: What irreducible outcome must this satisfy?46Non-negotiables: What constraints cannot be broken?47Assumptions to Drop: What is habit, inherited shape, or unproven preference?48Smallest Sufficient Path: What is the least complex path that satisfies the first principle?49Escalation Signal: What finding would require spec/design/architecture review?50```5152For repair choices, "smallest" means smallest sufficient stable repair, not the53smallest textual diff:5455```text56Minimality Check:57- Smallest textual diff:58- Correct owner:59- Bug class fixed:60- New branch/fallback added:61- Old path retired or scheduled:62- Verdict: sufficient repair | local patch | needs first-principles review63```6465## Decision Hygiene Review6667Use this escalation only when a design, fix, or plan needs endorsement before it68is written into a spec or implementation plan.6970Escalate from the five-line review when any of these risk signals appear:7172- multiple plausible paths and no clear selection criteria73- a new owner, duplicate owner, fallback, adapter, or compat-only carrier74- an old path that may need delete-first handling or a retirement trigger75- an unverified assumption that the proposal depends on76- user language such as "more elegant", "long-term stable", "first77 principles", or "Occam"78- a plan could encode the wrong owner, abstraction, compatibility boundary, or79 retirement schedule8081Use this compact shape:8283```text84First-principles invariants:85- Non-negotiable goal:86- Non-negotiable constraints:87- Historical assumptions to delete:8889Owner / retirement matrix:90- New canonical owner:91- Old owner:92- Compat-only carrier:93- Delete-first / retirement trigger:9495Falsification matrix:96- Dependency-removal test:97- Counterexample scenario:98- Must fail / degrade / remain correct cases:99100Verdict:101- Adopt / revise / reject / needs evidence:102- Blocking gaps:103- Next evidence:104```105106## Architecture Integrity Lens107108Use this narrower lens when a proposal is executable but may still encode the109wrong owner, abstraction, contract boundary, or retirement path. It is advisory110method-pack output and may be embedded inside `Decision Hygiene Review` when111that is enough.112113Trigger it when any of these appear before approach selection, task114decomposition, review, or completion-risk reporting:115116- responsibilities may overlap or a canonical owner is unclear117- the smallest diff adds a caller-side fallback, guard, adapter, or compat-only118 carrier119- an existing source-of-truth or contract could solve the class of problem at a120 higher level121- a stale owner, fallback, or old path may keep carrying real logic122- the work makes a long-term stability, "cleaner architecture", or123 higher-level simplification claim124125Use this compact shape:126127```text128Architecture Integrity Lens:129- Invariant: What must remain true for the system to be coherent?130- Canonical owner / contract: Which owner, contract, or source-of-truth should carry the behavior?131- Responsibility overlap: What duplicate owner, caller-side patch, fallback, or stale path might still carry real logic?132- Higher-level simplification: Can the problem be solved at the owner / contract / source-of-truth layer instead of by another local branch?133- Retirement / falsifier: What old path retires, or what evidence would disprove this architecture judgment?134- Verdict: proceed | revise design | split owner | return to baseline | needs ADR/baseline sync135```136137Do not run this lens for every low-risk task. If it does not change the138decision surface, return to the active workflow immediately.139140## Composition141142- With `brainstorming`: run before approach selection when the request is broad,143 ambiguous, likely to inherit a poor product shape, or involves owner /144 retirement / fallback / adapter risk. Use `Decision Hygiene Review` or the145 narrower `Architecture Integrity Lens` before recommending or selecting an146 approach when those signals appear.147- With `systematic-debugging`: run after evidence shows repeated fixes, fallback148 growth, duplicate owners, or consumer-side patching.149- With `writing-plans`: run before task decomposition when the plan could encode150 the wrong owner, abstraction, compatibility boundary, fallback, adapter, or151 retirement schedule. If the approved spec did not already cover this, use152 `Decision Hygiene Review` or the `Architecture Integrity Lens` before writing153 tasks.154- With `requesting-code-review`: run when review should check direction and155 owner integrity, not just code quality.156- With `verification-before-completion`: use only to name residual directional157 risk. It does not grant completion authority.158159## Boundaries160161- Prefer evidence from current project files, baseline docs, tests, logs, and162 user requirements. If evidence is missing, mark the line as unknown rather163 than inventing a principle.164- Keep the result advisory. This skill may recommend escalation, but it does165 not create authoritative `GateDecision`, `PolicySnapshot`, or completion166 authority.167- If the five-line review does not change the decision surface, return to the168 active workflow immediately.