Analyze and Fix a GitHub Issue
Given a GitHub issue number, investigate the problem, find the relevant code, and either propose or implement a fix.
Arguments
$ARGUMENTS — the GitHub issue number (e.g., 509). If not provided, ask the user.
Phase 1: Understand the Issue
Read the issue and extract key information:
gh issue view $ARGUMENTS --repo stillwater-sc/universal --json title,body,labels,state,comments
From the issue, identify:
- What's broken or missing — the core problem statement
- Which number type(s) are affected (posit, cfloat, lns, fixpnt, dd, qd, ereal, etc.)
- Which subsystem — api, conversion, arithmetic, math, operator<<, exceptions, etc.
- Severity — crash, wrong results, missing feature, documentation, performance
- Labels — enhancement, bug, help wanted, Epic, etc.
- Any code snippets or reproduction steps in the issue body or comments
Phase 2: Locate Related Code
Based on the issue analysis, search the codebase:
Find the relevant type's implementation:
include/sw/universal/number/TYPE/TYPE_impl.hpp
Search for keywords from the issue:
- Function names, error messages, type names mentioned in the issue
- Use Grep and Glob to find related files
Check existing tests for the affected area:
static/{category}/TYPE/api/
static/{category}/TYPE/arithmetic/
static/{category}/TYPE/conversion/
static/{category}/TYPE/math/
Examples: static/fixpnt/binary/api/, static/tapered/posit/api/, static/block/microfloat/api/
Check if there's a related PR or branch:
gh pr list --repo stillwater-sc/universal --state all --search "related keywords"
Phase 3: Assess Complexity
Classify the fix:
| Complexity |
Criteria |
Action |
| Trivial |
Typo, missing include, simple one-line fix |
Implement directly |
| Moderate |
New function, algorithm fix, test addition (1-3 files) |
Implement with user confirmation |
| Significant |
Cross-type change, new subsystem, architectural (4+ files) |
Present plan, ask user before implementing |
| Epic |
Major feature, multi-PR effort |
Present roadmap, suggest breakdown into sub-issues |
Phase 4: Implement the Fix
For Trivial/Moderate fixes:
Create a feature branch:
git checkout -b fix/issue-NNN-short-description
Make the code changes — follow existing patterns in the codebase
Build and test with BOTH compilers:
- Build with gcc:
cmake --build --preset gcc-debug --target TARGET
- Run gcc test
- Build with clang:
cmake --build --preset clang-debug --target TARGET
- Run clang test
- NEVER skip the clang build — CI uses clang and it catches different issues
Run related regression tests to check for regressions
Commit with a descriptive message referencing the issue:
fix(TYPE): description of what was fixed
Resolves #NNN
Push and create a draft PR:
git push -u origin fix/issue-NNN-short-description
gh pr create --draft --title "fix(TYPE): short description" --body "..."
Always create PRs as draft — this skips the expensive CI jobs (sanitizers, coverage,
full 11-platform matrix) and only runs the fast tier (gcc + clang CI_LITE, ~8 min).
When the user is satisfied, they promote with gh pr ready NNN.
For Significant/Epic issues:
Present a structured analysis:
## Issue #NNN: Title
### Root Cause
[explanation]
### Affected Files
- file1.hpp:line — what needs to change
- file2.cpp:line — what needs to change
### Proposed Approach
[step-by-step plan]
### Estimated Scope
[number of files, complexity assessment]
### Risks
[what could go wrong, what to watch for]
Ask the user how to proceed
Critical Rules
Build Safety
- ONE build at a time, max
-j4
- Check
pgrep -a 'make|cmake|ninja' before building
- Test with BOTH gcc AND clang
Code Quality
- Follow existing patterns — read similar implementations before writing
- Number types must be trivially constructible (no in-class initializers)
- Exception hierarchy: number types inherit
universal_*, internal blocks inherit std::runtime_error
- Don't use
constexpr on constructors that call math functions
Portability Pitfalls
- Don't use
long double bit-shift division — use std::ldexp()
- Always initialize
blockbinary temporaries (clang doesn't zero stack)
- MSVC has no
operator long double() on blocksignificand
- MinGW has IPA ICF bugs with multiple template instantiations
Issue Communication
- If the user explicitly asks to notify the issue thread when starting work:
gh issue comment NNN --repo stillwater-sc/universal --body "Working on this. Plan: [brief description of approach]"
- If the user explicitly asks to notify the issue after opening a PR, post a follow-up summary:
gh issue comment NNN --repo stillwater-sc/universal --body "Implemented [summary] in PR #PPP."
- Do not comment on issues automatically; always ask for confirmation first.
- Reference the issue number in commits:
Resolves #NNN or Fixes #NNN
- If the fix is partial, use
Relates to #NNN instead
- Don't close Epic issues with a single PR — they track multi-step efforts
Common Issue Patterns
| Issue Pattern |
Where to Look |
Typical Fix |
| Wrong arithmetic results |
TYPE_impl.hpp operators, blockbinary |
Algorithm fix, edge case handling |
| Missing math function |
math/TYPE_math.hpp or mathlib.hpp |
Implement using existing patterns |
| Precision loss in output |
operator<<, to_string() |
Use support::decimal for exact conversion |
| Conversion failure |
TYPE_impl.hpp assignment operators |
Fix the conversion path |
| Build failure on platform X |
Compiler-specific code paths |
Portability fix with #ifdef or alternative |
| Missing istream support |
operator>> in TYPE_impl.hpp |
Implement parsing |
| Performance issue |
Hot path in arithmetic operators |
Profile, optimize inner loop |
| CI test failure |
Test expectations vs actual behavior |
Fix test or fix implementation |
1---2name: fix-issue-23description: Analyze a GitHub issue, explore related code, and propose or implement a fix. Use when the user asks to investigate, fix, or resolve a GitHub issue.4---56# Analyze and Fix a GitHub Issue78Given a GitHub issue number, investigate the problem, find the relevant code, and either propose or implement a fix.910## Arguments1112`$ARGUMENTS` — the GitHub issue number (e.g., `509`). If not provided, ask the user.1314## Phase 1: Understand the Issue1516Read the issue and extract key information:1718```bash19gh issue view $ARGUMENTS --repo stillwater-sc/universal --json title,body,labels,state,comments20```2122From the issue, identify:23- **What's broken or missing** — the core problem statement24- **Which number type(s)** are affected (posit, cfloat, lns, fixpnt, dd, qd, ereal, etc.)25- **Which subsystem** — api, conversion, arithmetic, math, operator<<, exceptions, etc.26- **Severity** — crash, wrong results, missing feature, documentation, performance27- **Labels** — enhancement, bug, help wanted, Epic, etc.28- **Any code snippets or reproduction steps** in the issue body or comments2930## Phase 2: Locate Related Code3132Based on the issue analysis, search the codebase:33341. **Find the relevant type's implementation:**35 ```text36 include/sw/universal/number/TYPE/TYPE_impl.hpp37 ```38392. **Search for keywords from the issue:**40 - Function names, error messages, type names mentioned in the issue41 - Use Grep and Glob to find related files42433. **Check existing tests** for the affected area:44 ```text45 static/{category}/TYPE/api/46 static/{category}/TYPE/arithmetic/47 static/{category}/TYPE/conversion/48 static/{category}/TYPE/math/49 ```50 Examples: `static/fixpnt/binary/api/`, `static/tapered/posit/api/`, `static/block/microfloat/api/`51524. **Check if there's a related PR or branch:**53 ```bash54 gh pr list --repo stillwater-sc/universal --state all --search "related keywords"55 ```5657## Phase 3: Assess Complexity5859Classify the fix:6061| Complexity | Criteria | Action |62|-----------|----------|--------|63| **Trivial** | Typo, missing include, simple one-line fix | Implement directly |64| **Moderate** | New function, algorithm fix, test addition (1-3 files) | Implement with user confirmation |65| **Significant** | Cross-type change, new subsystem, architectural (4+ files) | Present plan, ask user before implementing |66| **Epic** | Major feature, multi-PR effort | Present roadmap, suggest breakdown into sub-issues |6768## Phase 4: Implement the Fix6970### For Trivial/Moderate fixes:71721. **Create a feature branch:**73 ```bash74 git checkout -b fix/issue-NNN-short-description75 ```76772. **Make the code changes** — follow existing patterns in the codebase78793. **Build and test with BOTH compilers:**80 - Build with gcc: `cmake --build --preset gcc-debug --target TARGET`81 - Run gcc test82 - Build with clang: `cmake --build --preset clang-debug --target TARGET`83 - Run clang test84 - NEVER skip the clang build — CI uses clang and it catches different issues85864. **Run related regression tests** to check for regressions87885. **Commit with a descriptive message** referencing the issue:89 ```text90 fix(TYPE): description of what was fixed9192 Resolves #NNN93 ```94956. **Push and create a draft PR:**96 ```bash97 git push -u origin fix/issue-NNN-short-description98 gh pr create --draft --title "fix(TYPE): short description" --body "..."99 ```100 Always create PRs as **draft** — this skips the expensive CI jobs (sanitizers, coverage,101 full 11-platform matrix) and only runs the fast tier (gcc + clang CI_LITE, ~8 min).102 When the user is satisfied, they promote with `gh pr ready NNN`.103104### For Significant/Epic issues:1051061. Present a structured analysis:107 ```markdown108 ## Issue #NNN: Title109110 ### Root Cause111 [explanation]112113 ### Affected Files114 - file1.hpp:line — what needs to change115 - file2.cpp:line — what needs to change116117 ### Proposed Approach118 [step-by-step plan]119120 ### Estimated Scope121 [number of files, complexity assessment]122123 ### Risks124 [what could go wrong, what to watch for]125 ```1261272. Ask the user how to proceed128129## Critical Rules130131### Build Safety132- ONE build at a time, max `-j4`133- Check `pgrep -a 'make|cmake|ninja'` before building134- Test with BOTH gcc AND clang135136### Code Quality137- Follow existing patterns — read similar implementations before writing138- Number types must be trivially constructible (no in-class initializers)139- Exception hierarchy: number types inherit `universal_*`, internal blocks inherit `std::runtime_error`140- Don't use `constexpr` on constructors that call math functions141142### Portability Pitfalls143- Don't use `long double` bit-shift division — use `std::ldexp()`144- Always initialize `blockbinary` temporaries (clang doesn't zero stack)145- MSVC has no `operator long double()` on `blocksignificand`146- MinGW has IPA ICF bugs with multiple template instantiations147148### Issue Communication149- **If the user explicitly asks** to notify the issue thread when starting work:150 ```bash151 gh issue comment NNN --repo stillwater-sc/universal --body "Working on this. Plan: [brief description of approach]"152 ```153- **If the user explicitly asks** to notify the issue after opening a PR, post a follow-up summary:154 ```bash155 gh issue comment NNN --repo stillwater-sc/universal --body "Implemented [summary] in PR #PPP."156 ```157- Do not comment on issues automatically; always ask for confirmation first.158- Reference the issue number in commits: `Resolves #NNN` or `Fixes #NNN`159- If the fix is partial, use `Relates to #NNN` instead160- Don't close Epic issues with a single PR — they track multi-step efforts161162## Common Issue Patterns163164| Issue Pattern | Where to Look | Typical Fix |165|--------------|---------------|-------------|166| Wrong arithmetic results | `TYPE_impl.hpp` operators, `blockbinary` | Algorithm fix, edge case handling |167| Missing math function | `math/TYPE_math.hpp` or `mathlib.hpp` | Implement using existing patterns |168| Precision loss in output | `operator<<`, `to_string()` | Use `support::decimal` for exact conversion |169| Conversion failure | `TYPE_impl.hpp` assignment operators | Fix the conversion path |170| Build failure on platform X | Compiler-specific code paths | Portability fix with `#ifdef` or alternative |171| Missing istream support | `operator>>` in `TYPE_impl.hpp` | Implement parsing |172| Performance issue | Hot path in arithmetic operators | Profile, optimize inner loop |173| CI test failure | Test expectations vs actual behavior | Fix test or fix implementation |