Issue resolution
Turn open GitHub issues into landed fixes, one issue at a time. Read the issue,
locate the code it names with Prowl, confirm the bug is real and still present,
fix it at the source, prove the fix, then close the issue with a short human
note. Prowl is the investigation engine; gh is only the issue API.
Never fabricate a fix or close an issue you did not resolve. If an issue is
already fixed on the current line, verify that and close it explaining so; if it
is invalid or needs the reporter, say that instead of forcing a change.
1. Read the tracker
gh issue list --state open lists what is open; gh issue view <N> reads one,
including the reporter's steps and any attached logs or screenshots.- Take the reporter's described symptoms as ground truth. Do not re-derive what
they already observed; use it to aim the investigation.
2. Investigate with Prowl, not a grep sweep
Route every "where is this / what depends on it" question through the index:
| Question |
First command |
| Locate the feature or subsystem named |
prowl-agent search "<question>" |
| Locate a named symbol |
prowl-agent find <name> |
| Read the offending code |
prowl-agent def <name-or-id> |
| See a file's shape |
prowl-agent outline <path> |
| Find every caller before you change a contract |
prowl-agent references <name-or-id> |
| Size the blast radius of the fix |
prowl-agent impact <path> |
Reserve grep for an exact literal (an error string, a config key) and glob for
filename patterns. When an issue quotes an error message, grep for that exact
string to find where it is emitted, then switch back to find/def to read it.
An error string that no longer exists in the tree usually means the issue was
fixed since the reporter's build. Confirm the current code path with
prowl-agent def/references before deciding the bug is gone.
3. Fix at the source
- Change the cause, not the symptom. Migrate every caller a contract change
touches --
prowl-agent references before editing an exported symbol so no
callsite is missed.
- Follow the repo's own conventions and its
AGENTS.md/CONTRIBUTING.md. Do not
invent a second pattern beside an existing one.
- Update the tests the changed behaviour breaks, and add one only where a
plausible bug would fail it.
4. Prove it, then commit
- Build and run the specific test or scenario that covers the change; a passing
targeted test is the proof, not the whole suite.
prowl-agent changed maps your edits to what they could affect, so you check
the right things before committing.- Commit through the repo's hooks. Never bypass them (
--no-verify is
forbidden); match the project's commit-message format.
5. Close it like a human
gh issue comment <N> -b "<note>" then gh issue close <N>.- The closing note has four rules: short (one or two sentences), not
technical (no diagnosis, no diff, no file or symbol names), not descriptive
of what the issue was (do not narrate or summarise the bug back at them), and
human, not AI (no "I've resolved…", no bullet lists, no hedging boilerplate
or upbeat filler). Acknowledge the report, say it is handled, done.
- Good: "Sorted this out on our end, thanks for the clear writeup. Closing."
Bad: "I have fixed the reconcile_zen reconciler so it no longer overwrites
policies.json and removed the two extensions."
- For an already-fixed issue, tell the reporter it should be resolved in current
builds and to reopen if it recurs -- same short, plain tone.
Ask before anything destructive or before deleting unrelated code you did not
write. When several issues are independent, resolve them in separate commits so
each fix stays revertible on its own.
1---2name: issue-resolution3description: Use when asked to work through open GitHub issues end to end -- review, investigate, fix, then comment and close -- or phrasings like "clear the open issues", "triage and fix the bugs in gh", or "resolve the tracker". Investigates each issue against the code with the read-only prowl-agent CLI, lands a real fix that builds and passes the repo's checks, and closes the issue with a short, human-toned note. Keep grep for exact literal text and gh for the GitHub API itself.4---56# Issue resolution78Turn open GitHub issues into landed fixes, one issue at a time. Read the issue,9locate the code it names with Prowl, confirm the bug is real and still present,10fix it at the source, prove the fix, then close the issue with a short human11note. Prowl is the investigation engine; `gh` is only the issue API.1213Never fabricate a fix or close an issue you did not resolve. If an issue is14already fixed on the current line, verify that and close it explaining so; if it15is invalid or needs the reporter, say that instead of forcing a change.1617## 1. Read the tracker1819- `gh issue list --state open` lists what is open; `gh issue view <N>` reads one,20 including the reporter's steps and any attached logs or screenshots.21- Take the reporter's described symptoms as ground truth. Do not re-derive what22 they already observed; use it to aim the investigation.2324## 2. Investigate with Prowl, not a grep sweep2526Route every "where is this / what depends on it" question through the index:2728| Question | First command |29|---|---|30| Locate the feature or subsystem named | `prowl-agent search "<question>"` |31| Locate a named symbol | `prowl-agent find <name>` |32| Read the offending code | `prowl-agent def <name-or-id>` |33| See a file's shape | `prowl-agent outline <path>` |34| Find every caller before you change a contract | `prowl-agent references <name-or-id>` |35| Size the blast radius of the fix | `prowl-agent impact <path>` |3637Reserve grep for an exact literal (an error string, a config key) and glob for38filename patterns. When an issue quotes an error message, grep for that exact39string to find where it is emitted, then switch back to `find`/`def` to read it.4041An error string that no longer exists in the tree usually means the issue was42fixed since the reporter's build. Confirm the current code path with43`prowl-agent def`/`references` before deciding the bug is gone.4445## 3. Fix at the source4647- Change the cause, not the symptom. Migrate every caller a contract change48 touches -- `prowl-agent references` before editing an exported symbol so no49 callsite is missed.50- Follow the repo's own conventions and its `AGENTS.md`/`CONTRIBUTING.md`. Do not51 invent a second pattern beside an existing one.52- Update the tests the changed behaviour breaks, and add one only where a53 plausible bug would fail it.5455## 4. Prove it, then commit5657- Build and run the specific test or scenario that covers the change; a passing58 targeted test is the proof, not the whole suite.59- `prowl-agent changed` maps your edits to what they could affect, so you check60 the right things before committing.61- Commit through the repo's hooks. Never bypass them (`--no-verify` is62 forbidden); match the project's commit-message format.6364## 5. Close it like a human6566- `gh issue comment <N> -b "<note>"` then `gh issue close <N>`.67- The closing note has four rules: **short** (one or two sentences), **not68 technical** (no diagnosis, no diff, no file or symbol names), **not descriptive69 of what the issue was** (do not narrate or summarise the bug back at them), and70 **human, not AI** (no "I've resolved…", no bullet lists, no hedging boilerplate71 or upbeat filler). Acknowledge the report, say it is handled, done.72- Good: "Sorted this out on our end, thanks for the clear writeup. Closing."73 Bad: "I have fixed the reconcile_zen reconciler so it no longer overwrites74 policies.json and removed the two extensions."75- For an already-fixed issue, tell the reporter it should be resolved in current76 builds and to reopen if it recurs -- same short, plain tone.7778Ask before anything destructive or before deleting unrelated code you did not79write. When several issues are independent, resolve them in separate commits so80each fix stays revertible on its own.
neur0map