Proof
Onboarding reads the repo once, so every change starts from context
A design-partner engineer asked whether every change would need a prompt that explains the repository. Onboarding writes that explanation into the repo once: conventions, vocabulary and decisions become files every later change reads.
On 19 October 2026, on a design-partner call, a data engineer asked us a question that belongs in every onboarding checklist. He wanted to know whether his team would have to explain their repository in every prompt, or whether their data engineering agent could read the files and work out the flow.
"So whenever we are working with Vibedata and we integrate it with our GitHub repositories, Would we need to give prompts that explain the structure of the repository as a whole, or would it have the ability to go into, into the files and understand how the flow is working within the repository?"
The second thing he asked about is already true inside a session. An agent can read the files and follow the flow. The harder problem is what happens when the session ends. Most of that reading is thrown away, and the next change starts by rebuilding the same picture from another prompt.
A prompt that explains the repo can be saved, versioned, diffed and reverted. The trouble is that the explanation usually is not: it lives in the session that produced it, gets rewritten by whoever picks up the change, and drifts from the last version. A new engineer learns the repo from a chat thread. A reviewer cannot check the explanation.
Onboarding writes the explanation down before the first change. The output is a set of files in the repo, committed in one PR and reviewed like any other change. Unlike the session context it replaces, those files keep the explanation after the session ends, carry the same review as the code, and are what the next change reads.
The repo should explain itself
Our onboarding skill opens with its own scope: "Prepare reusable repository context. Keep customer conventions and application behavior. A normal source/model task uses existing context; it does not start onboarding."[3] The whole argument is there: read the repo once, then use what you wrote on every later task.
Onboarding starts from the repo the customer already has. It inspects the dbt projects, dlt pipelines, profiles, CI and existing documents, then reconciles what it finds with the instructions the repo already keeps. The deliverable is one PR of context. The repo keeps its code.
Onboarding asks only where the reading is uncertain
The part that answers the call is the confirmation step. The agent does not ask the engineer to explain the repo from scratch. It builds an inventory from the code and the existing documents, attaches evidence to each line, and proposes a destination for it.
Then it asks about three things: conventions that conflict with each other, decisions the code does not explain, and ownership that is not clear from the files. That is a different conversation from "tell me how your repo works." It is "here is what I read, here is where I think it goes, and here are the places I could not tell."[2]
The agent shows the inventory as one table. Each convention gets an ID, the evidence (a file and line, or a customer decision), its exceptions, its destination and a confirmation state: inferred, confirmed, changed by user or dropped. Established decisions are confirmed evidence, so the agent does not ask about them again.
Every convention gets one destination
An inventory is only useful if every line has somewhere to go. The skill uses one destination per kind of knowledge, and the destination decides what a later change gets.
| What onboarding found | Where it goes | What a later change gets |
|---|---|---|
| A location or identity a script can check | repo-map.json | The paths, sources, entrypoints and commands |
| A rule that says must or never for every change of a kind | A convention skill under .agents/skills/ | The rule, loaded by the task that needs it |
| A business term | CONTEXT.md | The vocabulary the team uses |
| A decision with a reason | An ADR | Why the grain, the filter or the key is what it is |
| A decision a model or pipeline makes that its code does not explain | A design record | The reasoning behind that model or pipeline |
| Anything that should change | docs/review/ | A finding with evidence and a proposed action |
The split is the part we would copy. A fact a script can check belongs in the map, because a script can fail when it goes stale. A must or never belongs in a rule skill, where an agent reads it while it writes.
A decision with a reason belongs in an ADR, where a person can find it later. Anything that should change belongs in the review, where it gets an owner and a decision.
If a convention lives in two places, it drifts. If it lives only in the session that produced it, it disappears when the session ends. The destination rule makes the context reviewable: a reviewer can see why the grain is what it is, and find the ADR that says so.
The skill keeps AGENTS.md as the entry point and puts the conventions in skills. A new agent reads the index, loads the rule it needs, and does not read the whole library.
The review is the queue, and onboarding does not fix what it finds
Onboarding writes context. It does not convert pipelines, repair models or tidy READMEs. Anything that should change becomes a finding in docs/review/: one row with a kind (platform, convention, bug, gap or style), the evidence, the effect and a proposed action.
Triage changes only the status: intent, proposal → P-NNNN, declined: <reason> or deferred. It does not authorize the edit. A finding that becomes an intent does its own before-and-after comparison in a later session, with the repo's context already in place.
That separation keeps the context PR small enough to review. It also makes the review useful to a Head of Data: the first onboarding review is a list of what the team did not know about its own repo, with evidence, sorted into work the team can schedule.
The first review of our reference repo found a bug that had stayed green. Every yellow trip reported airport_fee_status = 'missing': the extras models hashed the trip key from TIMESTAMPTZ columns, while the trip models used naive timestamps, so the rejoin matched nothing while the build passed.[2]
The same review found that a fresh checkout could not build because dbt deps was not run before dbt build, and that no CI job ran the pytest suite. It also found sqlfluff violations and declined a mass reformat, because sqlfluff fix had dropped a values column list and the project kept its style with recorded exceptions.
None of those fixes were made during onboarding. They were filed, triaged and left for normal intents.
The rehearsal is a test for the documentation
Verification is where an onboarding skill can fool itself. A repo can look fully mapped and still send the next agent to the wrong file. The skill handles that with a rehearsal: add a source, change a mart, use the most relevant confirmed procedure.
For each task, the agent predicts from AGENTS.md, repo-map.json and the rules alone which files it will read and change, which skills apply, and which exact command runs. Then it checks the prediction against the repo. A miss is fixed in the context or filed as a finding.
That is a documentation test with a pass or fail answer. A map you never navigate is a guess, which is why the rehearsal is part of onboarding.
The skill is also careful about what verification proves. Its report separates context readiness, runtime loading, sandbox execution, persistent Domain state and Studio lifecycle. A structural check does not prove that a later task finds the right files.
The skill has boundaries
We have not measured how much prompt text onboarding saves, or how often a later change gets the right answer from the context on the first try.
The skill handles an empty repo and a repo that already uses dbt or dlt. An empty repo with an existing warehouse is not supported yet. Converting raw scripts to dlt and generating synthetic data are out of scope.[1]
When a decision is inferred rather than documented, the skill marks it inferred from code and files it for confirmation. The context is allowed to be incomplete. It is not allowed to pretend.
A team can start with the destination test
The destination test works without our product. Ask which convention your data engineering agent has to be told twice. If the answer lives only in a past session, a chat thread or one engineer's head, write it down.
Then put it somewhere with an owner. A fact a script can check goes in a map. A must or never goes where the agent reads it on the task.
A decision with a reason goes where a person can find it. Anything that should change goes into a review with evidence, where it gets an owner.
That last move is the one most teams skip. A fix made quietly during onboarding is a change nobody scheduled and nobody reviewed. A finding is work the team can see, estimate and decide about.
The measure that moves is time per PR: the total human effort per accepted change, including the spec, review and rework. If every PR starts with the same explanation, that cost is paid on every PR. A team that writes the explanation once can spend the next change on the change.
The productivity claim for Vibedata is that the same team ships more, measured as time to PR and time per PR. The gain is conditional on changing what the team focuses on and how it builds, and review compounds: each accepted change that is easier to review shrinks the next review. We have not measured onboarding's effect on either measure, so the claim here is the mechanism.
Take the question back to your own repo
The engineer on the call asked whether the agent could read the files and understand the flow. It can. The durable version of that answer is a repo that explains itself to every session.
Which convention in your repo exists only in the last prompt someone wrote?
References
- Onboarding skill design and drafts,
accelerate-data/sample-nyctaxi-comp, PR #7. Private reference repo; containsdocs/setup/onboarding-skill-design.mdand the first onboarding review. - Onboarding review,
docs/review/2026-10-14-onboarding-nyctaxi.md, same reference repo. Findings R-1, R-4, R-5 and R-6. - Onboarding VibeData skill,
accelerate-data/vibedata-official.
Get the weekly roundup by email
One email a week: what got easier in Vibedata, a recipe to try yourself, and where data engineering is heading.