What do I hand my developer when the fix is not words?
A brief with four parts: what is wrong and how it was measured, what to change in the files by name, how to check it worked with the number to beat, and what must not break. Written to go into a ticket, or into whatever built the site, without a follow-up question.
- What is wrong, with the measurement
- What to change, in the named filelayouts/product.tsx
- How to check it worked4 → 0
- What must not break
Three things you get
- Free on any finding
- Names the actual files
- Says how to check it worked
What comes back
The shape of it, drawn at a size the figures can be read. Placeholders, not a customer's numbers.
Three templates render the same title, so four pages compete for one query.
layouts/product.tsx line 41 — take the title from the item, not the category.
Re-run the check: duplicate titles should read 0, down from 4.
The category pages keep their own titles. Do not touch the sitemap.
Why not just send the finding?
Because a finding is a symptom and a developer needs a task. "176 KB of JavaScript is downloaded and never used" is true, and the first three questions back are which files, what am I meant to do about it, and how will we know it is fixed.
The detail+–
The brief answers those before they are asked. It names the 2 files, says what to split and where, and gives the figure to measure afterwards — so the conversation is about the work rather than about the report.
What if I do not have a developer?
Then it goes into the tool that built the site. The brief is written as imperative steps against named files, which is the form a coding assistant acts on rather than replies to — hand it advice and you get more advice back, hand it a work order and you get a change.
The detail+–
Where the right fix depends on how the site is built, it gives the 2 or 3 cases by name and the step for each, rather than asking you which one you are.
How do you know the brief is any good?
Because it is checked before you see it, and rejected if it is vague. A brief that names no file, carries no figure anybody could verify, or reaches for phrases like "review the codebase" and "follow best practices" is sent back to be written again.
The detail+–
If it still cannot be made specific, you are told that rather than handed it as though it were finished. A brief nobody can act on, presented as actionable, is worse than admitting the check did not establish enough.
Also asked
- Does this cost anything? +
- No. It assembles what was already measured into a shape you can use, and charging for the one step that turns a finding into action would teach people to stop at the finding.
- Will you tell me you cannot access my code? +
- Never. You already know that, and it is not an answer. What you do not have is the thing to hand the person who can change it, and writing that is the job.
- What kinds of findings become a brief? +
- Anything outside the words on the page: a bundle, a redirect, a template, a caching rule, a CMS setting, a blocked crawler.
Last updated 3 September 2026
Become the brand AI recommends.
Start with the free check. Your web address and nothing else.