debug-test-capture

Debug to Test Capture

Every completed debug session contains exactly the information needed to write a good test: a reproduction case, a root cause, and a verified fix. This skill turns that into a permanent regression guard before the debug context evaporates. A bug that was worth debugging will recur without a test, because nothing else remembers why the code looks the way it does.

When This Runs

After a debug session completes, specifically when:

• A post-fix regression trace returns a clean verdict
• Your debug workflow's final verification gate passes
• A debug workflow marks an issue resolved
• Any bug fix is committed

If you just finished debugging and haven't run this, the debug session is not complete.

Step 1: Extract the test signal from the debug session

Read back through the debug work and pull out:

1. The trigger: what user action or system state caused the bug? This becomes the arrange phase.
2. The root cause: what was actually wrong? This tells you what the test should assert against.
3. The divergence point: where did actual behavior differ from expected? This becomes the assertion.
4. The fix: what changed? This tells you what condition the test should verify holds.
5. The blast radius: from the regression trace, which adjacent paths were checked? Any without existing tests are candidates.

Step 2: Decide test type and location

Put the test next to the existing tests for that module, and follow the project's naming and layout conventions. If a test file for the module already exists, add to it. If not, create one that matches the neighbors. Look at two or three nearby test files first so the new one reads like it belongs.

Test framework

Use the project's current framework. The shape below is Swift Testing; XCTest and other frameworks map the same way (suite maps to test class or describe block, @Test to a test method, #expect to an assertion).

import Testing
@testable import MyApp

@Suite("Description of what's being tested")
struct FeatureTests {
    @Test("Bug description - regression test for [root cause]")
    func specificBehavior() async throws {
        // arrange: reproduce the conditions that triggered the bug
        // act: perform the operation that was broken
        // assert: verify the fix holds
    }
}