Index of every page on this site: llms.txt
All skills
kunchenguid avatar

/diagnostic-reasoning

@427056c
by Kun Chenkunchenguid/firstmate9k stars
2,779
Run it yourself

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

Use this Skill: https://skilld.dev/gh/kunchenguid/firstmate/diagnostic-reasoning

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈25 tokens for metadata: the name and description. ≈868 when used: this file.

Description uses 1.2% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈99 characters, or 1.2%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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.

Identify the smallest counterfactual that should change the outcome if the leading explanation is true. Change one condition at a time where practical, and record whether the symptom appears, disappears, or remains unchanged. Seek disconfirming evidence deliberately: name what observation would falsify the leading explanation, run that check when feasible, and retain contradictory results instead of explaining them away. Compare the final explanation against the proven path and show why the proposed causal boundary accounts for both the failure and the success.

Scope and act on the result

A diagnosis brief should ask for the reproduction, trigger/mask/symptom separation, divergent and proven path comparison, relevant history, smallest counterfactual, and disconfirming evidence in the report. A diagnostic report should distinguish observed facts from hypotheses and state any unresolved uncertainty that could change the recommended scope. Before acting on the report, verify that its claimed cause explains the end-user reproduction and the proven path without relying on an untested masking condition. If a load-bearing element is missing, route a focused follow-up investigation instead of treating confidence or implementation detail as proof. A diagnosis or implementation-ready recommendation is evidence, not authorization to change code. Implementation still requires the captain's request or another existing lifecycle authority, and the reproduction should become the regression test when a fix is authorized.

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts4mo3 checks · Risk SAFE
  • Gen Agent Trust Hub4mo

    This skill consists entirely of a reasoning framework for bug diagnosis and contains no executable code, network operations, or external dependencies.

  • Socket4mo

    No alerts

  • Snyk4mo

    Risk: LOW · No issues

Signed by skilld at 427056c. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last week.

Activeupdated last month
user-invocable
false
metadata
{
  "internal": true
}

README badge

README badge for kunchenguid/firstmate/diagnostic-reasoning