Skip to main content

Rules and hooks that act during investigation and fixing

Once the tools are in place at Step 0, it is finally time to investigate and fix. At this stage, every time you read a file and every time you rewrite one, another element steps in.

Reading a file brings a rule along automatically​

While investigating the bug, /debug does a Read on the implementation of fetchUser (user-service.ts). At this moment, triggered by opening a .ts file, the relevant path-scoped rule is loaded automatically.

rule frontmatter (illustrative)
---
name: typescript-strict
paths:
  - "**/*.ts"
  - "**/*.tsx"
---

When you open a file matching the paths: glob, that rule is injected into the context. Read a .ts and typescript-strict.md (no any, prefer type guards, etc.) or coding-patterns.md starts to apply, for example. This "switch loading by paths:" mechanism is Claude Code standard (📦); the contents of the rule files are the author's own (🔧).

Thanks to this "load only when you open the target" design, the TypeScript norms work only when you touch TypeScript, and the Terraform norms only when you touch .tf. Because what you need surfaces in the situation where you need it, you do not have to carry everything all the time (for the details of the mechanism, see How rules are loaded).

The moment you rewrite, a hook steps in​

It turns out the cause is "returning array[0] when the array is empty," and you go in to fix it. Here, when you run Edit / Write, two kinds of hooks step in before and after. These are the Computational mechanisms in Guides and Sensors terms.

Before the fix (PreToolUse) — stop dangerous writes​

Just before Edit / Write runs, check-protected-files.sh fires. If you try to rewrite .env along the way, or to hardcode a secret key into the code, you are stopped here. This hook was built—out of the experience of nearly doing exactly that, mis-editing .env or a lockfile, or writing secrets inline—not to "warn in prose" but to "physically stop it before it runs."

What check-protected-files.sh stops (excerpt)
# Writes to .env / credentials / lockfiles / .git/ / secrets/
# Hardcoded AWS Access Key (AKIA...) / GitHub PAT (ghp_...) etc.
echo "Blocked: '$FILE_PATH' is a protected target..." >&2
exit 2

Because you are bounced back with exit 2, "accidentally committing a secret" does not happen structurally.

After the fix (PostToolUse) — block "the easy fix"​

This is the mechanism that matters most in debugging. Right after Edit / Write, check-suppression.sh runs and detects newly added comments that suppress lint or type errors.

What check-suppression.sh detects (excerpt)
PATTERNS='eslint-disable|@ts-ignore($|[^a-zA-Z])|# type: ignore|# noqa|//[[:space:]]*tslint:disable'
# If newly added, exit 2 (stderr returns to Claude, prompting self-correction)

Suppose that, instead of fixing a type error at its root, you add a single // @ts-ignore line to silence it. That is exactly the /debug anti-pattern "a symptomatic fix that only hides the symptom." check-suppression.sh detects that new addition, returns stderr to Claude with exit 2, and makes it fix the already-applied edit itself. Unlike PreToolUse, a PostToolUse exit 2 does not block execution—the edit is not automatically undone; it is a mechanism that keeps you from moving on while a suppression remains. This hook, too, was born from the repeated failure that "the easy fix" only hides symptoms. Because a comment that silences an error looks like a fix at first glance, prose norms alone could not stop it.

By the way, PostToolUse also has other hooks registered, such as one that immediately saves a subagent's deliverables and one that monitors the rate limit (for the full list, see How hooks work). This chapter narrows in on the two that matter to the /debug fixing story.

The double stance of Guide and Sensor

The body of /debug's SKILL.md also says "avoid symptomatic fixes" (Inferential Guide). But prose instructions slip through probabilistically. So check-suppression.sh (Computational Sensor) deterministically catches the one that slipped through. Guarding the same norm with both prose and machine is the harness's typical stance.

The interrupt map for this stage​

Summary of this chapter

The key points:

  • Opening a file auto-loads the path-scoped rule corresponding to its type
  • Just before the fix, check-protected-files.sh stops writes to secrets / protected files
  • Right after the fix, check-suppression.sh detects suppressions like @ts-ignore and prompts self-correction
  • The prose norm "avoid symptomatic fixes" is backed mechanically by a hook

Next, in The verify loop, we look at the iteration that turns "I fixed it" into "I proved it is fixed."