diagnosing-bugs · Skill Details

Mechanism

When It Triggers · How It Works · What It Produces

Breaks down how the skill works and what it produces, so you can quickly judge whether it fits your scenario and value.

Trigger: Automatically loaded by the agent when the user mentions "diagnose", "debug", "broken", "slow", or similar keywords; can also be invoked manually. Phase 6 may recommend transitioning to /improve-codebase-architecture if architectural issues are found.
Mechanism: Six strictly sequenced phases, each with clear completion criteria before the next can begin. Phase 1 is the core — building a "tight" (fast, deterministic, agent-runnable, red-capable) feedback loop, listing 10 construction methods (from failing test to HITL bash script). Phase 3 requires 3-5 falsifiable hypotheses, optionally shown to the user for prioritisation. Phase 5 requires a "correct seam" for regression tests, otherwise recording it as an architectural finding.
Output: Bug fix + regression test (if a correct seam exists), or an architectural issue record (if no suitable seam, transitioning to improve-codebase-architecture). The commit message includes the verified hypothesis for future reference.

Use Cases

Two Typical Use Cases

Scenario 01

Fixing an intermittent bug

A flaky test failure appears in the testing environment. The developer invokes `/diagnosing-bugs`. The skill first tries to build a reliable reproduction loop, running it 100 times in parallel to raise the reproduction rate. Once a "red" signal is obtained, it minimises the repro, generates 3-5 hypotheses, verifies each, fixes the bug, and writes a regression test. All debug logs are tagged with a uniform prefix and bulk-cleaned after the fix.

Scenario 02

Investigating a performance regression

An API endpoint response time increases from 200ms to 2s. The developer invokes `/diagnosing-bugs`. The skill enters performance branch mode: first establishing a baseline measurement (timing harness, profiler, query plan), then bisecting instead of logging to locate the regression. After fixing, if no suitable seam exists for a regression test, it records this architectural finding and recommends transitioning to `/improve-codebase-architecture`.

Skill Relationships

Which Skills I Use · Which Skills Use Me

Dependency relationships read as "the upper tier points to the lower tier." The current Skill sits in the middle tier — above are Skills that depend on it, below are Skills it depends on.

Tier 1 · These Skills Use Me

ask-mattWorkflow

Tier 2 · Current Skill

diagnosing-bugsWorkflow

Tier 3 · I Use These Skills

improve-codebase-architectureWorkflow

Full Relationship Graph

Browse this skill's relationships within its skillset. Click a node to switch the side panel; use the search box to jump to any skill.

Skill File

SKILL.md

Open in GitHub ↗

SKILL.mdLoading from GitHub…

Skill Composition

Open in GitHub ↗

SKILL.md33.3%
scripts33.3%
other33.3%

▸skills/diagnosing-bugs/
▸diagnosing-bugs
- ·SKILL.md
- ▸agents
  - ·openai.yaml
- ▸scripts
  - ·hitl-loop.template.sh

Per the Agent Skills spec, SKILL.md is the only required file. The colored bars classify the rest into the three spec-aligned optional directories (scripts / references / assets) and an 'other' bucket. The full directory tree is below.

Related in Skillset

You May Also Need These Skills

ask-matt

A router skill for the entire skillset: when the user can't remember which skill to use or which flow fits their situation, they invoke this to get a recommendation. It describes the main "idea → ship" flow (grill-with-docs → to-spec/to-tickets → implement), plus on-ramps (triage, diagnosing-bugs, wayfinder), codebase health (improve-codebase-architecture), vocabulary layers (domain-modeling, codebase-design), and standalone skills (grill-me, prototype, research, teach). Following its map leads users to the correct workflow entry point.

Workflow

code-review

A two-axis code review skill: reviews a diff (from a fixed point to HEAD) along both Standards (coding standards + Fowler smell baseline) and Spec (faithful implementation of the originating issue/PRD). Both axes run as parallel sub-agents to avoid context pollution. The report aggregates findings without merging conclusions, ensuring "passes standards but implements the wrong thing" and "implements the right thing but breaks conventions" are both surfaced independently.

Workflow

codebase-design

A shared vocabulary skill for deep module design: provides a precise set of design terms (Module, Interface, Depth, Seam, Adapter, Leverage, Locality) guiding agents and developers to design "deep modules" — a lot of behaviour behind a small interface. Includes design principles (the deletion test, the interface is the test surface) and testability guidelines. A reference skill consumed by other skills (e.g., improve-codebase-architecture, tdd) and invoked directly by engineers.

Style Guide

domain-modeling

An active discipline for building and sharpening a project's domain model: challenges terms in real time during conversation, clarifies fuzzy language, stress-tests scenarios, cross-validates code against the model, updates CONTEXT.md inline, and sparingly creates ADRs (only when the decision is hard to reverse, surprising without context, and the result of a real trade-off). Not a static glossary — a living process that continuously polishes the domain model.

Workflow