Debugging workflow

Build a minimal bug reproduction before asking an AI agent to fix it

A coding agent can produce a convincing patch for the wrong problem when a bug report mixes symptoms, assumptions and missing environment details. The safer sequence is to establish a small, repeatable failure first. Diagnosis and repair come afterwards.

Why vague bug reports create weak fixes

“The upload sometimes fails” does not identify the input, route, runtime, exact error or expected result. If the first instruction is “fix it”, an agent may alter production code based on a suspected cause rather than observed behaviour. That creates churn and can hide the original fault.

A reproduction brief separates facts from theories. It records what failed, where it failed, the smallest known input and the exact result. Unknowns remain explicit rather than being filled with plausible guesses.

1. Capture the observed failure exactly

Preserve the error message, status code, incorrect output, timestamp and affected command or route. Remove secrets and personal data before sharing evidence. If the report came from another person and has not been reproduced, label it as second-hand.

2. Record the real environment

Inspect the repository commit, runtime version, operating system or container, lockfile and relevant feature flags. Do not infer production configuration from a local environment. Environment differences are often part of the reproduction.

3. State expected versus actual behaviour

Expected: POST /imports accepts the smallest valid CSV and returns HTTP 201.
Actual:   The same fixture returns HTTP 500 with “column index out of range”.

Neither line should contain the suspected root cause. They describe observable outcomes only.

4. Reduce the failing case

Start with the reported path and remove unrelated records, services and steps one at a time. Keep the smallest fixture that still fails. When removing a condition stops the failure, restore it and record the boundary you found.

• Replace a full customer export with the smallest sanitised fixture.
• Remove unrelated network calls and background jobs.
• Run the narrowest test or command that still demonstrates the failure.
• Do not change production data just to make reproduction easier.

5. Prove repeatability

Run the minimal case at least twice where safe. If the result is intermittent, report the observed frequency and test duration instead of calling it deterministic. A failure seen twice in ten attempts is different evidence from a failure seen ten times in ten attempts.

Use a structured handoff

# Bug Reproduction Brief
- Target and commit:
- Environment:
- Expected:
- Actual:
- Minimal steps:
- Minimal fixture:
- Reproduced: yes / no / intermittent
- Evidence:
- Unknowns:
- Safe next hypothesis to test:

This gives a coding agent a bounded target. The next workflow can rank hypotheses, inspect the responsible code and create a regression test without pretending the cause is already known.

Install the complete free workflow

npx skills add skyestrela/ai-agent-skill-preview \
  --skill bug-reproduction-brief --agent codex --global --yes --copy

Read the full Markdown workflow or inspect the public repository before installing.