software-review

Reviews PRs, RFCs, and architectural changes for reproducible defects with calibrated severity.

1|Updated May 8, 2026
One-click install
npx skills add https://github.com/franklinbaldo/skills --skill software-review-franklinbaldo
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: software-review
Source: https://github.com/franklinbaldo/skills/tree/main/software-review
Command: npx skills add https://github.com/franklinbaldo/skills --skill software-review-franklinbaldo

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Code review often degrades into style nitpicks, hypothetical risks, or rubber-stamp approvals. This Skill focuses review on material defects: broken invariants, incorrect behavior on valid input, misleading green checks, and architectural promises the mechanism cannot keep, with severity calibrated to the actual product being built. ## Core Features & Use Cases - Defect-focused PR review: Reconstructs the change contract, finds the critical path, reproduces suspected bugs with executable evidence, and reports only material findings with P1/P2 severity. - RFC and architecture review: Checks that every stated objective chains to a mechanism, an observable gate, migration compatibility, and a defined failure state. - Re-review and false-green detection: Verifies prior findings against the new head without moving goalposts, and audits CI checks that appear to validate more than they do. - Use Case: A reviewer suspects a passing pipeline is hiding a failure. The Skill reproduces the case, shows the pipeline swallowing an exit code, classifies it as P1, and proposes both a minimal fix and a structural fix using existing primitives. ## Quick Start Ask the agent to review this PR and report only the real bugs that block it, with severity calibrated to the type of application being built.

Frequently Asked Questions about software-review

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I review a PR for real bugs instead of style nitpicks?▼

Reconstruct the contract of the change first, then locate the critical path where errors would be material, such as parsing, persistence, serialization, and concurrency. Reproduce each suspicion with a test or counterexample before reporting it as a finding.

How to review an RFC or architecture proposal effectively?▼

Check that the RFC closes the chain from objective to contract, mechanism, observable gate, migration compatibility, and failure state. Flag objectives with no corresponding gate and decisions depending on behavior the current tooling does not offer.

How should severity be calibrated in code review findings?▼

Calibrate severity against the actual product being built, not an idealized one. P1 means the change breaks a central guarantee or corrupts data on valid input; P2 is a real but contournable defect; hypothetical future risks are observations, not blockers.

Why do passing CI checks sometimes hide real failures?▼

False greens occur when tests skip the relevant input, pipelines swallow exit codes, validation runs after a filter removes the defective case, or derived artifacts are not regenerated in CI. A misleading gate is often worse than no gate at all.

When should a re-review reopen previous findings?▼

Re-review checks each prior finding against the new head and marks it resolved, partially resolved, or remaining. It should not reopen settled decisions without new evidence or invent fresh nitpicks once everything material is fixed.

When is this review skill not the right tool?▼

It does not apply to greenfield implementation with no review object, cosmetic lint cleanup without consequences, or non-software artifacts like legal documents. It requires an existing change, PR, or RFC as its subject.