Workflow Debugging

Workflow

1. Triage & Parallel Track Initialization

• Analyze the request and extract the Issue ID if available.
• Worktree Setup: If an issue ID is identified, immediately create and switch to a separate git worktree to isolate the investigation.
• Initialize the following tracks in PARALLEL:
  • Track A: Heavy Infrastructure: Build d8 and prepare GDB/rr in the worktree.
  • Track B: Conceptual Triage: Analyze the reproducing JS source.
  • Track C: Static Research: Search for related code and spec text.

2. Work Branching

• Spawn subagents for independent dimensions (e.g., Spec vs. Runtime).

3. Investigation & Escalation

• Use GDB to inspect crash state.
• Escalate unfamiliar concepts immediately.

4. Synthesis

• Combine findings to locate the root cause.

5. Fix & Verify

• Propose a fix following V8 Best Practices.
• Architectural Skepticism (MANDATORY): Before presenting the fix, the agent MUST explicitly argue against its own proposal.
  • Skepticism Prompt: "Is this fix too hasty? Does it accidentally disable a valid optimization path? Am I fixing a symptom (crashing line) rather than the root cause (invariant violation)?"
• Deep Reasoning: If the root cause isn't fully understood, spawn a subagent to reason deeper about why the failing line exists and what invariant it's protecting.
• Verify: Confirm with tests and d8 flags. Run tests on both debug and release builds if possible to ensure no assertions are violated and performance is not regressed.

6. Interactive Review

Before committing or uploading, you MUST present the proposed solution to the user for review.

• Present the Diff: Show the exact code changes proposed.
• Present the Test: Show the regression test file and where it will be placed.
• Explain the Root Cause: Provide a clear explanation of why the bug happened.
• Share Skepticism Results: Briefly mention the counter-arguments considered during the Skepticism phase and why the proposed fix is still the right choice.
• Ask for Approval: Explicitly ask the user if you should proceed with committing and uploading.

7. Commit & Upload (Specialized)

Once the fix is approved by the user:

• Issue Association in Commits:

  • The commit message must follow the V8 convention.
  • It MUST include a Bug: v8:<issue_id> line at the bottom.
  • Example Commit Message:

    [compiler] Fix crash in Turboshaft during loop unrolling
    
    The loop unroller failed to handle cases where...
    
    Bug: v8:12345
    

• Test Naming and Placement:

  • Name the reproduction test file regress-<issue_id>.js.
  • If there is no issue ID, use a descriptive name like regress-short-description.js.
  • Place the test in the appropriate directory:
    • General regressions: test/mjsunit/regress/
    • Component-specific regressions (if applicable): e.g., test/mjsunit/compiler/regress-12345.js.
  • Ensure the test file contains a header referencing the bug:

    // Copyright 2026 the V8 project authors. All rights reserved.
    // Use of this source code is governed by a BSD-style license that can be
    // found in the LICENSE file.
    
    // Flags: --allow-natives-syntax --any-other-flags
    
    // Bug: v8:12345
    

• Finalization and Upload:

  • Run git cl format to ensure style compliance.
  • Create the commit locally.
  • Run git cl upload to upload the change list (CL) to Gerrit.
  • Report the CL URL back to the user/caller if the tool output provides it.