Content
82%Weight 40%Scale 1-5Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
A strong, expert-aimed reference: executable fail-closed verification code, precise gotchas that reflect real failure modes, and well-organized references that exist and deliver what they promise. Weak spots are limited to padding (Related Skills list, attribution, repeated disambiguation) and references to examples/ directories that are not present in the bundle.
Suggestions
Trim the 13-item Related Skills list to the 2-3 most relevant (e.g., webhook-handler-patterns, stripe-webhooks, adyen-webhooks) and move the rest to a reference file or drop the Attribution section — these add ~40 lines of low-value tokens.
Fix or remove the examples/express/, examples/nextjs/, and examples/fastapi/ links — no examples/ directory exists in the bundle, so following them fails; either include the examples or inline a minimal complete handler.
Add an explicit numbered handler checklist (verify → parse → dedupe on evt id → enqueue → 2xx within 10s) with a 'if verification fails, respond 401 and check the top causes' recovery step, rather than delegating failure recovery entirely to references/verification.md.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and expert-level — it assumes knowledge of HMAC, webhooks, and Node crypto, and never explains background concepts — but a few sections pad the token budget: the 13-item Related Skills list, the Attribution section, and the disambiguation note repeated verbatim from the description. These are minor trims, matching the "efficient; minor instances of over-explanation" anchor rather than the lean 5. | 4 / 5 |
Actionability | The core verification code is complete, copy-paste ready, and fail-closed (length guard before timingSafeEqual, missing-header check), with a real example key value, exact retry schedule (8 attempts with intervals), a runnable local-dev command (`npx hookdeck-cli listen 3000 ...`), and an explicit "verify, enqueue, return 2xx" guidance line. This matches the fully-executable anchor covering the common cases. | 5 / 5 |
Workflow Clarity | The handler sequence is clearly laid out (set signature key → verify raw-body HMAC → optionally check Authorization → dedupe on evt id → ack within 10s) with validation behavior embedded in the code (fail closed, length guard) and explicit error consequences ("uncaught throw becomes a 500, which Checkout.com retries eight times"). It falls short of the 5 anchor because there is no explicit ordered checklist or debug-on-failure loop in the body itself — recovery guidance is delegated to references/verification.md. | 4 / 5 |
Progressive Disclosure | Structure is good: three one-level-deep reference files (overview.md, setup.md, verification.md) are well-signaled with per-file content summaries, and all three exist in the bundle with matching content. The gap against the 5 anchor is the "For complete handlers with tests, see examples/express/, examples/nextjs/, examples/fastapi/" pointers — no examples/ directory exists in the bundle, so those references are broken. | 4 / 5 |
Total | 17 / 20 Passed |