{
  "instruction": "Always provide a hook callback to zValidator that returns structured JSON on validation failure",
  "relevant_when": "Agent uses @hono/zod-validator to validate request bodies, query params, or other inputs in a Hono API",
  "context": "The default zValidator behavior returns a 400 response with a plain-text body containing the Zod error. This is unusable by JSON API clients. The third argument to zValidator is a hook callback that receives { success, data?, error? } and the Hono context c. On failure, return c.json() with a structured error object. On success, return nothing to proceed to the handler. After validation, always use c.req.valid('json') to access the typed data -- never c.req.json() which re-parses and loses the Zod-inferred type.",
  "sources": [
    {
      "type": "file",
      "filename": "skills/hono-best-practices/SKILL.md",
      "tile": "tessl-labs/hono-best-practices@0.2.0"
    }
  ],
  "checklist": [
    {
      "name": "hook-callback-present",
      "rule": "Every zValidator call includes a third argument hook callback function that handles validation failure by returning c.json() with a structured error response",
      "relevant_when": "Agent uses zValidator from @hono/zod-validator"
    },
    {
      "name": "structured-json-error-on-failure",
      "rule": "The hook callback returns c.json({ error: { code, message } }, 400) or similar structured JSON on validation failure -- not plain text, not the raw Zod error object",
      "relevant_when": "Agent handles zValidator validation failure"
    },
    {
      "name": "use-req-valid-not-req-json",
      "rule": "After zValidator, the handler accesses validated data via c.req.valid('json') (or 'query', 'param', etc.) -- never via c.req.json() which re-parses the body and loses Zod type inference",
      "relevant_when": "Agent accesses request body after zValidator middleware"
    }
  ]
}