Most teams already have a Google ranking report. It is the Search Console Performance tab, sorted by clicks, screenshotted into a slide. It shows positions. It does not show what changed, why it changed, or what anyone should do about it.
This workflow fixes that in one sitting. You define a query set, give Codex a written report contract, and let it produce the same shaped report every week. The first build takes about 90 minutes. Every run after that takes under ten.
The whole workflow: raw exports in, one fixed report shape out, one human decision at the end.
What you will finish with
Who this is for: anyone who owns reporting for a site and already has Search Console access. You do not need to be a developer, but you do need a place to keep files that Codex can read.
What you will have when you are done: a saved report template, a written instruction file Codex follows every run, and one completed report for a real week.
Prerequisites: a verified Search Console property, a list of 20 to 50 queries you actually care about, Codex with access to a project folder, and read access to your own site's repository if you want the advanced version.
Definition of done: you can hand the report to someone who does not do SEO and they can tell you which three queries to look at and why.
Time: about 90 minutes for the first build, under 10 minutes per run after that.
Why the Performance report is not a ranking report
Search Console gives you four columns: clicks, impressions, CTR, and average position. That is a measurement table. A ranking report has to answer a different set of questions, and the 2026 signals make the gap wider than it used to be.
The Zyppy expert survey published on September 9, 2026 collected 13,665 data points from 131 practitioners. Click and behavior signals landed at 29.4%, brand signals at 27.0%, and technical SEO health at 17.5%. Two of the three signals that outrank technical health are invisible in a position column. Our own breakdown of what those numbers change is in the action guide, but the short version for reporting is this: if your report only shows positions, you are reporting on the signal that moved the least.
That is the gap Codex closes. It will not tell you why Google changed something. It will assemble the evidence for the change consistently enough that you can.
Before you start: four decisions
Make these calls before you write anything, because changing them later means rebuilding the report.
- The query set. 20 to 50 queries, grouped into two or three buckets that match how the business thinks. "Product", "comparison", "support" beats "high volume / medium volume / low volume".
- The comparison window. Compare the last 28 days against the previous 28 days. Shorter windows are noisy; longer windows hide the change you are looking for.
- The threshold. Decide what counts as worth reporting. A query moving more than five positions, or impressions moving more than 30% while clicks stay flat, are workable defaults.
- The storage location. One folder, one naming rule.
reports/ranking/YYYY-MM-DD.mdplus adata/subfolder for raw exports. Codex needs a consistent place to write.
Step 1: Export the raw data
Open Search Console, select your property, and go to Performance. Set the date range to 56 days so a 28-versus-28 comparison is possible from a single export, then use the Export button for a CSV of the Queries tab.
Do the same for Pages, and for Devices if you plan to report a mobile-versus-desktop split.
Expected output: three CSV files in data/, named with the export date.
Quality check: open the Queries CSV and confirm the first row of data is not a query containing the word "anonymous". Search Console withholds rare queries, and those rows will otherwise show up in your report as unnamed movement.
If it fails: if the export is truncated, your date range is too wide for the row limit. Export 28-day windows separately and let Codex concatenate them.
Step 2: Write the report contract
This is the step that decides whether the workflow survives past week three. Put the contract in a file Codex reads on every run — AGENTS.md at the project root, or a dedicated instructions file in the report folder.
The contract needs five things and nothing else:
Contract block | What to write | Why it matters |
|---|---|---|
Inputs | Exact file paths and the date range rule | Stops the agent inventing a window |
Thresholds | Your bands, in numbers | Turns a table into a decision |
Output shape | The three sections, in order | Keeps week 30 comparable to week 1 |
Confidence rules | What to say when the data does not explain a change | Prevents confident nonsense |
Boundaries | What the agent must not do | Read-only until you trust it |
A working version looks like this:
## Ranking report contract
Inputs: data/queries-*.csv, data/pages-*.csv
Window: last 28 days vs the previous 28 days. State both dates in the report header.
Report only three things:
1. Moved queries: any query moving more than 5 positions, or impressions up
more than 30% with clicks flat, or any query that left the top 10.
2. Likely explanation: use only the data in the files. If the files do not
explain the movement, write "not explained by this data".
3. Check next week: one line per flagged query, naming the exact page or
query to inspect.
Never state a cause you cannot point to in the data. Never recommend a site
change. Never edit any file outside reports/ranking/.Expected output: one instruction file, committed or saved next to the data.
Quality check: read the contract out loud. If any line could apply to a different site with no edits, it is too vague to constrain anything.
If it fails: if Codex keeps adding sections, the output shape is not specific enough. Name the three headings exactly as you want them.
The report anatomy. The footer that lists the exact files used is the part reviewers trust most, and the part most templates leave out.
Step 3: Generate the first report
Point Codex at the folder and ask for one report using the contract. Ask for the file, not a chat answer, so the output is reviewable and diffable.
The first run is where you will discover what your data actually looks like. Expect two or three rounds of correction. That is normal, and it is the cheapest part of the whole workflow.
Expected output: reports/ranking/YYYY-MM-DD.md with a header, three sections, and a footer listing the exact files used.
Quality check: pick two flagged queries and verify the numbers by hand in Search Console. If they match, the pipeline is sound. If they do not, stop and fix the data step. Do not troubleshoot the analysis on top of a broken input.
If it fails: the most common failure is a date mismatch between the export and the contract. Pin both dates in the header on every run so a two-day offset cannot quietly turn a flat month into a collapse.
The first version I built reported eleven moved queries in a week where nothing much had actually moved. The contract was fine; the export was not. A 30-day file compared against a 28-day window made two days of missing data look like a site-wide collapse. The contract now refuses to run unless the two ranges match, and that failure has not come back.
Step 4: Add the line the agent cannot write
Every report gets one human paragraph: what we shipped, changed, or broke last week.
This is not decoration. It is the fastest way to catch an agent attributing your own release to an algorithm update. When the report says a cluster of product pages dropped and your note says the template changed on Tuesday, the explanation narrows immediately.
Expected output: two or three sentences at the top of the report, written by a person.
Quality check: if the note and the movement section contradict each other, the contradiction is the most valuable line in the report. Keep it visible rather than smoothing it over.
Step 5: Verify before you send
Run these three checks before the report leaves your desk.
- Dates. Both windows stated in the header, matching the export.
- Two spot checks. Two flagged queries verified by hand.
- One contradiction check. Does any claimed explanation reference data that is not in the file list at the bottom?
If all three pass, the report is safe to share. It is a draft of your judgement, not a substitute for it.
The advanced path, when you are ready
Run the workflow by hand for four weeks first. Only automate after you have corrected the same class of mistake twice.
Then the upgrades are incremental:
- Schedule the run. A weekly scheduled run writes the report before you open your laptop. Keep the human paragraph as a required field so the report cannot ship without it.
- Store snapshots in version control. Each run becomes a commit. The diff between two weeks is a faster read than either report.
- Add a second property. Competitor or brand queries sit in a separate report with the same contract, not merged into the main one.
- Add one external signal. A branded-search or share-of-answer check makes the brand signal in the 2026 survey measurable instead of theoretical.
What not to automate: the recommendation step. The moment an agent starts proposing site changes, you have moved from reporting to publishing, and the review burden goes up faster than the time saved.
Troubleshooting
Symptom | Likely cause | Fix |
|---|---|---|
Every query looks like it dropped | Date-range offset between exports | Pin both windows in the contract and the header |
Report is empty | Thresholds too strict for your traffic level | Lower the impression threshold before lowering the position threshold |
Same five queries every week | Query set is too narrow | Add long-tail and comparison queries to the buckets |
Movement with no explanation | Normal for low-volume queries | Keep the "not explained by this data" output and move on |
Numbers differ from Search Console | Property or filter mismatch in the export | Export from the same property and filter set every time |
Maintain the workflow
Three maintenance habits keep this useful past the first quarter.
Review the query set every quarter. A report tracking last year's priorities is a history lesson, not a ranking report.
Re-read the contract when Search Console changes. Google updates the Performance report interface and export fields periodically. If a field disappears, the contract needs an edit the same day.
Keep the old reports. Comparing this quarter's report against the same quarter last year is the only cheap way to separate a real decline from seasonality.
FAQ
Do I need Codex specifically? No. The workflow works with any agent that can read files, run on a schedule, and write a reviewable output. Codex is a good fit when your site already lives in a repository because the report becomes a commit you can diff.
Can I do this with free tools only? Yes. The whole workflow runs on Search Console data, which is free, plus the agent. You only need a paid rank tracker when you want competitor positions or rankings you cannot see in your own property.
How is this different from the Search Console Performance report? The Performance report shows you a table. This workflow produces a decision: which queries crossed a threshold, what the data does and does not explain, and what to inspect next week. It also keeps a record, which the interface does not.
What if my site has very little traffic? Lower the impression threshold and compare 28 days against the same 28 days last year instead of the previous 28 days. Low-volume sites get more signal from year-over-year comparisons than from week-over-week ones.
Should the report include AI Overviews or AI citations? If you want it to, add a separate section with its own contract. Keep it out of the position report, because the sources and the measurement are different, and mixing them makes both harder to read.
Author: Leo Harrington, SEO Analytics Translator for 500+ Executive Reports at Auspia. Leo writes about turning search data into reports that a non-specialist can act on.
