Skip to content
Skills Library
Programming · Analysis

trace

/trace

Use when encountering bugs, test failures, runtime errors, unexpected behavior, broken builds, or "this doesn't work" reports. Systematic root-cause analysis before any patch — never blind-patches symptoms. Standalone (off the spec → scope → dispatch chain). Ends with a thinking-tier review of the fix.

Licence
Apache-2.0
Last repository change
12.08.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 12.08.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

Use when encountering bugs, test failures, runtime errors, unexpected behavior, broken builds, or "this doesn't work" reports. Systematic root-cause analysis before any patch — never blind-patches symptoms. Standalone (off the spec → scope → dispatch chain). Ends with a thinking-tier review of the fix.

Triggers from the description

this doesn
Original author description

Use when encountering bugs, test failures, runtime errors, unexpected behavior, broken builds, or "this doesn't work" reports. Systematic root-cause analysis before any patch — never blind-patches symptoms. Standalone (off the spec → scope → dispatch chain). Ends with a thinking-tier review of the fix.

How it works

  1. Per-Step Agent Map (DOCTRINE rule 12)
  2. Step 1 — Reproduce
  3. Step 2 — Gather Evidence (parallel)
  4. Step 3 — Hypothesize
  5. Step 4 — Verify
  6. Step 5 — Fix at Root
  7. Step 6 — Regression Test
  8. Step 7 — Memory + Final Review
  9. Anti-Patterns (refuse these)
  10. Output Format
Original SKILL.md headings · 122 lines, 821 words
SKILL.md preview
---
name: trace
description: Use when encountering bugs, test failures, runtime errors, unexpected behavior, broken builds, or "this doesn't work" reports. Systematic root-cause analysis before any patch — never blind-patches symptoms. Standalone (off the spec → scope → dispatch chain). Ends with a thinking-tier review of the fix.
---

# Trace

Root cause, not symptom. Never patch over a bug without understanding why it happened.

Dispatcher and reviewer — Opus 4.7 (thinking-tier). Implementer/Searcher/Writer — Sonnet 4.6.

## Per-Step Agent Map (DOCTRINE rule 12)

Every substantive step dispatches at least one Agent.

| Step | Worker tier | Thinking tier | Notes |
|---|---|---|---|
| 1 — Reproduce | Searcher (Sonnet) if repro missing | **Reviewer** (Opus) confirms repro is valid | Both tiers if dispatched |
| 2 — Gather evidence | Searcher × 3 (Sonnet) parallel | **Reviewer** (Opus) verifies evidence coverage | Both tiers |
| 3 — Hypothesize | — | **Debugger** (Opus) produces ranked hypotheses | Pure thinking |
| 4 — Verify | Implementer (Sonnet) minimal change | **Debugger** (Opus) re-evaluates against evidence | Both tiers · loop |
| 5 — Fix at root | Implementer (Sonnet) | **Reviewer** (Opus) checks no error-swallow / no symptom-patch | Both tiers |
| 6 — Regression test | Writer (Sonnet) | **Reviewer** (Opus) confirms test fails-without / passes-with | Both tiers |
| 7 — Memory + final | Writer (Sonnet) appends pitfall | **Reviewer** (Opus) final validation | Both tiers |

## Step 1 — Reproduce

Agents — `Searcher` (Sonnet, if needed) ⇒ **Reviewer** (Opus).

1. Confirm the bug is reproducible.
2. If repro steps missing — dispatch `Searcher — locating bug reproduction in recent changes/tests`.
3. Dispatch `**Reviewer** — confirming reproduction is valid` to validate the repro actually fails for the stated reason (not a flake).
4. If environmental (CI-only, intermittent, time-dependent) — flag explicitly before proceeding.

## Step 2 — Gather Evidence (parallel)

Agents — `Searcher` × 3 (Sonnet) parallel ⇒ **Reviewer** (Opus).

1. Dispatch simultaneously in a single message:
   - `Searcher — reading error stack traces and logs`
   - `Searcher — mapping the code paths involved`
   - `Searcher — finding related tests (passing and failing)`
2. Dispatch `**Reviewer** — verifying evidence coverage` to confirm the three Searchers actually triangulate the failure surface. If gaps remain, redispatch.

## Step 3 — Hypothesize

Agents — **Debugger** (Opus, thinking-tier).

Dispatch `**Debugger** — root cause analysis: <bug-summary>` — model: opus.

Apply **5 Whys** + **hypothesis testing** + **bisect mindset**:
- Why does this fail? → because X → why X? → because Y → continue to root
- Output 1–3 hypotheses ranked by likelihood, each with:
  - **What** — suspected root cause
  - **Evidence** — what supports it
  - **Counter-evidence** — what would falsify it
  - **Test** — minimal change to verify

## Step 4 — Verify

Agents — `Implementer` (Sonnet) ⇒ **Debugger** (Opus).

1. Pick highest-ranked hypothesis.
2. Dispatch `Implementer — verifying hypothesis: <hypothesis>` — make the minimal change needed to confirm/falsify.
3. Dispatch `**Debugger** — re-evaluating hypothesis against test result` to re-check against the evidence from Step 2.
4. Confirmed → proceed to Step 5. Falsified → return to Step 3 with next hypothesis.

## Step 5 — Fix at Root

Agents — `Implementer` (Sonnet) ⇒ **Reviewer** (Opus).

1. Dispatch `Implementer — fixing root cause: <root-cause>` with full context: the bug, the verified root cause, the minimal fix.
2. Dispatch `**Reviewer** — checking fix is at root` to verify the fix actually addresses the cause and doesn't patch the symptom.

Constraints (non-negotiable):
- No error swallowing
- No defensive try/catch around the symptom
- No flags or feature gates to hide the bug

## Step 6 — Regression Test

Agents — `Writer` (Sonnet) ⇒ **Reviewer** (Opus).

1. Dispatch `Writer — adding regression test for <bug>`.
2. Dispatch `**Reviewer** — confirming regression test fails-without and passes-with the fix`.
3. If existing suite had gaps that allowed this bug → note in `.hyperflow/memory/pitfalls.md`.

## Step 7 — Memory + Final Review

Agents — `Writer` (Sonnet) ⇒ **Reviewer** (Opus).

1. Dispatch `Writer — appending pitfall to .hyperflow/memory/pitfalls.md` per [memory-system.md](../hyperflow/memory-system.md): the bug pattern, why tests missed it, prevention strategy. Tags — `pitfall` plus domain tags.
2. Dispatch `**Reviewer** — final validation of fix + test + memory entry`. This is the integration review for the trace flow.

## Anti-Patterns (refuse these)

| Symptom patch | Why it's wrong |
|---|---|
| "Just catch the exception" | Find why it threw |
| "Add a null check" | Find why it was null |
| "Increase the timeout" | Find why it's slow |
| "Retry on failure" | Understand the failure mode first |

## Output Format

```
── Debug Result ─────────────────────
Bug: <one-line>
Reproducible: yes / no / intermittent
Root cause: <one-line>
Fix: <one-line summary>
Files changed: <list>
Regression test: <path>
─────────────────────────────────────
```

End with usage summary (model names, agent count, token totals) per [output-style.md](../hyperflow/output-style.md).

## Hand-off

Debug is **off the auto-chain** — it's standalone. After Step 7 reviewer passes, stop and suggest `/hyperflow:deploy` to run pre-push gates and commit the fix + regression test together. Do **not** auto-invoke ship — push requires explicit user opt-in.

## Doctrine

Full rules in [DOCTRINE.md](../hyperflow/DOCTRINE.md). See also [worker-prompt.md](../hyperflow/worker-prompt.md) and [reviewer-prompt.md](../hyperflow/reviewer-prompt.md).

Versions

RepositoryScoreLicence
This page · ccplugins/awesome-claude-code-plugins100Apache-2.0
jeremylongshore/tons-of-skills-marketplace100MIT
r3dlex/oh-my-auggie100Apache-2.0
zereight/gitlab-mcp100MIT
proxify-dev/agentic-kit100MIT
biliboss/skills100MIT
oliver-kriska/claude-elixir-phoenix100MIT
moonklabs/aiwf100MIT
Soul-Brews-Studio/arra-oracle-skills-cli100MIT

Database snapshot: 13.11.2026 · package version 96d5cf1019a1 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90hyperflow-trace
    Hyperflow debugging. Use for bugs, test failures, runtime errors, broken builds, or "this doesn't work" reports — verbs like debug, "fix it", solve, "why is X failing", "Y is broken", or a pasted stack trace. Systematic root-cause analysis before any patch — never blind-patch symptoms.
  • 100root-cause-analysis
    Performs systematic root cause analysis to identify the true source of bugs, errors, and unexpected behavior through structured investigation phases — not just treating symptoms. Use when a user reports a bug, crash, error, or broken behavior and needs to debug, troubleshoot, or…
  • 95systematic-debugging
    Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
  • 100systematic-debugging
    Systematic debugging approach for errors, test failures, and unexpected behavior. Use when encountering bugs, test failures, errors, or when debugging is needed. Prevents common anti-patterns like random fixes, skipping root cause analysis, and thrashing.
  • 100systematic-debugging
    Use when something is broken — an error message, stack trace, failing test, crash, wrong output, "it doesn't work", build failure, or unexpected behavior. Finds the root cause with evidence before changing code, then saves the fix to memory.
  • 100sr-systematic-debugging
    Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.