fix-bug

name	fix-bug
description	Fix an OpenROAD bug from a GitHub issue. Analyzes the issue, traces the root cause through the codebase, implements the fix, creates regression tests (registered in both CMake and Bazel), runs clang-format, and prepares a signed-off commit. Use when given a bug report issue number, error code (e.g. GPL-0305, DRT-0001, RSZ-2007), or when asked to fix a bug in any OpenROAD module (ant, cts, dpl, drt, gpl, grt, mpl, odb, pad, pdn, psm, rcx, rsz, sta, stt, tap, upf, utl, etc.). Also triggers on: "fix issue", "debug this error", "resolve crash", "fix segfault", "repair", "patch bug".
argument-hint	<issue-number-or-error-code>

Fix OpenROAD Bug

You are fixing a bug related to $ARGUMENTS.

1. Understand the bug

If $ARGUMENTS is a GitHub issue number:

gh issue view $ARGUMENTS --repo The-OpenROAD-Project/OpenROAD \
  --json title,body,labels,comments

Extract from the issue:

• Error string (e.g. GPL-0305, DRT-0001) -- search for the exact message ID
• Module -- infer from labels or error prefix
• Steps to reproduce -- look for attached scripts, Tcl commands, or tarballs
• Stack trace -- if a crash, identify the faulting function

If $ARGUMENTS is an error code, search for it directly:

grep -rn "ERROR_CODE" src/MODULE/src/

2. Trace the root cause

Follow OpenROAD's "trace bugs upstream" principle: find where the bad data is created, not where it is reported.

1. Find the error message source:

   grep -rn "ERROR_ID" src/
   

2. Read the surrounding code to understand the condition that triggers it
3. Trace the data flow backward -- who sets the offending value?
4. Identify the actual bug location (often in a different function/file from where the error is reported)

Critical constraint: Never modify files under src/sta/. OpenSTA is managed upstream. If the root cause is in OpenSTA, report this finding instead of patching it.

3. Implement the fix

Follow the coding practices in docs/agents/coding.md. Pay special attention to int64_t for area calculations and removing unreachable code after error() or throw.

4. Create regression test

Every bug fix needs a test that reproduces the exact failure mode from the issue (same error code, same stack frame, same condition) so a future regression is caught immediately.

Use the add-test skill (.agents/skills/add-test/SKILL.md) for the full workflow: writing the test, generating golden files, and registering in both CMake and Bazel.

5. Format and commit

# Format changed C++ files (NEVER format src/sta/* or *.i files)
clang-format -i <changed-cpp-files>

# Stage and commit with DCO sign-off
git add <changed-files>
git commit -s -m "MODULE: fix BRIEF_DESCRIPTION

Fixes #ISSUE_NUMBER"

6. Verify

• Test passes: cd src/MODULE/test && ./regression -R TEST_NAME
• No unintended changes: git diff HEAD
• Test registered in both CMake and Bazel
• No src/sta/ files modified
• C++ files formatted with clang-format
• Commit is signed off (-s)