Addressing Findings

Walk a findings list one item at a time: explain, propose, stop. The user decides each one; nothing changes until they do.

One finding per message, always. Time pressure and "batch the obvious ones" change how long each message is, not how many findings it holds. Deciding which findings are "obvious" is the user's call.

Before the first finding

1. Source the list.
   • analyze-code report — use its findings in report order (already severity-ranked). Each finding's Action: … → <specialist> names its specialist.
   • PR comments — if not already provided, fetch them: gh api repos/{owner}/{repo}/pulls/N/comments (inline) and gh pr view N --comments (review bodies). Sort each comment:
     • requests a change → finding
     • asks a question → finding; one option is "answer only, no code change"
     • praise, acknowledgement, resolved thread → not a finding
     • Order: severity you assess, then file:line.
   • Anything else — the list the user names; none exists → ask for it.
   • Another list exists that the user didn't name (a report next to PR comments) → mention it in the orientation line; don't merge it.
2. Re-check current state. Code may have changed since the list was made. Drop findings already resolved.
3. One line of orientation: the source, M findings in the order you'll take them, what was dropped and why (resolved, praise). Then Finding 1.

Per finding

Load the specialist the finding names; if it names none, pick one through using-software-specialists. Put Using <specialist> specialist directly above the finding header.

Full form:

Write for a reader who has not opened the file. Use complete sentences. Say what each function, type or term is the first time it appears. Restate the finding in your own plain words. Do not copy the report's tags or wording.

1. ## Finding N of M: <plain-language title> (PR comment: add — <author>, #<comment id>)
2. Context — one or two sentences: what this code does and who calls it.
3. Issue — what is wrong, quoting the line(s) with file:line. What it affects and when it bites. If an earlier claim about it was wrong, correct it here.
4. Fix options — usually two, each with its cost and the tests it adds. Show the recommended option as a short before/after snippet. Include "keep it and document why" when that is a real option. Steps only the user can do (rotate a key, change infra) are named as such.
5. Recommendation — one option, one sentence why.
6. One question, plain text, ending the message: "Apply A?" No option pickers, no second question.

Compact form — when the user signals time pressure ("move fast", "we're late", "batch these"): title, Issue in one line, recommended fix as a snippet with the tests it adds and any user-only step, "Apply?".

Then stop.

On the user's answer

PR replies (never posted)

Never post to the PR — no replies, no resolved threads, no submitted reviews, even when asked to. The user posts; you write the text they can use.

After each decided PR finding, give the suggested reply for that thread: #<comment id> (<author>): <text>. Repeat them all in the closing.

Rules

• Every change traces to an approved option — no "while I'm here" edits.
• Docs, plan, and wiki edits are changes too: approve first.
• Never stage or commit.
• A finding made moot by an earlier fix: one line saying so, then move on.

Closing

After the last finding: a table # | Finding | Outcome (fixed / documented / answered / skipped / resolved by user / needs user action), the current verification status, what is left uncommitted, and — for PR comments — the suggested reply text per thread, for the user to post.