feat(coding): errors as instructions — agent-actionable error output as a named coding standard

[visionik]

Summary

Directive's scripts already do this in places — scripts/framework_doctor.py emits data.suggested_fix fields, scripts/preflight_branch.py has actionable error text, the vBRIEF preflight gate outputs recovery commands. But this is emergent good practice, not a stated design principle. There is no rule requiring it across directive's tooling.

When agents read error output from directive's scripts, tasks, and tools, the error is either agent-actionable (good) or a human-debug dump the agent must interpret (bad, and common in the broader ecosystem).

The principle

Error messages designed for an LLM to act on. Not cryptic internal state dumps. More like: "denied: this agent lacks X permission on Y resource; the owner can grant it at LINK." Errors as instructions, not puzzles.
— @quinnypig, https://x.com/QuinnyPig/status/2055497559813304735

Every error output from a directive script, task, or tool must be structured as an agent instruction:

1. Name the specific thing that failed (not an internal exception class — what the agent was trying to do)
2. State what the agent should do next (the recovery action)
3. State where the human can intervene if agent recovery isn't possible

This makes "Errors as instructions" a named principle alongside #1006 (Fail Loud: completion claims require outcome verification). Fail Loud is about not hiding outcomes behind success claims. Errors as instructions is about structuring failures so the next actor (agent or human) can immediately act.

Anti-patterns to encode

• ⊗ Emit a raw exception traceback or internal state dump as the agent-visible error
• ⊗ Use error messages that name the failed internal mechanism without naming the user-intent that failed
• ⊗ Output errors that require the agent to re-read documentation to understand what to do next
• ⊗ Omit the recovery path from errors that have a known recovery

Application to projects directive creates

Projects built with directive that expose APIs, tools, or CLI surfaces to agents should apply the same principle: when an agent-invoked operation fails, the error response should be structured as an instruction — what failed, why, what to do next. This is a concrete addition to coding/coding.md and crosscuts into patterns/llm-app.md (Output handling section).

Files affected

• coding/coding.md — new named rule "Errors as Instructions" (sibling to Fail Loud feat(coding): fail-loud rule — never claim completion when anything was skipped silently #1006)
• patterns/llm-app.md — Output handling section: agent-facing APIs should return structured, actionable errors
• tests/content/test_coding_rules.py — content tests pinning the new rule tokens

Related

• feat(coding): fail-loud rule — never claim completion when anything was skipped silently #1006 (Fail Loud — do not hide outcomes; this is the complement: when outcomes are failures, structure them as instructions)
• framework:doctor failure prose names commands that don't exist; sharpen + add UPGRADING.md mitigation paragraph #1061 (framework:doctor failure prose — an existing precedent that already implements this pattern; this issue formalizes it as the rule)
• feat(security,agents): agent-session secret handling rules — assume outputs are persisted, pipe from secret manager #1165 (agent-session secret handling — the error path when a tool only accepts plaintext should follow this principle)