# Diagnostic Reasoning

Load before scoping a reported bug and before acting on a diagnostic report.

- Repository: https://github.com/kunchenguid/firstmate (8480 stars)
- Category: Engineering
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add kunchenguid/firstmate --skill diagnostic-reasoning -g -a claude-code -y`
Codex: `npx skills add kunchenguid/firstmate --skill diagnostic-reasoning -g -a codex -y`
Cursor: `npx skills add kunchenguid/firstmate --skill diagnostic-reasoning -g -a cursor -y`
Gemini CLI: `npx skills add kunchenguid/firstmate --skill diagnostic-reasoning -g -a gemini-cli -y`

## Description

Load before scoping a reported bug and before acting on a diagnostic report.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# diagnostic-reasoning

Use this procedure before scoping a reported bug and before acting on a diagnostic report.
This skill is the single owner of Firstmate's bug-diagnosis reasoning procedure.
Firstmate applies it when briefing delegated investigation and evaluating the resulting evidence, without taking over project-specific investigation itself.

## Establish the observed behavior

Start from the end user's experience rather than an internal error string or an implementation hypothesis.
Require an end-to-end reproduction aligned with the real user path whenever it is feasible and safe.
If a faithful reproduction is not feasible, record the exact limitation and use the closest representative path without presenting it as equivalent evidence.
Capture the expected behavior, observed behavior, setup, inputs, and repeatability before assigning a cause.

Separate these three facts explicitly:

- The **initiating trigger** is the event, input, or transition that starts the faulty behavior.
- The **masking condition** is the independent state, environment, timing, cache, configuration, or path difference that hides or exposes the fault.
- The **visible symptom** is what the end user or operator can actually observe.

Do not collapse those facts into one label.
A masking condition may explain why a fault appears only sometimes without being the initiating cause, and the visible symptom may be several layers downstream from both.

## Test the causal explanation

Inspect the failing path and a proven path where the intended behavior is known to work.
Compare their inputs, state transitions, dependencies, timing, and control flow to find the earliest meaningful divergence.
Inspect relevant history, including blame, commits, migrations, and prior implementations, when it can explain why the paths diverged or which invariant was intended.
Do not treat the most recent nearby change as causal without evidence.

The rest: https://github.com/kunchenguid/firstmate/blob/HEAD/.agents/skills/diagnostic-reasoning/SKILL.md