Content
75%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.
The body delivers lean, correct, provider-specific guidance with complete verification code in two languages and well-signaled reference files. Main deductions are for the duplicate headers table, promotional/padding sections, and references to example-handler directories that are missing from the bundle.
Suggestions
Remove the 'Important Headers' table — it duplicates the signing rules already stated in 'Essential Code' (both describe X-Affonso-Signature as the lowercase-hex HMAC-SHA256 of <timestamp>.<raw body>).
Trim or relocate the 9-link 'Related Skills' section and 'Attribution' block, which consume tokens without advancing webhook setup or verification.
Fix the dead references: the body points to examples/express/, examples/nextjs/, and examples/fastapi/ for 'complete handlers with tests', but no examples/ directory exists in the bundle — include the example handlers or correct the links.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The core sections are lean and provider-specific ("used as a plain string. Do not hex-decode it", "Never JSON.parse / re-serialise first"), with no explanations of concepts Claude already knows, so it is above the 3 anchor; it misses the 5 anchor because the 'Important Headers' table restates the signing rules bullets from 'Essential Code' and the 9-link 'Related Skills' section plus 'Attribution' are tokens that could be trimmed. | 4 / 5 |
Actionability | Verification is fully executable and copy-paste ready in both Node.js and Python (input validation, timing-safe comparison, the express.raw hint) plus an executable tunnel command ("npx hookdeck-cli listen 3000 affonso --path /webhooks/affonso"), matching the 4 anchor's 'concrete code or commands with minor gaps'; the gap that keeps it from 5 is that 'complete handlers with tests' are promised at examples/express/, examples/nextjs/, and examples/fastapi/, which do not exist in this bundle. | 4 / 5 |
Workflow Clarity | There is an explicit validation checkpoint with failure behavior ("Respond 401 when verification fails (missing or empty header, malformed digest, mismatch)") and raw-body acquisition warnings, plus idempotency guidance ("Use the event id for idempotency instead"), placing it above the 3 anchor; it falls short of the 5 anchor because the end-to-end handler sequence (verify first, parse second, handle idempotently) is only available via external webhook-handler-patterns links rather than an inline sequence. | 4 / 5 |
Progressive Disclosure | The three referenced files (references/overview.md, references/setup.md, references/verification.md) all exist, are one level deep, and are clearly signaled with descriptions in the 'Reference Materials' section, with common events inline and the full list delegated — good structure per the 4 anchor; it is not 5 because the body's links to examples/express/, examples/nextjs/, and examples/fastapi/ point to directories absent from the bundle, a navigation gap for the most substantial promised resource. | 4 / 5 |
Total | 16 / 20 Passed |