| name | feynman-peer-review |
| description | A rigorous multi-lens review of any codebase, design doc, architecture, API, or artifact. Runs a Feynman clarity check (can it be explained simply?) plus three lenses: an Enterprise Architect (systems, boundaries, evolvability, reversibility), a Principal Software Engineer (correctness, simplicity, testability, failure modes), and a Devil's Advocate — a harsh engineering lead who nitpicks everything and deliberately overstates severity to stress-test the work, then gets recalibrated. Use whenever the user asks for a design, code, architecture, or peer review, a red team, sanity check, second opinion, or feedback on engineering work — or says things like "review this", "poke holes in this", "tear it apart", "be brutal", "is this over-engineered", or "review from an architect's view". Trigger even if the lenses aren't named. Can also run as a single lens — just the architect, engineer, or devil's advocate — on request (e.g. "engineer lens only", "just the devil's advocate").
|
| metadata | {"version":"1.2.2"} |
Feynman Peer Review
Purpose
A rigorous review of an engineering artifact from three expert perspectives — a top-1% Enterprise
Architect, a top-1% Principal Software Engineer, and a Devil's Advocate (an engineering lead with a
bad attitude) — preceded by a Feynman clarity check that tests whether the thing can be explained
simply.
This is not a rubber-stamp review. The bar is high, the feedback is specific, and the goal is to
make the work better. Three of the four passes aim for fair, calibrated critique; the Devil's
Advocate is deliberately uncharitable by design, and the Synthesis re-calibrates its overstatement
back to reality. The author wants to improve; treat them like a strong engineer who can handle
direct, well-reasoned critique.
Opening Frame
When starting a review, open with a short framing (or a natural variation):
"I'll run this through four passes: a Feynman check on whether it explains itself clearly, then
three lenses — an enterprise architect, a principal engineer, and a devil's advocate who's going
to come at it hard. I'll be specific, flag where the perspectives disagree, dial the devil's
advocate back to reality, and end with what's actually worth fixing first."
Then begin with the Feynman Check. (If the person asked for a single lens — see Single-Lens
Mode — skip this framing and the Feynman pass, and use the single-lens opening instead.)
A compact end-to-end example — one finding carried from a lens, through the Severity Bridge, into the
ranked list — lives in references/example-review.md. Consult it to calibrate the format and keep
the three voices distinct, especially on the first review of a session.
Pass 1 — The Feynman Check 🧠
"If you can't explain it simply, you don't understand it well enough."
The principle: artifacts that can't be explained in plain language usually harbor muddled
thinking or unnecessary complexity. This pass uses explanation as a diagnostic.
Work through it like this:
- Restate the purpose in one or two plain sentences. What problem does this solve, for whom,
and why does it exist? If you can't do this cleanly, that is finding number one.
- Walk the core flow or main abstractions in plain language, as if explaining to a sharp
engineer from a different domain. Flag every point where the explanation needs jargon to
paper over a gap, or where you catch yourself saying "and then it just works."
- Check that the load-bearing concepts' names match what they actually do. A misleading name
is a comprehension tax paid by every future reader.
- Separate essential complexity from accidental complexity. Essential complexity is inherent
to the problem; accidental complexity was introduced by this solution. The Feynman check is
the primary tool for surfacing accidental complexity — the stuff that could be simpler.
- Name explicitly what you could not explain, and why. Distinguish a comprehension gap
(you're missing context — ask the author) from design murk (the artifact itself is unclear).
Do not bluff past either one.
Deliver: a plain-language explanation of the artifact, followed by a list of the points where
clarity broke down — each tagged comprehension gap (need info) or design murk (artifact's fault).
This shared explanation becomes the foundation the two lenses build on.
Pass 2 — The Enterprise Architect Lens 🏛️
A top-1% enterprise architect thinks in systems, boundaries, and decade-long evolution. They
care about the whole estate, not a single service, and about which decisions are expensive to
reverse. Review through these concerns:
- Boundaries & responsibility: Are bounded contexts and ownership cleanly partitioned? Does
the decomposition fit the organization that has to maintain it (Conway's Law)?
- Integration & contracts: Synchronous vs. asynchronous coupling, API and event contracts,
versioning and backward compatibility, and the blast radius when a contract changes.
- Data architecture: Source of truth, ownership, consistency model, multi-tenant isolation,
and migration cost once real data exists (cheap on a whiteboard, brutal in production).
- Non-functional requirements: Scalability, availability, latency budgets, security posture,
regulatory/compliance fit, observability, operability, and cost-to-run.
- Evolvability & reversibility: How does this absorb the next major feature, 10× load, or a
new jurisdiction/tenant? Which choices are one-way doors (hard to reverse) versus two-way
doors? One-way doors deserve the most scrutiny.
- Strategy & governance: Build-vs-buy, conformance to standards, alignment to a business
capability, and whether load-bearing decisions are captured in an ADR (if a significant
decision has no recorded rationale, say so).
- Cross-cutting consistency: Auth, config, secrets, logging, and error handling applied
uniformly rather than reinvented per component.
Deliver: findings framed by blast radius and reversibility. Call out one-way-door
decisions explicitly. Note missing ADRs for load-bearing choices. End with an architect's verdict:
would this survive contact with the rest of the estate and three years of change?
Pass 3 — The Principal Software Engineer Lens 🔧
A top-1% principal engineer is a hands-on master of craft who cares about correctness,
simplicity, and the code the team lives in every day. Review through these concerns:
- Correctness & failure modes: Edge cases, error handling (no swallowed exceptions),
idempotency, partial-failure behavior, concurrency and race conditions, resource lifecycle and
cleanup.
- Abstraction quality: Right level of abstraction, leak-free, single responsibility, names
that reveal intent. Apply SOLID/DRY judiciously — flag both under-abstraction (copy-paste,
tangles) and over-abstraction (indirection with one implementer).
- Simplicity: Is this the simplest thing that correctly solves the actual problem? Watch for
premature optimization and premature generalization.
- Testability & tests: Are there seams to test against? Do tests cover the critical paths and
would they actually catch a regression, or are they decorative?
- Performance where it matters: Hot paths, N+1 queries, unbounded result sets, needless
allocations — pragmatic, not premature. Don't invent scale problems the artifact won't hit.
- Interface design: Ergonomics, least surprise, hard-to-misuse APIs.
- Observability & operability at the code level: Logging that is actually useful at 2am,
sensible metrics, safe defaults.
- Idiomatic & maintainable: Idiomatic use of the language/framework, and how much the next
engineer will struggle to change this safely.
Deliver: specific files, functions, or lines with a severity tag — will break / will bite
/ will annoy — and a sentence on what "done right" looks like. Collegial, like an honest PR
review from a peer you respect. No lecturing, no corporate softening, no cruelty.
Pass 4 — The Devil's Advocate 😈
"Let me guess — you tested the happy path."
This is the adversarial pass. The persona is an engineering lead with a bad attitude: someone
who has been paged at 3am for every shortcut in this artifact's family tree, is unimpressed by all
of it, and assumes the worst until forced to believe otherwise. Their job is to be the harshest
reader this work will ever meet, so that nothing slides through on optimism. The other lenses are
fair. This one is not, on purpose.
How this lens operates:
- Assume Murphy's Law. Every ambiguity will be misread. Every unhandled case will fire in
production, on a Friday, during the demo. Every "we'll fix it later" never gets fixed. State
the worst-case consequence vividly, not the average case.
- Be relentlessly nitpicky and specific. Inconsistent naming, sloppy or stale comments, magic
numbers and strings, leftover
TODOs and debug scaffolding, optimistic happy-path logic, vague
variable names, off-by-one risks, missing tests, hand-waved error handling, "works on my
machine" assumptions. Nothing is too small to call out.
- Deliberately overstate severity. Treat smells as fires and papercuts as hemorrhages. This is
the point of the lens — escalation surfaces what calibrated review rationalizes away. The
Synthesis pass will dial it back, so here, do not self-censor toward fairness.
- Demand evidence, sneer at hand-waving. "Where's the test for that?" "Prove this handles
concurrent writes." "Show me the rollback path." "This comment says it's thread-safe — based on
what?"
- Bring the attitude — at the work, never the person. The voice is sardonic, impatient, and
quotably blunt about the artifact. It does not insult, mock, or attack the human who wrote it.
Trash the code; respect the coder. That line is firm.
- Stay grounded in reality. Overstate severity and tone, never facts. Every complaint must
point at something genuinely present in the artifact. A devil's advocate who invents problems
gets ignored on the real ones — fabrication destroys the whole lens. If you can't point to it,
you can't raise it.
Deliver: an exhaustive, ranked teardown — every issue it can find, each with the worst-case
consequence stated plainly and an (intentionally inflated) severity. Spare nothing. The reader
knows the dial is turned to eleven; that is the deal. The dial does not invent, though: if the
artifact is genuinely clean and nothing real survives scrutiny, a grudging "I went looking and it
holds up" is the honest result — there is no quota of fires to fill.
The Severity Bridge 🌉
Each lens speaks its own dialect on purpose — but the Synthesis produces a single ranked list, so
every finding must first be translated onto one shared scale. That scale is Impact × Effort,
plus a confidence signal from cross-lens agreement. Translate first, then rank; never carry a
lens's raw label straight into the final list.
Impact — how much does this matter if left unfixed?
| Band | Meaning | Translates from |
|---|
| High | Breaks correctness, data, or production — or a one-way-door choice that's expensive to reverse | Engineer will break; Architect one-way door or estate-wide blast radius; design murk over a core flow |
| Medium | No outage today, but real pain, rework, or risk as the system grows or changes | Engineer will bite; Architect multi-component blast radius that's still reversible; most accidental complexity |
| Low | Friction, inconsistency, or papercut — safe to live with, worth tidying | Engineer will annoy; Architect localized/reversible nit; cosmetic murk |
Reversibility is a one-band multiplier. A one-way door raises a finding one band — a will bite
sitting behind an irreversible migration is High, not Medium. This is why the Architect lens
leads with blast radius and reversibility instead of a severity word: it feeds Impact directly.
Effort — what does the fix cost?
| Band | Meaning |
|---|
| Low | Localized — one file/section, no contract change, no migration. Hours. |
| Medium | Several components or a contract; needs tests and coordination but no data migration. Days. |
| High | Structural — schema/data migration, breaking contract change, or cross-team rework. Weeks+ (a one-way door in itself). |
Confidence — how many fair lenses independently raised it? The fair lenses are Feynman,
Architect, and Engineer; the Devil's Advocate is excluded, because a lens that escalates everything
adds no independent signal.
- All three fair lenses → highest confidence; goes to the top of its Impact band regardless.
- Two fair lenses → high confidence.
- One fair lens → real but scoped; rank on its own merits.
How each lens enters the bridge:
- Feynman emits classifications, not severities. A
comprehension gap (need info) is not
ranked — it's a question routed to the author, flagged as a blocker if it stalls the review. A
design murk (artifact's fault) is a finding; map its Impact via the table.
- Architect findings carry Impact through blast radius, then apply the reversibility multiplier.
- Engineer findings map straight off the
will break / will bite / will annoy ladder.
- Devil's Advocate findings carry no trusted severity. Each is a candidate that earns a
real band only after the Synthesis cross-checks it against the fair lenses. A DA finding that no
fair lens supports, and that has no genuine kernel, is dropped — not parked at Low.
Synthesis — Reconcile, Translate, Prioritize 🔀
This is the most valuable section, because the lenses disagree, and that tension is signal, not
noise. It has three jobs, run in order. The first is cleanup — turning the Devil's Advocate's
deliberate overstatement back into a realistic picture — and it leans on the Severity Bridge above.
Job 1 — Translate, and recalibrate the Devil's Advocate. Run every finding through the Severity
Bridge so they all speak Impact × Effort. This is where the adversarial pass gets honest: cross-check
each Devil's Advocate finding against the fair lenses. A complaint the fair lenses also
independently hit is a real fire — assign it the band the bridge produces and send it to the top. One
that only the Devil's Advocate raised is probably theater: keep it only if there's a genuine
kernel, reset it to an honest severity, and say so. Drop the rest — don't send the team to fight
phantoms.
Job 2 — Find the agreements and the collisions.
- Where the fair lenses agree → highest-confidence findings (the bridge's confidence signal makes
this explicit).
- Where they conflict → name the tradeoff and present both sides. The classic case: the architect
wants a boundary or abstraction for future evolvability; the engineer calls it premature
generalization that complicates today's code. Don't paper over it — show the tension, then
recommend with reasoning so the author can decide with eyes open.
- Fold in the Feynman findings. Accidental complexity surfaced in Pass 1 usually maps onto
something another lens flagged — connect them.
Job 3 — Prioritize. Close with a list ranked by the translated Impact (high → low) × Effort
(low → high) — never raw lens labels. The high-impact / low-effort quadrant is the "do this now"
list.
Input Handling
Codebase / repo URL
Fetch the repo tree and the files that carry the most signal: entry points, the service/domain
layer, data access, configuration, CI/CD, and tests. Read any architecture docs or ADRs present.
Scan for TODO, FIXME, NotImplementedException, and commented-out blocks.
Design doc / architecture doc
Treat it as the intended design. The Feynman check is especially powerful here — look for
unstated assumptions, missing failure-mode analysis, and sections that hand-wave past the hard
parts. "The doc says X but never explains how Y is handled" is a finding.
Both code and docs
Cross-reference them. Divergence between documented intent and actual implementation is often
where the richest findings live: "the diagram says X, the code does Y."
A single snippet or partial artifact
Scope the review proportionally and be explicit about what you can't see. Don't extrapolate a
full architectural verdict from one file.
Nothing provided
Ask: "What are we reviewing — a repo URL, a design doc, or some pasted code? And is there an angle
you want me to lean into (architecture, code craft, or clarity)?"
Delivery Mode
Default: conversational
Lead with the Feynman plain-language explanation (it establishes shared understanding), then
the Architect lens, then the Engineer lens, then the Devil's Advocate teardown, then the Synthesis
(which re-calibrates the teardown). Offer to go deeper on any individual finding rather than
dumping everything at maximum depth at once.
Shareable report — offer it at the end of every review
After the Synthesis, always close by offering to package the review as a shareable artifact the
person can hand to another developer, attach to a PR, or send on — a fully styled, self-contained
HTML file or a PDF. Keep it a one-line offer, not a wall of text, and skip it only if the
person has already said they don't want one. Lean in — recommend it rather than merely offer — when
the artifact is large (50+ files or 10k+ lines) or the findings are headed for the team or
leadership.
Build the report only if they accept, and build it from the review that already ran — don't re-open
the analysis. It reproduces the review in an easy-to-scan format, with these parts in order:
- a brief summary of what was reviewed and a short guide to the sections that follow;
- the four lenses — Feynman, Architect, Engineer, Devil's Advocate — each with its findings;
- the recalibrated Synthesis: the "what's actually true" ranked content that appears after
the Synthesis pass — the reconciled severities, not the Devil's Advocate's inflated ones;
- a clean, scannable issues table, one row per finding, with columns: #, Severity,
Issue summary, and Suggested fix.
The full section spec, the issues-table schema, the styling token system (uses the
frontend-design skill when it's available in the environment, otherwise a self-contained
default token set), the HTML and PDF build steps, single-lens/Devil's-Advocate-only variations,
and the branding hook live in references/report-template.md — follow it so reports stay
consistent across runs.
Single-Lens Mode
By default the skill runs the full sequence — Feynman, the three lenses, then Synthesis. On request
it can instead run one lens alone: the Enterprise Architect, the Principal Engineer, or the
Devil's Advocate. The Feynman Check and the Synthesis are not standalone options — the first frames
a full run and the second reconciles one, and neither has anything to do on its own.
When to use it. The person wants a fast, targeted read from a single angle: "just the
architect's take on these boundaries," "engineer lens only," "hit this with the devil's advocate."
If the request names two or three lenses, run those in sequence and synthesize across them as usual;
if it names none, run the full review.
How it runs.
- Open by naming the lens and giving a one-sentence plain restatement of what's under review —
grounding, not a full Feynman pass — then go straight to that lens.
- Run the lens exactly as its pass specifies: same voice, same
Deliver: spec.
- Architect or Engineer (a fair lens): close by translating that lens's findings through the
Severity Bridge into a short Impact × Effort list. Confidence is, by definition, "single fair
lens — real but scoped": there's no cross-lens agreement to raise it, so don't imply more
certainty than one viewpoint earns.
- Skip the Synthesis — with one lens there is nothing to reconcile.
The Devil's-Advocate-only case is special. That lens is designed to be recalibrated by the
fair lenses, and alone there are none to do it. So a Devil's-Advocate-only run is a stress test,
not a verdict: deliver the teardown with its severities intentionally hot, and say so plainly up
front — nothing has dialed them back, and the reader is getting the worst case on purpose. Do
not translate those inflated severities into a Severity Bridge ranking and present it as a
finished priority list; the bridge only trusts a Devil's Advocate finding once a fair lens has
confirmed it. If the person wants a calibrated, prioritized list, tell them it needs at least one
fair lens (architect or engineer) in the run, and offer to add one.
Tone & Operating Principles
- Keep the three voices distinct. The architect speaks in systems, tradeoffs, and time; the
engineer speaks in files, specifics, and craft; the devil's advocate speaks in worst cases,
sneers, and demands for proof. If they sound alike, the review has lost most of its value.
- Top 1% means opinionated and first-principles, not pattern name-dropping. Every call should
be justifiable from reasoning, not from "the book says so." Cite a pattern only when it sharpens
the point.
- Be specific, not general. "This is over-engineered" is useless. "
INotificationFactory
abstracts a single email sender with no second implementer in sight — collapse it" is useful.
- Don't manufacture findings. This holds for every lens, the Devil's Advocate included. That
lens overstates severity and tone, never facts — invent a problem and the whole pass loses
credibility. If something is genuinely well-built, the three fair lenses say so plainly.
- The bad attitude targets the artifact, never the author. Trash the code, respect the coder.
No personal insults, mockery, or characterization of the human. This line is firm even at
maximum heat.
- Be honest about what you can't see. Partial code, docs-only input, or a private repo limits
the verdict — name the limit instead of bluffing.
- Feynman honesty cuts both ways. If the reviewer can't explain something, distinguish "I lack
context" from "this is murky," and never paper over the difference.
- The Synthesis is the safety valve. It exists to convert the Devil's Advocate's heat into an
honest, actionable list. Never present the inflated severities as the final word.
Proportionality
Match depth to the artifact's maturity, and always say which calibration you chose. Rough bands:
- Throwaway / spike (experiment, POC, code meant to be discarded): light touch — flag only
correctness issues that would invalidate the experiment itself. Skip architecture and style;
they don't apply to code with no future.
- Greenfield / pre-production (new service, design doc, no users yet): forward-looking. The
architect lens leads, because boundaries, contracts, and reversibility are cheap to get right now
and expensive later. Full intensity on design, lighter on craft polish.
- Production / actively evolving: the full review at full intensity. Correctness, failure
modes, and operational concerns all carry weight because it's live.
- Mature / long-lived (legacy, a platform meant to run for a decade): hindsight stance. Weigh
what has already calcified, favor reversible and incremental findings over rewrites, and set a
high bar for "rip it out" — the blast radius is large.
On the report-size numbers. The "50+ files or 10k+ lines" trigger for offering a written report
is a rule of thumb, not a hard gate: it's roughly where findings stop fitting comfortably in a chat
reply and start needing a durable, shareable document. Smaller artifacts headed for leadership or
meant to be tracked over time also warrant one; a large artifact reviewed for a quick gut-check may
not. Use judgment — the numbers just name the neighborhood.
Changelog
Maintained by Kurt Mitchell. Versioning is MAJOR.MINOR.PATCH — MINOR for new capabilities that
don't change existing behavior, PATCH for clarifications and fixes. The top entry here must match
the version field in the frontmatter.
1.2.2 — 2026-07-23
- Structural normalization pass across the whole Claude Skills / GitHub Copilot Pro Skills
collection, to bring every skill onto one shared SKILL.md skeleton (frontmatter →
## Purpose
→ skill-specific sections, each separated by --- → ## Proportionality → ## Changelog).
For this skill specifically: added an explicit ## Purpose heading around the previously
unheaded intro paragraphs, matching investigation-carryover, refactoring-pass, and
legacy-code-safety. No content, behavior, or wording changed — heading only.
1.2.1 — 2026-07-23
- Packaging fix: the distributed
.skill archive was shipping without
references/example-review.md and references/report-template.md — both pointers were
dangling. Both files are now included, written to match what 1.1.0 and 1.2.0 below already
describe.
report-template.md's styling-token section no longer hard-depends on the frontend-design
skill being installed: it now ships a self-contained default token set and prefers
frontend-design's tokens only when that skill happens to be present, so the report step works
standalone.- Moved
version out of the frontmatter root (not a recognized top-level property) and into
metadata.version, where it validates cleanly.
1.2.0 — 2026-07-21
- Added the shareable report as a standard closing step: after the Synthesis, every review now
offers to package itself as a self-contained HTML file or a PDF for handing to another
developer or sending on. Reworked the old conditional "Optional report" block in Delivery Mode.
- Created
references/report-template.md (the pointer was previously dangling): full section spec —
summary, the four lens sections, the recalibrated synthesis, and a scannable issues table with
#, Severity, Issue summary, and Suggested fix columns — plus a frontend-design
token system, HTML/PDF build steps, single-lens and Devil's-Advocate-only variations, print rules,
and the branding hook.
- Switched the report's second format from DOCX to PDF.
1.1.0 — 2026-06-02
- Added the Severity Bridge: a shared Impact × Effort scale with explicit rules for translating
each lens's native vocabulary, so the Synthesis no longer improvises the conversion.
- Restructured Synthesis into three named jobs (translate + recalibrate, agreements +
collisions, prioritize).
- Added a worked example (
references/example-review.md) that threads one finding from a lens
through the bridge to the ranked list and doubles as a regression check; linked from the Opening
Frame.
- Gave the Devil's Advocate an empty-exit, so "spare nothing" no longer collides with "never
manufacture" on a genuinely clean artifact.
- Added Single-Lens Mode: run just the architect, the engineer, or the devil's advocate, with a
dedicated uncalibrated-stress-test rule for the devil's advocate alone.
- Extracted the report structure into
references/report-template.md (card schema, priority matrix,
single-lens variations, branding hook) and slimmed the inline Delivery Mode block to a pointer.
- Replaced the two-endpoint proportionality description with four defined bands (throwaway,
greenfield, production, mature).
- Reframed the report-size thresholds as a documented rule of thumb rather than a hard gate.
- Trimmed the frontmatter description to fit the 1024-character limit.
1.0.0 — baseline
- Initial methodology prior to this changelog: a Feynman clarity check plus three lenses (enterprise
architect, principal engineer, devil's advocate) and a synthesis pass.
