---
name: resolve-findings
description: >-
  Triage a review findings report: verify each finding, implement accepted
  fixes, and record rejected, deferred, or already-resolved items. Use for
  report-driven follow-up work.
---

# resolve-findings

Treat review reports as inputs, not truth.
Your job is to:
1. verify each finding
2. decide whether it is correct
3. fix accepted findings within scope
4. document why any finding was not fixed

## Defaults

- Default input discovery is deterministic. If the user does not provide a report path:
  1. list `.agent-layer/tmp/*.report.md`
  2. keep only files matching `<workflow>.<run-id>.report.md`
  3. keep only reports from workflows that normally produce actionable findings:
     - `verify-against-plan`
     - `review-plan`
     - `review-scope`
  4. group by workflow and sort each group by `run-id` descending
  5. choose the newest report from the highest-precedence workflow in this order:
     - `verify-against-plan`
     - `review-plan`
     - `review-scope`
- If no valid report artifact exists, ask the user for a report path or rerun the review workflow.
- If the user asked only for triage or report review, stop after triage and ask before editing code.

## Required artifacts

Use one shared `run-id = YYYYMMDD-HHMMSS-<short-rand>`.

Always create:
- `.agent-layer/tmp/resolve-findings.<run-id>.report.md`

Create these only when at least one finding is accepted and fixes are in scope for the request:
- `.agent-layer/tmp/resolve-findings.<run-id>.plan.md`
- `.agent-layer/tmp/resolve-findings.<run-id>.task.md`
- `.agent-layer/tmp/resolve-findings.<run-id>.context.md`

The final report is the resolution log.
Create each file with `touch` before writing.

## Multi-agent pattern

Recommended roles:
1. `Verifier`: checks whether each reported finding is actually valid.
2. `Execution gatekeeper`: decides whether the accepted finding set should `proceed`, `revise`, `escalate`, or `rewrite-because-out-of-scope`.
3. `Fixer`: implements accepted findings.
4. `Auditor`: reviews the resulting changes for regressions or overreach.

## Global constraints

- Treat the report as input, not authority.
- Preserve an explicit verdict for every finding. Do not silently drop any.
- Apply accepted fixes to the actual reviewed target, which may be plan artifacts, code, docs, or tests.
- Do not expand the scope beyond accepted findings without asking.

## Human checkpoints

- Required: ask before editing only when the user explicitly limited the run to triage or report review.
- Required: ask when no valid review report can be found and explicit report selection is needed.
- Required: ask when an accepted fix would require materially broader scope or a real behavior change beyond the reviewed target.
- When a checkpoint involves a genuine tradeoff between substantive alternatives, present at least two options with brief pros and cons, state which you recommend and why, and let the human decide.
- Stay autonomous during verdicting and in-scope fixes when the request includes fixes.

## Triage workflow

### Phase 1: Parse and verify findings (Verifier)

For each finding, assign exactly one verdict:
- `accept`
- `reject`
- `defer`
- `already-resolved`

Verification rules:
- Reproduce or inspect the claim directly in code, plan artifacts, or diffs.
- Do not assume the report is correct because it sounds plausible.
- If the finding depends on a missing fact, mark it `defer` and explain what is missing.
- If the finding is technically true but out of scope for this run, mark it `defer`.

### Phase 2: Write the plan and task list (Planner)

For accepted findings only, create a focused plan with:
- objective
- accepted findings in scope
- rejected or deferred findings out of scope
- implementation approach
- verification commands
- risk notes

Create a compact task list that matches the accepted findings.

If zero findings are accepted:
- do not create plan, task, or context artifacts
- record `No accepted findings` in the resolution report
- stop without editing code

### Phase 3: Gate the accepted fix set (Execution gatekeeper)

Choose exactly one verdict for the accepted finding set:
- `proceed`: the fix set is ready to implement as written
- `revise`: the plan or task list needs updates first
- `escalate`: a human checkpoint is actually required
- `rewrite-because-out-of-scope`: the accepted set should be rewritten to the largest still-in-scope subset before coding

If the verdict is `revise`, update the plan or task list and repeat Phase 2.
If the verdict is `escalate`, ask the smallest question that unblocks a trustworthy fix set.
If the verdict is `rewrite-because-out-of-scope`, rewrite the accepted set to the largest still-in-scope subset, defer the rest explicitly, and repeat Phase 2.

### Phase 4: Implement accepted findings (Fixer)

Execution rules:
- keep scope tight to accepted findings
- prefer root-cause fixes over surface patches
- if a fix requires a materially larger refactor than the finding suggests, hand it back to the execution gatekeeper
- if two accepted findings are duplicates, fix once and note both as resolved by the same change

### Phase 5: Audit the fix set (Auditor)

After implementation:
- re-read each accepted finding
- confirm the change actually resolves it
- review touched code for regressions
- if you discover a new issue caused by the fix, either fix it immediately or record it in the resolution report

## Resolution report format

Write `.agent-layer/tmp/resolve-findings.<run-id>.report.md` with:

1. `# Resolution Summary`
2. `## Accepted and Fixed`
3. `## Rejected`
4. `## Deferred`
5. `## Already Resolved`
6. `## Verification`
7. `## Residual Risk`

For every non-fixed finding, explain why in concrete terms.

## Guardrails

- Do not silently ignore findings.
- Do not "fix" a finding you do not agree with just to clear the report.
- Do not rewrite the report author's conclusion without preserving the actual verdict.
- Do not let a Medium or Low finding pull in unrelated opportunistic work.
- If a Critical or High finding remains unresolved, say so prominently in the final report.

## Definition of done

- The resolution report exists at `.agent-layer/tmp/resolve-findings.<run-id>.report.md` with every required section (`Summary`, `Accepted and Fixed`, `Rejected`, `Deferred`, `Already Resolved`, `Verification`, `Residual Risk`).
- Every finding from the input review report has exactly one explicit verdict of accept, reject, defer, or already-resolved — none silently dropped.
- When at least one finding is accepted, the plan/task/context artifacts also exist at the documented paths; when zero are accepted, they are absent and the report says `No accepted findings`.
- Every non-fixed finding carries a concrete explanation, and any unresolved Critical or High finding is surfaced prominently in the report and handoff.

## Final handoff

After the run:
1. Echo the report path, plus the plan/task/context paths only if they were created.
2. Summarize what was fixed.
3. Call out any unresolved High/Critical findings.
