Check Impl Against Spec
During PR review, compare the branch diff and working tree against approved product and tech commitments in spec_context.md and fold material mismatches into review.json.
Overview
Check implementation against spec is an agent skill most often used in Ship (also Validate scope, Build pm) that compares a PR’s implementation to spec_context.md and records material mismatches in review.json.
Install
npx skills add https://github.com/warpdotdev/common-skills --skill check-impl-against-specWhat is this skill?
- Runs only when spec_context.md exists alongside PR review inputs
- Extracts behaviors, file/subsystem changes, constraints, and follow-up steps from product and tech spec sections
- Compares commitments to pr_diff.txt, pr_description.md, and checked-out branch files
- Treats intent-preserving implementation tweaks as acceptable; flags material scope or behavior gaps
- Feeds mismatches into review.json as a supplement to normal code review
- 3-step process: extract commitments, compare to diff and tree, classify material vs acceptable differences
Adoption & trust: 2k installs on skills.sh; 18 GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your PR looks fine in a generic review, but nobody systematically checked it against the approved spec you wrote earlier.
Who is it for?
Repos that maintain spec_context.md with product acceptance criteria and tech change lists and run agent-driven PR review.
Skip if: Ad-hoc commits without spec context, greenfield spikes with no written commitments, or reviews where spec_context.md is absent.
When should I use this skill?
During PR review when approved or repository spec context is available in spec_context.md.
What do I get? / Deliverables
Review output includes spec-aligned gaps so you can fix scope drift before merge instead of discovering missing behaviors in production.
- Material spec mismatches appended or merged into review.json
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Spec-vs-implementation checking is a ship-phase quality gate tied to pull requests, after build work lands and before merge. Review subphase is where agents reconcile implementation with stated acceptance criteria and planned file changes—not a standalone report skill.
Where it fits
After scope is frozen into spec_context.md, ensure later PRs still honor those acceptance criteria.
Tech spec lists required subsystems; this skill verifies the PR actually touched them.
Agent PR review merges spec gaps with standard review findings in review.json.
How it compares
Use alongside narrative code review skills—it adds spec diffing, not style or security scanning alone.
Common Questions / FAQ
Who is check-impl-against-spec for?
Solo and indie builders using agent PR review who already capture approved product and tech spec in spec_context.md and want automated drift detection.
When should I use check-impl-against-spec?
During ship review when spec_context.md, pr_diff.txt, and the PR branch are available; also useful after validate scope or build pm when those specs feed the same review pipeline.
Is check-impl-against-spec safe to install?
It reads spec and PR artifacts in your workspace; review the Security Audits panel on this Prism page before installing in sensitive repos.
SKILL.md
READMESKILL.md - Check Impl Against Spec
# Check implementation against spec Use this skill only when `spec_context.md` exists during PR review. ## Goal Determine whether the implementation in the checked-out PR materially matches the approved spec context. This is a supplement to the normal code review, not a separate output. ## Inputs - `spec_context.md` contains the spec context to compare against. It may include both product spec content (intended behavior, acceptance criteria) and tech spec content (implementation details, file changes). - `pr_diff.txt` contains the annotated diff for the PR. - `pr_description.md` may contain additional scope or rationale. - The working tree contains the PR branch contents. ## Process 1. Read `spec_context.md` and extract the concrete commitments it makes: - required behaviors (from the product spec) - required files or subsystems to change (from the tech spec) - stated constraints - required follow-up steps, validation, or migrations 2. Compare those commitments against the actual implementation in `pr_diff.txt` and the checked-out files. 3. Treat small implementation-level adjustments as acceptable when they preserve the spec's intent. Do not flag harmless differences in naming, structure, or low-level technique. 4. Flag a mismatch only when it is material, such as: - required behavior in the product spec is missing - the implementation contradicts a spec decision - the change introduces significant unplanned scope - a required validation, migration, or compatibility step from the tech spec is absent ## Outputs - Do not create a separate report file. - Fold spec-alignment findings into `review.json`. - Put broad spec-drift concerns in the review summary. - Add inline comments only when the mismatch can be tied to changed lines in the diff. - Treat material spec drift as at least an important concern. - If the implementation matches the spec closely enough, do not add comments just to mention alignment. ## Boundaries - Do not require literal one-to-one implementation of the spec when the PR achieves the same outcome safely. - Do not speculate about spec details that are not actually present in `spec_context.md`. - Do not post to GitHub directly.