// Use when reviewing a software design for first-principles alignment. Triggers on: "review this design", "evaluate this design", "design review", "is this design sound", or when a user shares a design doc/spec for feedback.
| name | design |
| description | Use when reviewing a software design for first-principles alignment. Triggers on: "review this design", "evaluate this design", "design review", "is this design sound", or when a user shares a design doc/spec for feedback. |
| argument-hint | [target file or description] |
You are performing a First Principles Design Review. Your goal is to evaluate whether a software design follows from the actual problem's fundamentals or from inherited assumptions and conventions. Apply the five-phase framework with heavy emphasis on decomposition and assumption surfacing.
Determine what design to review:
$ARGUMENTS contains a file path, read it with the Read tool. If the path is ambiguous, use Glob to resolve it.$ARGUMENTS contains a description or pasted content, use it as the design under review.$ARGUMENTS is empty and the codebase has relevant files, ask: "What design would you like me to review? Share a file path, paste the design, or describe it." Suggest candidate files if you find specs, RFCs, or design docs via Glob (e.g., **/*design*, **/*spec*, **/*rfc*, **/docs/**).$ARGUMENTS is empty and there is no codebase context, go to the Edge Cases section.Once you have the design input:
Read and follow the framework. Execute all five phases in sequence. Below are phase-specific instructions for design review.
Go deep here. This is the most important phase for design review.
This phase distinguishes a first-principles review from a conventional review.
Produce an "ideal shape" — given only the fundamentals from Phases 1-2, what should this design look like?
Compare the ideal shape against the proposed design. Note convergences and divergences.
Draw primarily from these principles in the catalog:
Apply additional principles from the catalog when your Phase 1-3 findings make them relevant. Flag tensions between principles and reason about which takes priority in this context.
Use the Assessment Report template from output-templates.
Deliver a gap analysis between the proposed design and what first-principles reasoning suggests. For each gap, state whether the design choice is assumption-driven or fundamentals-driven.
Include a "What's Working Well" section. Identify design choices that are genuinely well-aligned with the problem's fundamentals. This is not a criticism tool — it is an alignment tool.
Frame Socratic questions to help the designer see tradeoffs and make informed decisions. Avoid questions that imply a single correct answer.
Conclude with numbered, concrete recommendations ordered by severity. Each recommendation must state what to do, why (traced to a principle or fundamental), and what it costs.
Empty invocation, no codebase context: Offer all four modes with brief descriptions:
/fp:design — Review a software design for first-principles alignment (recommended starting point)/fp:architecture — Evaluate system structure, boundaries, and communication patterns/fp:plan — Build a project or feature plan grounded in fundamentals/fp:code — Review implementation code against first principlesAsk what the user would like to review.
Empty invocation, codebase present: Search for design-relevant files (specs, RFCs, docs, ADRs). Present candidates and ask which design to review. If none found, ask the user to share or describe a design.
Input looks like code, not design:
State: "This looks like implementation code rather than a design. /fp:code is built for code review — would you like to switch? I can proceed with a design-level review of the code's implicit design if you prefer."
Input looks like architecture (service boundaries, deployment topology, infrastructure):
State: "This looks like it's at the architecture level — system boundaries, deployment, infrastructure. /fp:architecture is tuned for that. I'll proceed with a design review, but an architecture review may surface more relevant findings. Want to switch?"
Input too large to analyze fully: Identify the most critical components (highest coupling, most assumptions, most complex). Analyze those in full depth. State explicitly what was analyzed and what was skipped, with a brief rationale for the prioritization. Offer to review skipped sections separately.
Use when reviewing code for first-principles alignment — structural and logical issues, not style. Triggers on: "review this code from first principles", "first principles code review", or when the user wants deeper-than-surface code analysis.
Use when evaluating software architecture decisions from first principles. Triggers on: "review this architecture", "evaluate architecture", "architecture review", "are these service boundaries right", or when discussing system-level structure.
Use when planning a new project or feature using first-principles thinking. Triggers on: "plan this feature", "design from scratch", "greenfield", "what should we build", or when starting something new and wanting a principled foundation.