Step 1 · Reproduce the Bug

Goal

Establish a reliable, on-demand reproduction of the bug before touching any code. A bug you cannot reproduce is a bug you cannot fix.

Instructions

You are in workflow step 1 of the bug-cycle. A bug has been reported. Your job is to find the exact conditions that produce it and document them precisely.

Tasks to Perform

1. Collect All Information About the Report

Before reading a single line of code, gather:

  • What exactly was expected to happen?
  • What exactly happened instead? (error message, wrong output, incorrect state)
  • When did this start happening? (was it always broken, or did something change?)
  • Does it happen always or only sometimes?
  • What environment? (production, staging, specific browser, specific user account)
  • What input or data triggers it?

2. Check the Logs

# Find error logs
find . -name "*.log" -type f | xargs ls -lt 2>/dev/null | head -10

# Tail the most recent log
tail -100 [path/to/latest.log]

# Search for the error pattern
grep -n "[error text or exception class]" [log file] | tail -20

# Check if this error appears frequently or rarely
grep -c "[error pattern]" [log file]

3. Check Recent Git History

If the bug is a regression (was working before), find when it broke:

# Find recent changes to likely files
git log --oneline -20

# If you can narrow it to a file:
git log --oneline -10 -- [path/to/suspected/file]

# Use bisect if you know a good version
git bisect start
git bisect bad HEAD
git bisect good [last-known-good-commit-or-tag]
# Then test each bisect checkpoint until the first bad commit is found

4. Reproduce Locally

Try to reproduce the bug in a local environment:

# Set up the same data/state as when the bug occurs
# Run the same operation
# Observe the output

Document the exact reproduction steps:

1. Set up: [initial state or data]
2. Action: [what operation triggers the bug]
3. Expected: [what should happen]
4. Actual: [what actually happens — exact error or incorrect output]

5. Write a Failing Test

Before investigating the root cause, write a test that:

  • Sets up the conditions that trigger the bug
  • Runs the operation
  • Asserts the correct expected behaviour (it should fail right now)
# Run it to confirm it fails with the expected error
[test runner command] [specific test path]

This test becomes the regression test once the bug is fixed.

6. Create a TODO.md Entry

Always include the source reference so the task is traceable. Status rules: [ ] = not started · [~] = in progress (one at a time) · [x] = done (prefix the date).

## Todo
- [ ] fix: [one-line description of the bug] _(ref: workflows/bug-cycle/01-reproduce.md)_
  - Reproduction: [steps to reproduce]
  - Expected: [correct behaviour]
  - Actual: [current wrong behaviour]
  - Regression test: [path to failing test]

Expected Output

  • Documented reproduction steps (in TODO.md)
  • Failing regression test committed
  • Environment/data conditions understood

Exit Criteria

This step is complete when:

  • [ ] Bug is reproducible on demand
  • [ ] Reproduction steps are written down
  • [ ] A failing test exists that captures the bug
  • [ ] Ready to proceed to Step 2 (Diagnose)