troubleshoot

Files (1)

• SKILL.md

SKILL.md (first lines)

# Troubleshoot

End-to-end bug workflow for issues **you found while manually testing the app** in a feature built by agents. You are the tester; this skill diagnoses and fixes what you report. Combines:

- **`superpowers:systematic-debugging`** — the root-cause method (no fixes before root cause)
- The project's **backend-log tool** (from the stack profile, optional) for runtime/invocation bugs
- **`superpowers:test-driven-development`** — fix is written test-first (red → green)
- **`superpowers:finishing-a-development-branch`** — ship the fix as a branch → PR

**Autonomy contract:** the agent diagnoses **autonomously** to root cause, then **GATES** — it presents the diagnosis + proposed fix and waits for your approval **before changing any code**. After approval it implements, verifies, and ships without further prompting.

**Run mode (default = autonomous after the gate).** Like `/feature` and `/improve`, this skill is autonomous by default — it does not pause between reproduce → root cause → fix → verify → ship; the single mandatory pause is the **diagnosis gate** (step 3). If the user asks to slow down ("run slowly", "stop at each step", "walk me through it"), also pause to confirm at reproduce, root cause, and verify. The diagnosis gate and the stop-class are **always honored regardless of mode** — they are not waived by autonomous mode.

## Stack profile (READ FIRST)

Load the project's **stack profile**: `docs/stack.md` (preferred) or `sdd-stack.md` at repo root. If neither exists, prompt the user to create one from the plugin's `templates/sdd-stack.template.md`, or auto-detect conservative defaults. Everywhere this skill says **[PROJECT CONTEXT]**, substitute a compact summary from the profile. Everywhere it says **[VERIFY]**, substitute the profile's *Verify commands*. The profile's **Backend-log tool** and **Spec location glob** drive the optional branches below.

## Input

`$ARGUMENTS` should contain a **feature reference** and a **bug description**. Accept loose forms:
- `"leads-list — duplicate leads appear after sync"`
- `"checkout: estimate total shows $0 when line items exist"`
- just a bug description (no feature) — then infer/ask for the feature.

## When to Use

- You manually tested a feature and hit a bug, wrong value, broken interaction, or console error.
- The feature was recently built/changed by an agent and you want it diagnosed and fixed properly.
- A feature that "works" but is **wrong or unsafe by design** — a known tech-debt defect (e.g. a hardcoded auth bypass) — counts as *incorrect behavior* and belongs here, even though it works exactly as built and no spec is changing. ("Change how Y does X" on *correct* behavior is `/improve`; replacing *known-bad* behavior is `/troubleshoot`.)

**Don't use when:**
- It's a new feature request (use `/feature`).
- It's a change/extension to a feature that works as specified (use `/improve`).
- The "bug" is actually a spec change — fix the spec via `/spec`, then `/feature` (or `/improve` when amending).

**Not an exit:** "the user said it's obviously a one-liner" is a *hypothesis*, not a reason to skip. A reported wrong value in an agent-built feature is exactly this skill's job — investigate to root cause and gate the fix regardless of how trivial it looks. Only skip for a typo *you can see is a typo* in a file you're already editing for another reason.

## Process Overview

```dot
digraph troubleshoot {
    rankdir=TB;
    "0. Scope feature + bug" [shape=box];
    "1. Reproduce" [shape=box];
    "2. Root cause (systematic-debugging)" [shape=box];
    "3. GATE: present diagnosis + fix" [shape=diamond];
    "4. Fix test-first (TDD)" [shape=box];
    "5. Verify (test + lint/build)" [shape=box];
    "5b. Code-review gate (/code-review)" [shape=box];
    "6. Branch → PR (finish)" [shape=box];
    "DONE" [shape=doublecircle];

    "0. Scope feature + bug" -> "1. Reproduce";
    "1. Reproduce" -> "2. Root cause (systematic-debugging)";
    "2. Root cause (systematic-debugging)" -> "3. GATE: present diagnosis + fix";
    "3. GATE: present diagnosis + fix" -> "4. Fix test-first (TDD)" [label="approved"];
    "3. GATE: present diagnosis + fix" -> "DONE" [label="rejected / hand off"];
    "4. Fix test-first (TDD)" -> "5. Verify (test + lint/build)";
    "5. Verify (test + lint/build)" -> "5b. Code-review gate (/code-review)";
    "5b. Code-review gate (/code-review)" -> "6. Branch → PR (finish)";
    "6. Branch → PR (finish)" -> "DONE";
}
```

## Step-by-Step Instructions

### 0. Scope the feature + bug

1. Parse `$ARGUMENTS` into `FEATURE_HINT` and `BUG_DESCRIPTION`.
2. **Resolve the feature directory** using the profile's **spec location glob**:
   ```
   <spec glob from profile>  | grep -i "<slug fragment from FEATURE_HINT>"
   ```
   - Exactly one match → that's `FEATURE_DIRECTORY`. Read its `spec.md` (and `plan.md` if present) to understand intended behavior — your **expected-behavior oracle**.
   - Multiple or zero matches → ask the user which feature.
   - No spec (or no spec layer) → proceed without one, but note the diagnosis can't be checked against a spec.
3. Read the profile's **binding context files** — the bug may be a violation of a frozen pattern or a convention.
4. Identify the likely code surface from the spec's impacted-files list + the bug description.

### 1. Reproduce — establish the failing baseline

Invoke **`superpowers:systematic-debugging`** and follow its Phase 1 discipline:

1. Read any error messages / stack traces in the bug description **completely**.
2. Determine reproduction:
   - **UI bug:** identify the route/component and the exact interaction. If reproduction needs the running app, use the **`run`** skill (or `superpowers-chrome:browsing`) to drive it and observe.
   - **Backend/runtime bug:** use the profile's **backend-log tool** to pull logs for the failing invocation (e.g. a `base44:base44-troubleshooter` skill, `supabase functions logs`, `vercel logs`, `heroku logs`). If the profile says "none", inspect logs manually. **Never log or echo secret values — refer to them by name only.**
   - **Build/lint bug:** reproduce with the profile's **[VERIFY]** commands.
3. Confirm you can reproduce **consistently** before going further. If you cannot reproduce, say so and ask the user for exact steps / a screenshot / the failing value — do not guess.

### 2. Root cause investigation

Stay inside `superpowers:systematic-debugging` — **the Iron Law applies: NO FIXES WITHOUT ROOT CAUSE FIRST.**

- Use structured hypothesis testing (analyze → investigate → debug) across the candidate surface. (If a dedicated diagnostic skill like `/sc:troubleshoot` is installed, use it; otherwise do this inline.)
- Trace from symptom to mechanism: read the actual implicated code, the data schema if data shape is involved, and the spec's expected behavior.
- Form a hypothesis, find the evidence that confirms it (the specific line/condition/data), and rule out alternatives. A root cause names *the mechanism*, not just the symptom.
- Check the **stack-specific root-cause classes** the profile's conventions imply (e.g. silently-dropped unknown fields, missing cache/query invalidation, wrong auth accessor, data-mapping drift, concurrent-write races, styling violations).

### 3. GATE — present diagnosis + proposed fix (STOP here)

**Do not change any code yet.** Present to the user:

```
## Diagnosis
- Feature: FEATURE_DIRECTORY (or "no spec — area: …")
- Symptom: <what you reproduced, observed vs expected value/behavior>
- Reproduction: <exact steps / command>
- Root cause: <the mechanism — file:line, the specific condition/data>
- Evidence: <what proves it — log line, failing assertion, schema mismatch, the diff that introduced it>

## Proposed fix
- Change: <what you will change, where>
- Why this is the root-cause fix (not a symptom patch): <reasoning>
- Regression test: <the test you'll write first and what it asserts>
- Risk / blast radius: <other code paths touched, any frozen-pattern concerns>
- Stop-class check: <does the root-cause fix cross any one-way / high-cost boundary? Classify explicitly — none | schema/DB migration | security/auth/secrets boundary | frozen pattern | one-way door (data model, public API/contract shape, architecture — hard to reverse / costly to refactor later). If yes, say which and whether a smaller reversible fix exists.>
- Spec impact: <none | spec is wrong and should be updated first>
```

From miroo93/dev-workflows, MIT.

More from miroo93/dev-workflows