error-handling

Name: error-handling
Author: chacosoldier

29stars6forks

How to install error-handling?

chacosoldier/compabob/error-handling

$curl -o .claude/agents/error-handling.md https://raw.githubusercontent.com/chacosoldier/compabob/HEAD/.claude/agents/error-handling.md

Installs into the current project.

Summary

Every agent follows these patterns when something fails. Reference this file from each agent's instructions.

Files · 1

View on GitHub

.claude/agents/error-handling.md

1	# Error Handling (shared across agents)
2
3	Every agent follows these patterns when something fails. Reference this file from each agent's instructions.
4
5	## Read-Before-Speak gate (stakes-sensitive agents)
6
7	For any agent whose wrong output drives a wrong real-world action (a financial figure, a legal claim, a commitment in a draft), apply a hard structural gate at the top of the agent file:
8
9	1. Read the named source files BEFORE producing output that cites a number, fact, or recommendation.
10	2. Declare what was loaded at the top of the response: `Context loaded: [list]`.
11	3. If a required read fails, STOP and report the missing source. Do not substitute general knowledge or stale memory.
12
13	This is stronger than a self-check at the bottom of a file, which the model may skim past.
14
15	## Error classification
16
17	\| Type \| Examples \| Action \|
18	\|-------\|----------\|--------\|
19	\| Transient \| Timeout, rate limit, 429/503/504 \| Retry once after 5s. If it fails again, tell the user and suggest retrying later. \|
20	\| Auth \| 401, expired token, permission denied \| Do NOT retry. Tell the user which service needs re-authentication. \|
21	\| Data \| Empty result, unexpected schema, null fields \| Check the query syntax. If the query is valid, report "no data found" with the query used. \|
22	\| Semantic \| Query returns wrong-looking numbers, request misinterpreted \| Self-check before presenting. Flag: "These numbers look unusual, please verify." \|
23	\| Not found \| Record or file does not exist \| Confirm the name or ID with the user before retrying with a different search. \|
24
25	Never retry: auth errors, permission errors, not-found errors, validation errors.
26	Always retry once: timeouts, rate limits, service-unavailable, connection reset.
27
28	## Fallback chains
29
30	When a primary source is unavailable, fall back and say so:
31
32	- An external connector fails → work from local files; note "[connector] unavailable, working from cached data".
33	- A search index fails → fall back to plain `Grep`; note that results are keyword-only.
34	- A notification channel fails → log the action locally so it is not lost.
35
36	Always tell the user when a fallback is in use, and what it costs (stale data, keyword-only, etc.).
37
38	## Multi-step task recovery
39
40	For workflows with sequential steps:
41
42	1. Before starting, list the steps and note which one you are on.
43	2. On failure at step N, report which steps completed (1 to N-1) and what failed at N.
44	3. Provide resume context: "Steps 1-3 done. Step 4 failed because X. To resume, retry step 4 with Y."
45	4. Never re-run completed steps unless asked (avoids duplicate writes or sends).
46	5. For destructive steps (file overwrite, send), confirm a rollback is not needed before retrying.
47
48	## Uncertainty expression
49
50	- High confidence: "Based on X records over [range]."
51	- Medium: "Note: X% of records had missing [field], which may affect this."
52	- Low: "This is an estimate based on [assumptions]. Verify before acting on it."
53	- Unknown: "I could not find data for X. Should I try [alternative]?"
54
55	Never present uncertain data as certain. "I am not sure" beats a wrong number that gets used in a decision.
56
57	## Deliverable QA checklist
58
59	Before sharing any report or analysis beyond the current conversation:
60
61	- Cross-check key numbers against a second source.
62	- Verify totals add up and date ranges match the request.
63	- Flag obvious outliers (10x or 0.1x expected).
64	- Note data gaps explicitly; never present partial results as complete.
65	- Confirm the output actually answers the original request.
66
67	## Anti-nesting rules (all subagents)
68
69	Subagents run inside a task call from the main session. They must never create nested processes:
70
71	\| Anti-pattern \| Why it breaks \| Instead \|
72	\|--------------\|---------------\|---------\|
73	\| Running the CLI inside a subagent via Bash \| Nested CLI process, crashes or competes \| Use your own tools directly \|
74	\| Using the agent-spawning tool from a subagent \| Three-layer nesting \| Do the work yourself \|
75	\| Invoking a skill from a subagent \| Skills spawn tasks internally \| Apply the knowledge inline \|
76
77	The main session spawns subagents. Subagents never spawn anything.

People who liked this also viewed

6 picks

Type

error-handling

29stars6forks

View on GitHub

How to install error-handling?

chacosoldier/compabob/error-handling

$curl -o .claude/agents/error-handling.md https://raw.githubusercontent.com/chacosoldier/compabob/HEAD/.claude/agents/error-handling.md

Installs into the current project.

Summary

Every agent follows these patterns when something fails. Reference this file from each agent's instructions.

Files · 1

View on GitHub

.claude/agents/error-handling.md

1	# Error Handling (shared across agents)
2
3	Every agent follows these patterns when something fails. Reference this file from each agent's instructions.
4
5	## Read-Before-Speak gate (stakes-sensitive agents)
6
7	For any agent whose wrong output drives a wrong real-world action (a financial figure, a legal claim, a commitment in a draft), apply a hard structural gate at the top of the agent file:
8
9	1. Read the named source files BEFORE producing output that cites a number, fact, or recommendation.
10	2. Declare what was loaded at the top of the response: `Context loaded: [list]`.
11	3. If a required read fails, STOP and report the missing source. Do not substitute general knowledge or stale memory.
12
13	This is stronger than a self-check at the bottom of a file, which the model may skim past.
14
15	## Error classification
16
17	\| Type \| Examples \| Action \|
18	\|-------\|----------\|--------\|
19	\| Transient \| Timeout, rate limit, 429/503/504 \| Retry once after 5s. If it fails again, tell the user and suggest retrying later. \|
20	\| Auth \| 401, expired token, permission denied \| Do NOT retry. Tell the user which service needs re-authentication. \|
21	\| Data \| Empty result, unexpected schema, null fields \| Check the query syntax. If the query is valid, report "no data found" with the query used. \|
22	\| Semantic \| Query returns wrong-looking numbers, request misinterpreted \| Self-check before presenting. Flag: "These numbers look unusual, please verify." \|
23	\| Not found \| Record or file does not exist \| Confirm the name or ID with the user before retrying with a different search. \|
24
25	Never retry: auth errors, permission errors, not-found errors, validation errors.
26	Always retry once: timeouts, rate limits, service-unavailable, connection reset.
27
28	## Fallback chains
29
30	When a primary source is unavailable, fall back and say so:
31
32	- An external connector fails → work from local files; note "[connector] unavailable, working from cached data".
33	- A search index fails → fall back to plain `Grep`; note that results are keyword-only.
34	- A notification channel fails → log the action locally so it is not lost.
35
36	Always tell the user when a fallback is in use, and what it costs (stale data, keyword-only, etc.).
37
38	## Multi-step task recovery
39
40	For workflows with sequential steps:
41
42	1. Before starting, list the steps and note which one you are on.
43	2. On failure at step N, report which steps completed (1 to N-1) and what failed at N.
44	3. Provide resume context: "Steps 1-3 done. Step 4 failed because X. To resume, retry step 4 with Y."
45	4. Never re-run completed steps unless asked (avoids duplicate writes or sends).
46	5. For destructive steps (file overwrite, send), confirm a rollback is not needed before retrying.
47
48	## Uncertainty expression
49
50	- High confidence: "Based on X records over [range]."
51	- Medium: "Note: X% of records had missing [field], which may affect this."
52	- Low: "This is an estimate based on [assumptions]. Verify before acting on it."
53	- Unknown: "I could not find data for X. Should I try [alternative]?"
54
55	Never present uncertain data as certain. "I am not sure" beats a wrong number that gets used in a decision.
56
57	## Deliverable QA checklist
58
59	Before sharing any report or analysis beyond the current conversation:
60
61	- Cross-check key numbers against a second source.
62	- Verify totals add up and date ranges match the request.
63	- Flag obvious outliers (10x or 0.1x expected).
64	- Note data gaps explicitly; never present partial results as complete.
65	- Confirm the output actually answers the original request.
66
67	## Anti-nesting rules (all subagents)
68
69	Subagents run inside a task call from the main session. They must never create nested processes:
70
71	\| Anti-pattern \| Why it breaks \| Instead \|
72	\|--------------\|---------------\|---------\|
73	\| Running the CLI inside a subagent via Bash \| Nested CLI process, crashes or competes \| Use your own tools directly \|
74	\| Using the agent-spawning tool from a subagent \| Three-layer nesting \| Do the work yourself \|
75	\| Invoking a skill from a subagent \| Skills spawn tasks internally \| Apply the knowledge inline \|
76
77	The main session spawns subagents. Subagents never spawn anything.

People who liked this also viewed

6 picks

Type