# TS Debug

> Debug. Only explicitly triggered by user.

- Skill: `tstelzer/ts-debug` (Agent Skill)
- Install (CLI): `npx skillmds@latest add tstelzer/ts-debug`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tstelzer/ts-debug/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tstelzer (https://skillmd.com/u/tstelzer)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tstelzer/ts-debug

---


# Debug

## Required Reading

- skill: ts-principles
  - Read `ts-principles/SKILL.md`.
  - Read every linked principle detail document before debugging.

## Role

Debug is a repair judge.

It turns a concrete symptom into a causal explanation and an
architecture-aligned fix. It rejects patches that hide the symptom without
fixing the owner of the defect.

The judge may edit code. It may dispatch reviewers after its fix when the
change has meaningful risk, touches shared contracts, changes behavior across
boundaries, or the user asks for review.

## Sub-Agent Selection

Use this section when this skill spawns sub-agent reviewers.

- Choose the first available entry for the reviewer role.
- If the harness cannot set provider, model line, and reasoning separately,
  choose the closest available model and record what actually ran.
- When spawning more than one reviewer, use different provider and model-line
  pairs when model availability permits.

### Review Worker

| Priority | Provider | Model line | Reasoning |
| --- | --- | --- | --- |
| 1 | Anthropic | `fable` latest | `high` |
| 2 | OpenAI | `astra` latest | `high` |
| 3 | OpenRouter | `glm` latest | `xhigh` |
| 4 | Anthropic | `opus` latest | `high` |
| 5 | OpenAI | `sol` latest | `high` |
| 6 | OpenRouter | `gemini flash` latest | `high` |
| 7 | OpenRouter | `deepseek v4 pro` latest | `high` |
| 8 | Cursor | `composer` | `high` |

## Workflow

1. FRAME_SYMPTOM
2. REPRODUCE
3. TRACE_CAUSE
4. CHOOSE_REMEDY
5. APPLY_FIX
6. VERIFY
7. REVIEW_IF_NEEDED
8. HANDOFF

### FRAME_SYMPTOM

- Capture the exact error, command, input, environment, and expected behavior
  when available.
- Name the repository root and check the starting worktree state before edits.
- Treat supplied logs, stack traces, screenshots, and failing commands as
  evidence, not as the full cause.

### REPRODUCE

- Reproduce the failure locally when possible.
- Use the smallest command that shows the symptom.
- If reproduction is unavailable, state why and continue with weaker confidence.

### TRACE_CAUSE

- Identify the failing boundary: command, tool, API, module, data contract,
  runtime state, dependency, environment, or external service.
- Inspect nearby architecture, existing patterns, and source-owned contracts
  before choosing a remedy.
- Explain the causal chain before editing code.
- Fix the owner of the defect, not the nearest caller that can mask it.

### CHOOSE_REMEDY

Before editing, classify the remedy:

- `causal fix`: changes the code or contract that owns the defect.
- `boundary adaptation`: handles a real external contract at the edge.
- `containment`: mitigates an upstream or environmental defect.
- `workaround`: hides the symptom without fixing ownership.

Apply `causal fix` or `boundary adaptation`.

Apply `containment` only when the cause is outside the repo or cannot be fixed
now. Record the reason and removal condition.

Do not apply `workaround`.

Treat these as suspect until proven necessary:

- build-tool wrappers
- broad catches or swallowed errors
- loosened types
- skipped tests or changed snapshots
- sleeps, retries, and timing changes
- broad fallback paths
- special cases far from the owning boundary

### APPLY_FIX

- Keep the fix scoped to the owner of the defect.
- Prefer deleting wrong code, correcting contracts, or moving logic to the right
  boundary over adding wrappers, flags, or fallbacks.
- Add or update tests when the changed behavior needs proof.
- Before finishing the fix, check whether the causal explanation, boundary
  adaptation, containment, invariant, failure mode, or contract needs docs where
  a future maintainer will look.
- Add `/** ... */`, a short why-comment, or source-owned docs when code cannot
  carry the reason. Do not add comments that restate the code.
- Preserve unrelated user changes.

### VERIFY

- Re-run the reproduction command.
- Run the smallest additional check that proves the fix changed behavior for
  the right reason.
- If a required check cannot run after the obvious fix, stop and surface the
  failure.

### REVIEW_IF_NEEDED

Dispatch reviewers when the fix touches auth, persistence, public APIs,
migrations, shared tooling, build behavior, dependency resolution, concurrency,
or cross-module contracts.

Choose reviewers from the `Review Worker` list.

Reviewer prompts must include:

- the original symptom
- the causal explanation
- the debug-owned diff
- verification run
- assigned provider, model line, and reasoning level
- suspected risk areas

Reviewers must look for false fixes, hidden workarounds, contract drift,
overbroad changes, missing tests, and behavior masked by tooling changes.

### HANDOFF

Report:

- Symptom and reproduction status.
- Root cause and owning boundary.
- Remedy classification.
- Fix applied.
- Verification run and result.
- Review result, open risks, or deviations.