| name | workflow-debugging |
| description | Workflow for issue-based debugging in V8. Use when tasked with debugging a specific issue, usually associated with a Buganizer ID or a specific reproduction script. Do not use for performance regressions. |
Workflow: Issue Debugging
Use this skill when tasked with debugging a specific issue, usually associated
with a Buganizer ID or a specific reproduction script. This specializes the
general debugging approach for tracked issues.
Activation Criteria
- User provides an issue ID or Buganizer URL.
- User provides a reproduction script that crashes or behaves unexpectedly.
- The goal is to find a root cause and propose a fix for a specific bug.
Core Principles (Inherited & Specialized)
- Strict Orchestration: The main agent acts purely as a dispatcher.
Delegate technical tasks.
- Eager Parallelism: Initialize Heavy Infrastructure, Conceptual Triage,
and Static Research in parallel.
- Issue Association: When an issue ID is known, use it to label tests and
commits.
- Handling Inaccessible URLs & Missing Info:
- If a URL cannot be accessed directly (e.g., due to authentication), or if
the intake phase detects that critical attachments (repro script, flags,
etc.) cannot be accessed or are redacted, the Orchestrator MUST stop
immediately and ask the user to provide them manually.
- Avoid opening a browser to access the page if it is inaccessible through
tools.
- Use separate, sequential interactive prompts (e.g., via
ask_question or
direct message to user) to gather missing information:
- Input 1: The JavaScript test source code.
- Input 2: The relevant
d8 flags or command-line arguments.
- Rely on user-provided reproduction script or flags.
- If the user denies or does not provide the information, seek explicit
guidance on how to proceed.
- Store the test source in the workspace (e.g.,
scratch/regress-<issue_id>.js) to avoid modifying the user's environment
directly.
- Worktree Isolation: If you debug with a repository in use (e.g., with
unrelated changes) or debug multiple issues at once you MUST create and
switch to an isolated git worktree using
agents/scripts/create_worktree.sh <issue_id> BEFORE running any builds or
tests, to avoid clobbering the main workspace or rebuilding unnecessarily.
- Cross-Pollination & Communication: The Orchestrator MUST actively relay
relevant discoveries and hypotheses between subagents working on overlapping
or related tasks to avoid duplicate work and find matching patterns.
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 using
agents/scripts/create_worktree.sh <issue_id> to isolate the investigation.
- Eager Delegation (MANDATORY): The Orchestrator MUST proactively spawn
subagents to handle all of the following tracks in PARALLEL:
- Track A: Heavy Infrastructure: Spawn a subagent to build
d8 and
prepare GDB/rr in the worktree.
- Track B: Conceptual Triage: Spawn a subagent to analyze the reproducing
JS source.
- Track C: Static Research: Spawn a subagent to search for related code
and spec text, and understand affected areas super deeply.
2. Work Branching
- Spawn subagents for independent dimensions (e.g., Spec vs. Runtime).
3. Investigation & Escalation
- Reproduction Verification (MANDATORY): Before launching GDB or doing any
deep debugging, you MUST first execute the reproduction script normally
(without GDB) using your compiled
d8 binary to verify that the crash indeed
reproduces locally. This establishes the baseline.
- 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.
- Create a Regression Test: Design and implement a clean, semantic
regression test. This test must be developed and verified to crash/fail on the
unfixed codebase and pass cleanly on the fixed codebase.
- 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 working regression test file and where it will
be placed. A bug fix must always be accompanied by a working regression
test. Proposing a fix without a reproducer is strictly forbidden unless the
user has explicitly waived it.
- 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:
