bug-investigation

Bug investigation

When to use

In the bug workflow, from discovery through implementation. For live production behavior, start with runtime-debugging; for the reasoning that finds the cause, this skill hands off to root-cause-analysis.

Required context

The report itself: symptom, where it was seen, raw error output, reproduction steps if any. Useful: the feature map entry and the verification profile.

Preconditions

• The expected behavior is stated by the report, the code's tests or a human. Without it, the report is a requirements question, not a bug; ask.
• The raw failure output is available, or a human was asked for it.

Procedure

1. Understand the symptom. Separate what was observed from what the reporter concluded. Note the environment, input and time.
2. Reproduce in the smallest setting that shows the defect. If you cannot reproduce it, record every attempt and ask for more data before touching code. When the defect appears only in a running environment, use runtime-debugging to observe it there.
3. Isolate. Narrow the input and the code path until the defect's location is small. When the defect is a regression, compare against the last good revision with core.repository.diff, and use core.repository.history to find the changes in between.
4. Find the cause with root-cause-analysis. Do not write a fix before the cause is confirmed.
5. Write the regression test with regression-testing, and see it fail.
6. Fix the cause, not the symptom, in the smallest change the cause allows.
7. Verify: the regression test passes, the surrounding suite passes, and the original reproduction no longer shows the defect.
8. Look sideways. Search for the same cause elsewhere and list each occurrence as fixed, ruled out or left for a human to decide.

Keep a running log while investigating; the synthetic example in examples/investigation-log.md shows the level of detail. For a Paved workflow, keep durable investigation notes under .paved/documents/research/<run-id>.md and the implementation plan under .paved/documents/plans/<run-id>.md; use the same workflow run id for both.

Tools

core.repository.diff to compare with a known-good revision; core.repository.history, when available, to list the changes between that revision and the failing one.

Rules

core.testing.regression-test-for-bug-fix makes step 5 non-negotiable, and core.quality.unknowns-stay-unknown applies to the report: a reporter's explanation is a hypothesis until the code confirms it.

Verification

Required: unit. Recommended: integration or e2e when the defect lives at that level, and runtime when it was observed in a running system.

Evidence

The reproduction, check results for the regression test before and after the fix and for the surrounding suite, and the diff.

Completion criteria

• The regression test failed before the fix and passes after it.
• The original reproduction no longer shows the defect.
• The cause is explained in the evidence, with the observation that confirmed it.

Failure modes

Failure	Signal	Response
Cannot reproduce	Several attempts show no defect	Record the attempts; ask for data; do not guess a fix
Fix before cause	A change is proposed with no confirmed cause	Return to step 4
Intermittent defect	Reproduction fails only sometimes	Treat timing, ordering and shared state as suspects; measure the rate
Symptom masked	The error disappears but the state is still wrong	Keep tracing; assert on the state, not on the error

References

• examples/investigation-log.md: a synthetic investigation log.