- Home
- Skills
- Code Quality & Review
- Spec Check Before Coding: Test the Spec Against Reality
Works with the AI Agents you already use
Spec Check Before Coding: Test the Spec Against Reality
Agents make this worse because they take the spec at its word and start coding.
Free
Spec Check Before Coding: Test the Spec Against Reality
Example session with this skill installed
Review docs/specs/checkout-discounts.md before we implement it. Tests run with python3 -m unittest, and our staging API is at http://127.0.0.1:8099 (GET /api/quote). Read-only: don't change any code. You can go past your summary without waiting for me.
- Read your context and instructions
- Compiled the spec check before
Spec review: docs/specs/checkout-discounts.md
What the spec asks for
The spec lets a customer use FREESHIP together with one percentage code on the same order, so people with a welcome code and free shipping stop abandoning their carts. It also adds a new SAVE20 code (20% off subtotals of $100 or more) for large orders. On the API side, GET /api/quote would accept code more than once. Sending two percentage codes would return 422 with codes_not_combinable. The code involved is shop/discounts.py (quote()) and shop/server.py (query parsing).
You said I could go past this summary without waiting, so I went on to check the spec's "Current behavior" section against the real system.
Verification evidence
Unit tests: PYTHONDONTWRITEBYTECODE=1 python3 -m unittest -v. I set that variable so the run wouldn't write any files. git status showed the same before and after.
test_freeship_over_threshold ... ok
test_no_code_adds_shipping ... ok
test_unknown_code_is_rejected ... ok
test_welcome10_takes_ten_percent ... ok
Ran 4 tests in 0.000s
OK
All 4 pass. None of them covers lowercase codes, the exact FREESHIP threshold, or sending two codes.
Staging API: curl -s "http://127.0.0.1:8099/api/quote?<query>"
| Query | HTTP | Response |
|---|---|---|
subtotal=60 | 200 | {"subtotal": 60.0, "discount": 0.0, "shipping": 7.5, "total": 67.5, "applied_code": null} |
subtotal=60&code=WELCOME10 | 200 | {"subtotal": 60.0, "discount": 6.0, "shipping": 7.5, "total": 61.5, "applied_code": "WELCOME10"} |
subtotal=60&code=welcome10 | 422 | {"error": "invalid_code", "code": "welcome10"} |
subtotal=60&code=Welcome10 | 422 | {"error": "invalid_code", "code": "Welcome10"} |
subtotal=80&code=freeship | 422 | {"error": "invalid_code", "code": "freeship"} |
subtotal=50&code=FREESHIP | 422 | {"error": "invalid_code", "code": "FREESHIP"} |
subtotal=60&code=FREESHIP | 422 | {"error": "invalid_code", "code": "FREESHIP"} |
subtotal=74.99&code=FREESHIP | 422 | {"error": "invalid_code", "code": "FREESHIP"} |
subtotal=75&code=FREESHIP | 200 | {"subtotal": 75.0, "discount": 0.0, "shipping": 0.0, "total": 75.0, "applied_code": "FREESHIP"} |
subtotal=60&code=BOGUS | 422 | {"error": "invalid_code", "code": "BOGUS"} |
subtotal=60&code=WELCOME10&code=FREESHIP | 200 | {"subtotal": 60.0, "discount": 6.0, "shipping": 7.5, "total": 61.5, "applied_code": "WELCOME10"} |
subtotal=60&code=FREESHIP&code=WELCOME10 | 422 | {"error": "invalid_code", "code": "FREESHIP"} |
subtotal=120&code=SAVE20 | 422 | {"error": "invalid_code", "code": "SAVE20"} |
The code gives the same results
shop/discounts.pyhasFREESHIP_MIN_SUBTOTAL = 75.00.- Codes are matched exactly (
code in PERCENT_CODES,code == "FREESHIP"), with no case normalization. shop/server.pyreads only the first code:q.get("code", [None])[0].
Stopped: the spec's "current behavior" doesn't match the system
Two of the spec's claims about how the system works today are wrong. I've stopped the review here instead of building it on that description.
1. Case sensitivity
- Spec says: "Discount codes are case-insensitive:
welcome10andWELCOME10both apply."
Reality: codes are case-sensitive. welcome10, Welcome10 and freeship all return 422 invalid_code. Only the exact uppercase code works.
2. FREESHIP threshold
- Spec says: "
FREESHIPremoves the $7.50 shipping fee on orders of $50 or more."
Reality: the threshold is
$75. FREESHIP at 50, 60 and 74.99 returns 422 invalid_code; at 75 it applies. Below the threshold the order isn't just charged shipping: the whole request is rejected as an invalid code.
This also breaks the first acceptance criterion. subtotal=60, code=WELCOME10, code=FREESHIP → shipping 0, total 54.00 only works with a $50 threshold. With today's $75 threshold, FREESHIP doesn't qualify at $60.
Smaller differences, which also affect the "after" design:
- Spec says: "Only one code can be used per order."
Reality: a second code isn't rejected. The server silently uses the first code and ignores the rest. WELCOME10&FREESHIP returns 200 with only WELCOME10 applied. FREESHIP&WELCOME10 at $60 returns 422 because FREESHIP came first.
- These claims match: WELCOME10 takes 10% off, and unknown codes return
invalid_code(as HTTP 422).
Questions before we continue
Is the spec out of date, or is the code wrong? Was the FREESHIP threshold $50 at some point and later raised to $75? Was case-insensitive matching planned but never built?
2.
Is the spec describing another environment? For example, production with settings that differ from this staging server.
3.
For the new behavior: should the threshold be $50 (a change the spec doesn't mention) or stay at $75? Should matching become case-insensitive as part of this work, or stay exact?
If your answers mean the spec's picture of today's system is wrong, the spec needs updating before anyone implements from it. The other option is for you to approve continuing with the known inaccuracy. Until then I won't move on to mapping the code changes or the before/after approvals.
I didn't change, create or delete any file in the project.
Connects securely to your tools. The creator never sees your data.
About this skill
The problem
Specs rot. The system a spec describes has often drifted by the time someone implements it. If the "before" picture is wrong, the "after" is wrong too, and nobody notices until QA or production. Agents make this worse because they take the spec at its word and start coding.
What it does
- Summarizes the spec back to you (what changes, why, the business logic and the scope) and confirms it understood before going further.
- Asks what testing is available, which environment to use and what is off-limits, without guessing.
- Verifies the current state by running existing tests, sending API requests, tracing code paths, or checking the UI in a browser.
- Gate 1: stops if the required tests can't run within your scope.
- Gate 2: stops if today's behavior doesn't match what the spec claims, and shows you the quote from the spec next to what testing found.
- Maps the spec's changes onto the codebase, from architecture to components to lines.
- Presents every change as a before/after (UX flow, request/response, business logic or schema) and asks for your approval one change at a time.
- Reviews details last: edge cases, error handling, security, backward compatibility, concurrency and rollback.
- Ends with a summary of approved changes, risks, pros, cons and things the implementer should know.
- Never implements anything. It only reviews.
Frameworks & tools
Stack-agnostic. Uses whatever testing the project already has: unit, integration, API requests, and Playwright when browser checks are needed.
Why this beats prompting it yourself
It enforces an order and two hard stops. A plain "review this spec" prompt critiques the document. This skill checks the document against the running system and refuses to continue on a false premise without your explicit approval.
Use cases
- Checking a ticket or PRD before handing it to an agent to implement.
- Catching a stale spec written months before the system changed.
- Aligning on before/after behavior with the person who wrote the spec.
Known limitations
Review only; it writes no implementation code. Verifying current behavior needs a test environment or a test suite you can run. Without one, Gate 1 stops the review.
Find more skills like this on the Claude Skills Marketplace, the Codex Skills Marketplace and the Gemini Skills Marketplace, or browse Claude Skills for Code Quality & Review.
Review only; it writes no implementation code. Verifying current behavior needs a test environment or a test suite you can run. Without one, Gate 1 stops the review.
How to use
- 1
Connect your agent to the Agensi MCP
Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup
- 2
Sign in to Agensi
Your agent shows a sign-in link. Sign in and click Allow.
- 3
Ask for what you need
Your agent loads this skill and uses it on your task. It always asks before buying a skill.
Reviews
No reviews yet
Be one of the first to try it. Every listed skill goes through the trust checks below.
Security scanned
Checked by our 8-point scan before listing
Fresh listing
Recently published to Agensi
Free to use
No account required to browse
Trust & safety
Security scan
Security scan passed 8 days ago
- Free with an Agensi account
- Software
- Project test runner
- Optional
- Playwrightorbrowser MCP
Playwright or a browser MCP is only needed for UI specs.
Permissions
Read-only and never writes code. Shell runs the project's existing tests. Network and browser access only reach the test environment the user names. It only uses a test-environment account the user provides in the session, never a production or personal account, and does not write it to any file, log or summary.