debugging-and-error-recovery

Name: debugging-and-error-recovery
Author: pimenov

20stars2forks

How to install debugging-and-error-recovery?

pimenov/codex-first-skills-pack/debugging-and-error-recovery

$npx -y skills add pimenov/codex-first-skills-pack --skill debugging-and-error-recovery

Installs into the current project.

Summary

Guides systematic root-cause debugging and recovery instead of guessing fixes. Use when tests fail, builds break, commands error, logs or consoles show errors, runtime behavior differs from expectation, a bug is reported, a prior fix did not work, CI/deploy/smoke checks fail, or

Files · 1

View on GitHub

SKILL.md

1	# Debugging And Error Recovery
2
3	## Overview
4
5	When something breaks, stop adding scope. Preserve the evidence, reproduce the failure, localize it, reduce it, fix the root cause, guard against recurrence, and only then resume.
6
7	This skill prevents the common agent failure mode: changing several things at once and declaring success because the latest symptom disappeared.
8
9	## Stop-The-Line Rule
10
11	When any unexpected failure appears:
12
13	1. Stop feature work and unrelated cleanup.
14	2. Preserve the exact error, command, environment clue, input, URL, test name, or repro step.
15	3. Reproduce the failure or document why it cannot be reproduced.
16	4. Localize the failing layer.
17	5. Reduce to the smallest useful failing case.
18	6. Fix the root cause, not only the symptom.
19	7. Add a guard: test, assertion, smoke check, runbook note, or monitor.
20	8. Run focused verification first, then broader verification when risk warrants it.
21
22	Do not keep repeating the same failed guess. If the first real attempt does not solve a tool, package, API, networking, infrastructure, or vendor problem, check current official docs, issue trackers, or known community patterns before the next fix. Use `source-driven-development` for version-sensitive APIs and tools.
23
24	## Triage
25
26	### 1. Reproduce
27
28	Make the failure happen on demand when possible.
29
30	Capture:
31
32	- exact command or user action;
33	- exact error lines, stack frame, failing test name, HTTP status, or log signature;
34	- current branch/worktree state when in a repo;
35	- relevant runtime versions and env key presence without raw secrets;
36	- whether the failure is local, CI, staging, production, or external-service only.
37
38	If it cannot be reproduced, classify it:
39
40	- `timing`: race, async ordering, cache, clock, load, flaky dependency;
41	- `environment`: OS, Node/Python/runtime version, CI image, env vars, permissions;
42	- `state`: database rows, local cache, session, global singleton, test pollution;
43	- `external`: API outage, rate limit, auth/session expiry, vendor UI/API change;
44	- `unknown`: not enough evidence yet.
45
46	For production-adjacent failures, stay read-only until the user approves a bounded mutation.
47
48	### 2. Localize
49
50	Identify the failing layer before editing:
51
52	- UI/browser: console, DOM state, network request, route, hydration, asset loading.
53	- API/backend: request/response, handler, service, auth, validation, logs.
54	- Database/data: query, migration, schema, constraints, data shape, transaction.
55	- Build/tooling: config, dependency, compiler, bundler, runtime version.
56	- External service: credentials presence, status, rate limits, API contract, webhook.
57	- Test harness: fixture, mock, timing, cleanup, wrong expectation.
58
59	Read the relevant code and tests before changing them. Find a nearby working pattern when the codebase has one.
60
61	### 3. Reduce
62
63	Narrow the failure:
64
65	- run the single failing test before the whole suite;
66	- isolate the route, function, query, fixture, or input;
67	- remove unrelated changes from the hypothesis, not from the user's worktree;
68	- use logs or temporary instrumentation only where they answer a specific question;
69	- avoid broad refactors during diagnosis.
70
71	If a regression has a known good commit and the repo is clean enough, consider `git bisect`. Never use destructive git commands without explicit approval.
72
73	### 4. Fix The Root Cause
74
75	Name the cause in one sentence before editing:
76
77	```text
78	Root cause: <why the failure occurs, not merely where it appears>
79	```
80
81	Bad: "Form crashes because `user.name` is undefined."
82
83	Better: "The API can return users without `profile`, but the form assumes `profile.name` exists and has no empty-state branch."
84
85	Make the smallest change that addresses the cause. Do not bundle adjacent cleanup, dependency updates, or stylistic rewrites unless they are required for the fix.
86
87	### 5. Guard Against Recurrence
88
89	Choose a guard proportionate to risk:
90
91	- Unit test for pure logic.
92	- Integration test for API/data/service boundaries.
93	- Browser or Playwright smoke for critical UI flows.
94	- Migration/rollback dry-run for data changes.
95	- Runbook/session note for operational failures.
96	- Monitoring/logging only when the issue is intermittent or production-observable.
97
98	For bug fixes, prefer a test or focused check that would fail without the fix and pass with it.
99
100	### 6. Verify
101
102	Verify in this order:
103
104	1. Focused reproduction no longer fails.
105	2. New or updated guard passes.
106	3. Neighboring tests/checks pass.
107	4. Broader suite/build/smoke passes when touched surface warrants it.
108	5. Original

People who liked this also viewed

6 picks

Type

debugging-and-error-recovery

20stars2forks

View on GitHub

How to install debugging-and-error-recovery?

pimenov/codex-first-skills-pack/debugging-and-error-recovery

$npx -y skills add pimenov/codex-first-skills-pack --skill debugging-and-error-recovery

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Debugging And Error Recovery
2
3	## Overview
4
5	When something breaks, stop adding scope. Preserve the evidence, reproduce the failure, localize it, reduce it, fix the root cause, guard against recurrence, and only then resume.
6
7	This skill prevents the common agent failure mode: changing several things at once and declaring success because the latest symptom disappeared.
8
9	## Stop-The-Line Rule
10
11	When any unexpected failure appears:
12
13	1. Stop feature work and unrelated cleanup.
14	2. Preserve the exact error, command, environment clue, input, URL, test name, or repro step.
15	3. Reproduce the failure or document why it cannot be reproduced.
16	4. Localize the failing layer.
17	5. Reduce to the smallest useful failing case.
18	6. Fix the root cause, not only the symptom.
19	7. Add a guard: test, assertion, smoke check, runbook note, or monitor.
20	8. Run focused verification first, then broader verification when risk warrants it.
21
22	Do not keep repeating the same failed guess. If the first real attempt does not solve a tool, package, API, networking, infrastructure, or vendor problem, check current official docs, issue trackers, or known community patterns before the next fix. Use `source-driven-development` for version-sensitive APIs and tools.
23
24	## Triage
25
26	### 1. Reproduce
27
28	Make the failure happen on demand when possible.
29
30	Capture:
31
32	- exact command or user action;
33	- exact error lines, stack frame, failing test name, HTTP status, or log signature;
34	- current branch/worktree state when in a repo;
35	- relevant runtime versions and env key presence without raw secrets;
36	- whether the failure is local, CI, staging, production, or external-service only.
37
38	If it cannot be reproduced, classify it:
39
40	- `timing`: race, async ordering, cache, clock, load, flaky dependency;
41	- `environment`: OS, Node/Python/runtime version, CI image, env vars, permissions;
42	- `state`: database rows, local cache, session, global singleton, test pollution;
43	- `external`: API outage, rate limit, auth/session expiry, vendor UI/API change;
44	- `unknown`: not enough evidence yet.
45
46	For production-adjacent failures, stay read-only until the user approves a bounded mutation.
47
48	### 2. Localize
49
50	Identify the failing layer before editing:
51
52	- UI/browser: console, DOM state, network request, route, hydration, asset loading.
53	- API/backend: request/response, handler, service, auth, validation, logs.
54	- Database/data: query, migration, schema, constraints, data shape, transaction.
55	- Build/tooling: config, dependency, compiler, bundler, runtime version.
56	- External service: credentials presence, status, rate limits, API contract, webhook.
57	- Test harness: fixture, mock, timing, cleanup, wrong expectation.
58
59	Read the relevant code and tests before changing them. Find a nearby working pattern when the codebase has one.
60
61	### 3. Reduce
62
63	Narrow the failure:
64
65	- run the single failing test before the whole suite;
66	- isolate the route, function, query, fixture, or input;
67	- remove unrelated changes from the hypothesis, not from the user's worktree;
68	- use logs or temporary instrumentation only where they answer a specific question;
69	- avoid broad refactors during diagnosis.
70
71	If a regression has a known good commit and the repo is clean enough, consider `git bisect`. Never use destructive git commands without explicit approval.
72
73	### 4. Fix The Root Cause
74
75	Name the cause in one sentence before editing:
76
77	```text
78	Root cause: <why the failure occurs, not merely where it appears>
79	```
80
81	Bad: "Form crashes because `user.name` is undefined."
82
83	Better: "The API can return users without `profile`, but the form assumes `profile.name` exists and has no empty-state branch."
84
85	Make the smallest change that addresses the cause. Do not bundle adjacent cleanup, dependency updates, or stylistic rewrites unless they are required for the fix.
86
87	### 5. Guard Against Recurrence
88
89	Choose a guard proportionate to risk:
90
91	- Unit test for pure logic.
92	- Integration test for API/data/service boundaries.
93	- Browser or Playwright smoke for critical UI flows.
94	- Migration/rollback dry-run for data changes.
95	- Runbook/session note for operational failures.
96	- Monitoring/logging only when the issue is intermittent or production-observable.
97
98	For bug fixes, prefer a test or focused check that would fail without the fix and pass with it.
99
100	### 6. Verify
101
102	Verify in this order:
103
104	1. Focused reproduction no longer fails.
105	2. New or updated guard passes.
106	3. Neighboring tests/checks pass.
107	4. Broader suite/build/smoke passes when touched surface warrants it.
108	5. Original

People who liked this also viewed

6 picks

Type