Canon Best Practices
3 min read
A good Canon is small, current and authoritative. A large one full of drafts and meeting notes produces confident citations of documents nobody stands behind.
Admit Only What You Would Stand Behind
Section titled “Admit Only What You Would Stand Behind”The test for a document is simple: if a test case cited this, would you accept it as proof the behaviour is correct?
| Admit | Leave in Files |
|---|---|
| Product requirement documents | Meeting notes and brainstorms |
| Feature specs and design docs | Draft specs still under discussion |
| API contracts | Bug reports and support tickets |
| Acceptance and exit criteria | Screenshots and recordings |
| Standards you are held to | Old versions kept for history |
Everything in Canon is treated as authority. There is no “for reference only” tier, and a superseded spec cites just as confidently as a current one.
Prefer Documents That State Outcomes
Section titled “Prefer Documents That State Outcomes”Retrieval can only surface what the document contains. Specs written as capability lists give the model nothing to assert against.
- Weak: “Users may edit shared steps.”
- Strong: “The Create Shared Step button stays disabled until the name is filled in.”
The second sentence produces a test case with a real expected result. The first produces a test case that restates the requirement.
Where a spec is thin on outcomes, the fastest fix is usually to add the numbered instructions and the error messages — they are the parts that turn into steps and assertions.
Keep It Current
Section titled “Keep It Current”Canon indexes a document once. Replacing the file does not re-index it.
Build these into your process:
- Re-index after a spec revision. Otherwise the AI cites the version you replaced.
- Remove superseded documents. A stale spec in Canon is worse than a missing one — the AI will cite it and a reviewer will believe it.
- Check the Grounding now tile, not the document count. Documents that failed to parse still appear in the list.
Check Before You Generate
Section titled “Check Before You Generate”Before a large generation run, search two or three of your intended subjects in Ask Canon.
If a subject comes back with nothing, you have learned in ten seconds that generation on it will be ungrounded — instead of learning it after reviewing forty drafts. Either add the document or turn Ground in Canon off for that run so nobody mistakes the output for grounded work.
Use Workspace Scope Sparingly
Section titled “Use Workspace Scope Sparingly”Workspace Canon grounds every project in the workspace. That is powerful for a real standard and expensive for anything else, because a single wrong line propagates into every product’s test cases.
A good rule: a document belongs at workspace level only if it would be wrong for any project to ignore it.
Name Documents for Their Citation
Section titled “Name Documents for Their Citation”Titles appear on every citation chip, in release readiness summaries and on Atlas nodes. Checkout API v2 — payment contract is a citation someone can act on. final_v3_REVIEWED.docx is not.
Rename the source file before adding it to Canon.
Watch the Passage Count
Section titled “Watch the Passage Count”A document indexed to far fewer passages than its length suggests usually means the extractor found less text than you expected — a PDF that is mostly diagrams, or a spreadsheet where only one sheet has content.
That document is in Canon and grounding almost nothing. Open it, check what is actually text, and re-export if needed.