What this covers
You ran a 30-page audit on your codebase, you have findings worth fixing, and you want a coding agent to do the work. Dumping the whole report into the chat looks tempting but produces vague edits, missed action items, and an agent that “did some refactoring.” This guide is the chunk-summarize-prioritize pattern that turns a long report into a brief the agent can execute against — plus the verification loop that confirms the right items shipped.
Who this is for
Developers using coding agents (Claude Code, Codex, Cursor Agent, Aider) on real projects: post-audit cleanup, dependency upgrade reports, accessibility audits, performance reviews, security findings. Especially useful when the report came from a different tool (Lighthouse, an LLM audit, a human consultant) than the agent that will fix things.
When to reach for it
When you are about to dump a long analysis into a coding agent: a multi-page audit, a security report, a refactor proposal, a tech debt inventory, an architecture review. Skip if the report is already under one page and tightly scoped.
When this is NOT the right tool
Single-issue tickets and tiny reports — the agent handles those directly. Also skip if the report is mostly narrative without action items; rewrite it as a checklist first or it will not survive contact with any agent.
Before you start
- Read the report yourself first. Agents will not catch what you cannot summarize.
- Have a target output in mind: PRs, a single PR with multiple commits, a triage list, or follow-up tickets.
- Know which findings are non-negotiable (security, breakage) and which are nice-to-have (style, optimization).
- Confirm the agent has access to the relevant code — running an agent on findings about files it cannot see is a waste.
Step by step
- Summarize the full report into a 1-page brief — not a rewrite, a brief. Include the title of the audit, the scope (what was reviewed), the top 3 findings, and a count of total findings by severity.
- Identify 3-5 action items the agent can actually do. Drop the rest into a follow-up file. Five concrete actions beats fifteen vague ones.
- For each action item, write a mini-spec:
Action 1: Replace deprecated request.json() with await request.json()
- Files: src/api/*.ts
- Source finding: report section 3.2
- Acceptance: existing tests pass, no console warnings- Feed the brief plus action items to the agent. Reference the full report only when needed for a specific action. Most action items can be executed from the mini-spec alone.
- Have the agent open one PR per action item (or one PR with multiple commits, one commit per item). Atomic PRs are easier to review and revert.
- Verify each PR against the corresponding finding in the original report. Close the loop — did the action actually address the finding, or did the agent fix a near-miss?
Worked example
Audit report: “Performance review of the checkout flow,” 42 pages, 18 findings.
Brief: “Performance audit, May 2026. Scope: /checkout/*. Top 3: (1) unnecessary re-renders in CheckoutForm, (2) N+1 query in cart.ts, (3) missing image lazy-loading on OrderSummary.”
Action items: just the top 3, each with a mini-spec naming files, acceptance criteria, and report section number.
Result: three small PRs. The remaining 15 findings stay in a follow-up file for the next sprint.
First-run exercise
- Take a report you already have lying around. Summarize it into a 1-page brief.
- Pick the three most concrete, agent-friendly action items.
- Run one through your agent of choice. Review the PR.
- Note where the spec was thin — usually missing acceptance criteria or unclear file scope — and fix the template before the next item.
Quality check
- Did each PR address the specific finding referenced, not a near-miss? Read the original report, then the PR.
- Are tests passing? Performance and security audits often surface findings that have no test; ask the agent to propose one.
- Did the agent introduce regressions? Run the full test suite, not just the touched files.
- Did follow-up items actually go into the backlog, or did you mean to and forget? Write them down before merging.
How to reuse this workflow
- Save the brief template as a snippet — title, scope, top 3, severity counts.
- Save the action-item mini-spec format. Same shape every time keeps agent behavior consistent.
- Build a “report intake” checklist: read, summarize, extract actions, file follow-ups, run agent, verify, file remaining items.
- After each audit, log how many findings made it to PRs vs slipped to follow-up. If less than 70% ship, the briefs are too aggressive.
Recommended workflow
Full report → 1-page brief → 3-5 action items with mini-specs → agent execution → atomic PRs → verify against original report → file remaining findings as follow-ups.
Common mistakes
- Dumping the entire 30-page report into one prompt. The agent reads, gets overwhelmed, and produces “general improvements.”
- No action items, just findings. Findings are observations; action items are commands.
- Skipping severity ranking. The agent will pick whichever item is easiest, which is rarely the one that matters.
- Letting the agent pick which findings to fix. You triage, the agent executes.
- One mega-PR for the whole audit. Atomic PRs review faster and revert cleanly.
- Forgetting the follow-up file. Findings you do not ship today must go somewhere or they evaporate.
FAQ
- What if the report is in a non-text format (PDF, slides)?: Convert to text first. Most agents accept PDFs, but the chunking step is much easier on plain text.
- Should the agent that did the audit also do the fixes?: Sometimes — Claude Code can audit and fix in one session. For unbiased review, separate the auditor and the fixer.
- What if the report is wrong?: Verify findings before action. The brief step is also a sanity check on the audit itself.
- How big should the brief be?: One page maximum. If you cannot fit it on one page, the audit is too broad to act on.
Related
Tags: #AI coding #Tutorial