Content
85%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
A well-structured, highly actionable body with executable tests, explicit validation checkpoints, and a real one-level-deep reference for the reason-code tables. Its main weakness is mild redundancy between the How-to-use list, the numbered Steps, and the Worked example, which costs some token efficiency.
Suggestions
Collapse the 'How to use' 7-step list and the 'Step 1-7' sections into a single sequenced workflow to remove overlapping restatements of the same guidance.
Trim the 'Worked example' to only the parts not already shown as code in Steps 1-5 (e.g. the 13.1 → product_not_received mapping and the final cell-status note), since it currently re-narrates the prior steps.
Move the per-gateway API snippets (Stripe/Adyen/PayPal) into a references/gateway-disputes.md file so the body stays an overview, consistent with how the reason-code catalog is already externalized.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | It largely avoids explaining concepts Claude already knows (only a one-line chargeback definition, no primer on Stripe/PDFs) and leans on executable code, but the 'How to use' 7-step list overlaps with the 'Step 1-7' sections, and the 'Worked example' re-narrates Steps 1-4; tightening that redundancy would lift it to a 3. | 2 / 3 |
Actionability | Provides fully executable, copy-paste-ready TypeScript tests with real SDK calls (stripe.paymentIntents.create with pm_card_createDispute, stripe.disputes.update with concrete evidence fields), exact assertions, a YAML matrix, and ledger reconciliation tests with specific entry types. | 3 / 3 |
Workflow Clarity | A clear sequenced multi-step process (How-to-use 7 steps mirrored by Steps 1-7) with explicit validation checkpoints — assert status === 'needs_response', assert has_evidence before due_by, webhook-driven confirmation of final state, and ledger assertions — and the Anti-patterns table reinforces due-date tracking and webhook handling. | 3 / 3 |
Progressive Disclosure | The reason-code catalog is appropriately offloaded to references/reason-codes.md (a real, confirmed bundle file), referenced inline via markdown links at multiple points, keeping the body an overview with one-level-deep, clearly signaled navigation. | 3 / 3 |
Total | 11 / 12 Passed |