From 3632afbc7906caf5334b2f67169384c63d7e2197 Mon Sep 17 00:00:00 2001
From: Wiktoria Van Harneveldt <w.dev+git@mailbox.org>
Date: Sun, 18 Oct 2026 12:49:51 +0200
Subject: [PATCH] docs: add error handling guidance to AGENTS.md

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
---
 AGENTS.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 2563059..db331cd 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -122,6 +122,54 @@ const configuration = getConfiguration();
   } as const;
   ```
 
+### Error Handling
+
+Throw an error when a function cannot complete its job, and handle it where the caller can respond. Do not return a sentinel string or flag that every caller must remember to check.
+
+```typescript
+// ❌ BAD — every caller has to check the returned string
+function foo(): 'good' | 'bad' {
+  if (somethingNotRight) {
+    return 'bad';
+  }
+
+  doTheRightThing();
+  return 'good';
+}
+
+function bar(): void {
+  const result = foo();
+
+  if (result === 'bad') {
+    console.error('bad message for logging');
+    interaction.reply('bad message to user');
+  }
+
+  if (result === 'good') {
+    interaction.reply('good message to user');
+  }
+}
+
+// ✅ GOOD — the failure is thrown and handled in one place
+function foo(): void {
+  if (somethingNotRight) {
+    throw new Error('something is not right');
+  }
+
+  doTheRightThing();
+}
+
+function bar(): void {
+  try {
+    foo();
+    interaction.reply('success, expected outcome');
+  } catch (error) {
+    console.error(error);
+    interaction.reply(error.message);
+  }
+}
+```
+
 ## Configuration Is the Source of Truth
 
 Root-level config files define how this project is built, linted, formatted, and run. **Do not invent parallel config** (no new ESLint/Prettier/Biome/Jest/Vitest configs, no duplicate tsconfig variants, no ad-hoc tooling files).