Scaffolding goes up before a building and comes down when it's finished. This series is about what went up around the agent while it built the report. We start with the first piece, and it isn't code.
with Elizabeth Cecilia. Tap any underlined word for a quick definition.
Have the report open. The lessons point at real pages and tiles. The .pbix opens in Power BI Desktop; the PDF works on any device, but things like View as and the i buttons need Desktop.
Every of a starts from nothing. It doesn't remember last week, your decisions or your rules. The first thing it reads in this kit is a file at the top of the folder: . That file is the .
Predict first: A new session starts in the kit folder. Before it reads anything, what does the agent know about your project?
01
Six parts, in a fixed order
The kit's brief has six headings. Each one answers a question the agent would otherwise guess at.
What this isThe project in two short paragraphs, and what matters most.
What is in this folderEvery file and its purpose, which tells the agent what it may do with it.
Rules that do not bendTen rules, each one short.
Never without askingThe actions that need a yes first.
How to workSeed first, propose then wait, refresh before checking.
Done meansThe finish line, in two bullets.
The first part is only two paragraphs, but one sentence in it sets the agent's priorities for the whole build:
A reviewer opens the model view and the measures before any chart. The model, the measures and the measure basis register matter most. Pages come second.
Predict first: Without that sentence, what would the agent most likely spend its effort on first?
02
Every file has a purpose
The second part is a table of every file in the folder. For each one it says what the file is for, and so what the agent may do with it. In the brief that last column is called Status. Here are five rows.
PathWhat it is
source.xlsxAll the data, one Excel table per sheet.
spec/model_spec.jsonEvery table, column, relationship and role.
reference/mockup.htmlThe HTML mock-up of the report.
tools/validate.pyChecks the project against the specs and the seed.
seed/A small project saved by hand in Desktop: one of each visual and setting the report uses.
Match each file to its purpose. A is a : the model is built from it. A reference is only there to look at. Some files can't be touched without a yes.
source.xlsx
spec/model_spec.json
reference/mockup.html
tools/validate.py
seed/
In the brief these read: never edit without asking; source of truth for the model; reference only; run after every change; the authority on file formats.
03
Rules that do not bend
The third part has ten numbered rules. Each is one line in bold, with a short reason under it. Three of them:
1. The seed is the authority on file formats. Read the seed, copy its structure and versions, and change only names, fields and positions.
3. No numbers of your own. All data comes from source.xlsx through Power Query.
9. Never say a page works. You cannot open Power BI Desktop. Say "written and validated, not opened". The person opens it and reports back.
Rule 1 points at the , which has its own series: The seed project. Rule 9 exists because the agent can't see what you see: it has never opened .
Predict first: The agent has just built three pages. Which report back follows the brief?
04
A yes covers one step
The fourth part lists five things the agent must ask about first, and wait for a yes:
- git push, or anything that touches a remote, a tag or a release
- amend, rebase, reset --hard, or anything else that rewrites history
- deleting or overwriting a file, unless the agreed step writes it
- editing source.xlsx
- running the s against report/
A yes covers the one step it was given for.
Predict first: Which of these can the agent do without asking?
Predict first: You said yes to a commit. The agent offers to push it too. Is that covered?
05
Done means two things
The last part is the shortest. It's also the one most often skipped:
- python tools/validate.py ends in RESULT: PASS.
- The person has opened the project in Desktop, after a refresh, and said what they saw. Until then it is not done.
Predict first: The prints RESULT: PASS. Is the work done?
06
A brief that learns
A brief isn't written once and left. When something goes wrong, the lesson goes into the brief, so every later session starts with it. This rule was added to the kit's brief the week it was published:
Check each edit before the next command. Never chain an edit to a commit, a run or another edit. After every edit, confirm the change is in the file before doing anything else. A command can report success and change nothing.
It came from a real slip: an edit silently changed nothing, and the commit chained after it ran anyway. Lesson 7 tells the story.
Predict first: Where should a lesson from a slip go, so the next session doesn't repeat it?
07
What went up first
The brief went up before anything else. Next lesson: the two specs, where every table and every tile was decided before a single project file existed.
Write the brief before the build. Give every file a purpose. Make every yes cover one step. Done means opened, not just passed.
And when something goes wrong, put the fix in the brief, where the next session will read it.
Terms in this lesson
Earn 5 XP for every term you know.
Get the project files
Everything is free on GitHub. Open the report next to the lessons and check each step for yourself.
The whole project
The Power BI project, the seed project, the specs and the tools: the whole kit. On the GitHub page, click the green Code button, then Download ZIP, and unzip it anywhere.
The Critical Raw Materials Intelligence report as a single .pbix file to open in Power BI Desktop. Open the latest release under Releases, then Assets, on the right of the GitHub page.