القائمة
Use when errors occur deep in execution - traces bugs backward through call stack to find original trigger, not just symptom
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Use when shaping a feature before implementation - turns rough ideas into an approved markdown spec and local task directory
Use to execute an approved local markdown task directory iteratively - work the current Now slice, update docs, then stop
Use when implementation is complete and verified - delete finished local task docs, present integration options, and clean up safely
Use for advanced markdown task-doc operations - split work, reprioritize slices, delete finished local task dirs, and keep docs clean
Use after executing a task directory - verifies implementation against plan.md, acceptance checks, and anti-goals
Use when starting any conversation - establishes skill selection and the local task-doc workflow
| name | root-cause-tracing |
| description | Use when errors occur deep in execution - traces bugs backward through call stack to find original trigger, not just symptom |
<codex_compat> This skill was ported from Claude Code. In Codex:
SKILL.md from disk.spawn_agent (dispatch in parallel via multi_tool_use.parallel when needed).<skill_overview> Bugs manifest deep in the call stack; trace backward until you find the original trigger, then fix at source, not where error appears. </skill_overview>
<rigidity_level> MEDIUM FREEDOM - Follow the backward tracing process strictly, but adapt instrumentation and debugging techniques to your language and tools. </rigidity_level>
<quick_reference>
| Step | Action | Question |
|---|---|---|
| 1 | Read error completely | What failed and where? |
| 2 | Find immediate cause | What code directly threw this? |
| 3 | Trace backward one level | What called this code? |
| 4 | Keep tracing up stack | What called that? |
| 5 | Find where bad data originated | Where was invalid value created? |
| 6 | Fix at source | Address root cause |
| 7 | Add defense at each layer | Validate assumptions as backup |
Core rule: Never fix just where error appears. Fix where problem originates. </quick_reference>
<when_to_use>
Example symptoms:
<the_process>
Read the complete error:
Error: Invalid email format: ""
at validateEmail (validator.ts:42)
at UserService.create (user-service.ts:18)
at ApiHandler.createUser (api-handler.ts:67)
at HttpServer.handleRequest (server.ts:123)
at TestCase.test_create_user (user.test.ts:10)
Symptom: Email validation fails on empty string Location: Deep in validator utility
DON'T fix here yet. This might be symptom, not source.
What code directly causes this?
// validator.ts:42
function validateEmail(email: string): boolean {
if (!email) throw new Error(`Invalid email format: "${email}"`);
return EMAIL_REGEX.test(email);
}
Question: Why is email empty? Keep tracing.
Use stack trace:
// user-service.ts:18
create(request: UserRequest): User {
validateEmail(request.email); // Called with request.email = ""
// ...
}
Question: Why is request.email empty? Keep tracing.
// api-handler.ts:67
async createUser(req: Request): Promise<Response> {
const userRequest = {
name: req.body.name,
email: req.body.email || "", // ← FOUND IT!
};
return this.userService.create(userRequest);
}
Root cause found: API handler provides default empty string when email missing.
Why empty string as default?
// api-handler.ts (SOURCE FIX)
async createUser(req: Request): Promise<Response> {
if (!req.body.email) {
return Response.badRequest("Email is required");
}
const userRequest = {
name: req.body.name,
email: req.body.email, // No default, already validated
};
return this.userService.create(userRequest);
}
After fixing source, add validation at each layer as backup:
// Layer 1: API - Reject invalid input (PRIMARY FIX)
if (!req.body.email) return Response.badRequest("Email required");
// Layer 2: Service - Validate assumptions
assert(request.email, "email must be present");
// Layer 3: Utility - Defensive check
if (!email) throw new Error("invariant violated: email empty");
Primary fix at source. Defense is backup, not replacement. </the_process>
<debugging_approaches>
IMPORTANT: Claude cannot run interactive debuggers. Guide user through debugger commands.
"Let's use lldb to trace backward through the call stack.
Please run these commands:
lldb target/debug/myapp
(lldb) breakpoint set --file validator.rs --line 42
(lldb) run
When breakpoint hits:
(lldb) frame variable email # Check value here
(lldb) bt # See full call stack
(lldb) up # Move to caller
(lldb) frame variable request # Check values in caller
(lldb) up # Move up again
(lldb) frame variable # Where empty string created?
Please share:
1. Value of 'email' at validator.rs:42
2. Value of 'request.email' in user_service.rs
3. Value of 'req.body.email' in api_handler.rs
4. Where does empty string first appear?"
When debugger not available or issue intermittent:
// Add at error location
fn validate_email(email: &str) -> Result<()> {
eprintln!("DEBUG validate_email called:");
eprintln!(" email: {:?}", email);
eprintln!(" backtrace: {}", std::backtrace::Backtrace::capture());
if email.is_empty() {
return Err(Error::InvalidEmail);
}
// ...
}
Critical: Use eprintln!() or console.error() in tests (not logger - may be suppressed).
Run and analyze:
cargo test 2>&1 | grep "DEBUG validate_email" -A 10
Look for:
<finding_polluting_tests>
When something appears during tests but you don't know which:
Binary search approach:
# Run half the tests
npm test tests/first-half/*.test.ts
# Pollution appears? Yes → in first half, No → second half
# Subdivide
npm test tests/first-quarter/*.test.ts
# Continue until specific file
npm test tests/auth/login.test.ts ← Found it!
Or test isolation:
# Run tests one at a time
for test in tests/**/*.test.ts; do
echo "Testing: $test"
npm test "$test"
if [ -d .git ]; then
echo "FOUND POLLUTER: $test"
break
fi
done
</finding_polluting_tests>
Developer fixes symptom, not source
# Error appears in git utility:
fn git_init(directory: &str) {
Command::new("git")
.arg("init")
.current_dir(directory)
.run()
}
Error: "Invalid argument: empty directory"
Developer adds validation at symptom:
fn git_init(directory: &str) {
if directory.is_empty() {
panic!("Directory cannot be empty"); // Band-aid
}
Command::new("git").arg("init").current_dir(directory).run()
}
<why_it_fails>
Fix at source:
function setupTest() {
let _tempDir: string | undefined;
return {
beforeEach() {
_tempDir = makeTempDir();
},
get tempDir(): string {
if (!_tempDir) {
throw new Error("tempDir accessed before beforeEach!");
}
return _tempDir;
}
};
}
What you gain:
# Error in API handler
async createUser(req: Request): Promise {
const userRequest = {
name: req.body.name,
email: req.body.email || "", // Suspicious!
};
return this.userService.create(userRequest);
}
Developer sees empty string default and "fixes" it:
email: req.body.email || "noreply@example.com"
Ships to production
Bug: Users created without email input get noreply@example.com
Database has fake emails, can't distinguish missing from real
<why_it_fails>
Findings:
Fix at source (validate at boundary):
async createUser(req: Request): Promise<Response> {
// Validate at API boundary
if (!req.body.email) {
return Response.badRequest("Email is required");
}
const userRequest = {
name: req.body.name,
email: req.body.email, // No default needed
};
return this.userService.create(userRequest);
}
What you gain:
# Problem: .git directory appearing in source code directory during tests
Symptom location:
Error: Cannot initialize git repo (repo already exists)
Location: src/workspace/git.rs:45
Developer adds check:
if Path::new(".git").exists() {
return Err("Git already initialized");
}
Doesn't help - still appears in wrong place!
<why_it_fails>
1. git init runs with cwd=""
↓ Why is cwd empty?
2. WorkspaceManager.init(projectDir="")
↓ Why is projectDir empty?
3. Session.create(projectDir="")
↓ Why was empty string passed?
4. Test: Project.create(context.tempDir)
↓ Why is context.tempDir empty?
5. ROOT CAUSE:
const context = setupTest(); // tempDir="" initially
Project.create(context.tempDir); // Accessed at top level!
beforeEach(() => {
context.tempDir = makeTempDir(); // Assigned here
});
TEST ACCESSED TEMPDIR BEFORE BEFOREEACH RAN!
Fix at source (make early access impossible):
function setupTest() {
let _tempDir: string | undefined;
return {
beforeEach() {
_tempDir = makeTempDir();
},
get tempDir(): string {
if (!_tempDir) {
throw new Error("tempDir accessed before beforeEach!");
}
return _tempDir;
}
};
}
Then add defense at each layer:
// Layer 1: Test framework (PRIMARY FIX)
// Getter throws if accessed early
// Layer 2: Project validation
fn create(directory: &str) -> Result<Self> {
if directory.is_empty() {
return Err("Directory cannot be empty");
}
// ...
}
// Layer 3: Workspace validation
fn init(path: &Path) -> Result<()> {
if !path.exists() {
return Err("Path must exist");
}
// ...
}
// Layer 4: Environment guard
fn git_init(dir: &Path) -> Result<()> {
if env::var("NODE_ENV") != Ok("test".to_string()) {
if !dir.starts_with("/tmp") {
panic!("Refusing to git init outside test dir");
}
}
// ...
}
What you gain:
<critical_rules>
All of these mean: STOP. Trace backward to find source.
<verification_checklist> Before claiming root cause fixed:
Can't check all boxes? Keep tracing backward. </verification_checklist>
**This skill is called by:** - hyperpowers:debugging-with-tools (Phase 2: Trace Backward Through Call Stack) - When errors occur deep in execution - When unclear where invalid data originatedThis skill requires:
This skill calls:
When stuck: