Grounding and Citations
3 min read
Grounding is what Canon does. Citation is how you check it worked.
Grounding Is On by Default
Section titled “Grounding Is On by Default”Every AI generation run is grounded in Canon unless you say otherwise. There is no switch to find and turn on.
In the AI Test Case Generator, the Ground in Canon toggle sits with the other run inputs:
Use the documents in this project’s Canon as the source. Turn it off to generate from the attached requirement alone — useful when Canon is incomplete or out of date.
Turn it off when Canon is thin, stale, or mid-upload — a partially indexed corpus can be worse than none, because it grounds some claims and quietly invents the rest.
Your choice is remembered per project, so a project whose Canon you do not trust stays off until you turn it back on. A project with no Canon at all needs no action: grounding simply retrieves nothing.
What the Model Actually Receives
Section titled “What the Model Actually Receives”Retrieval does not hand the model a handful of sentences. It finds the relevant documents and passes each of them whole, up to a budget.
That is a deliberate choice. Ranking passages individually promoted section introductions — text that describes what a feature is for — over the single most testable sentence in a document, which would sit far down the list and never reach the model. Whole documents keep procedure, edge cases and error handling together.
To reach the corners of a document rather than its opening section, the subject is searched along several axes at once — required fields and validation rules, errors and rejections, limits and defaults, lifecycle and deletion, step-by-step instructions, and the form and controls involved. These are phrased the way a spec would phrase them, because they are matched against your documents.
Both stages of generation are grounded: the coverage map that decides what to test, and the writing stage that produces the steps.
Where Citations Appear
Section titled “Where Citations Appear”Generated test cases and gaps
Section titled “Generated test cases and gaps”Each draft in the review list carries citation chips — one chip per document, not one per passage. Hovering a chip shows the source filename and the exact passage text the model saw.
Gaps carry them too. A gap is only actionable if you can open the document that needs the missing sentence written into it.
Release readiness
Section titled “Release readiness”The AI summary on a release cites the exit criteria it judged against. Without Canon, a readiness call falls back on a generic standard supplied from the model’s priors — “80% pass rate looks healthy” — which is exactly the judgement a sign-off should not rest on. See Release readiness.
Nodes proposed from Canon carry the citations they were drawn from, so you can check a proposed area against the document that implied it before accepting it. See Propose from Canon.
Reviewing a Grounded Draft
Section titled “Reviewing a Grounded Draft”A citation turns review from re-derivation into checking. The workflow that gets value out of it:
- Read the test case.
- Look at the chip. Does the cited document plausibly say this?
- Hover it. Does the passage actually say this?
- If it does, accept. If it does not, the document is wrong, or the model over-reached — both worth knowing.
An uncited draft in a grounded run is a signal, not a defect. It means nothing in Canon covered that behaviour, and the model wrote it from general knowledge. Treat it with the scrutiny you would give an unsourced claim.
When Grounding Does Not Help
Section titled “When Grounding Does Not Help”Canon cannot assert what is not written down. If your specs describe capabilities (“users may edit shared steps”) without describing outcomes, generation will produce capability-shaped test cases with nothing to assert.
Use Ask Canon to check for this before a run. Passages that read like policy statements rather than behaviour are the ones to go and fill in.