Primer facts
Structured facts about your projects that power the AI agent primer and requirements reports - categories, review workflow, and where they surface.
The concept
When an AI agent (or a human relying on AI-generated context) starts work on a project, it needs to know things a codebase alone can't always tell it: which package manager to use, that a particular migration step is handwritten rather than generated, what the deployment process actually looks like, or a hard-won gotcha that cost someone a debugging session last month. Writing this down once, in a structured way, is far more reliable than hoping an agent rediscovers it
- or worse, guesses wrong - every single time.
A primer fact is exactly that: one small, structured piece of project (or workspace) knowledge - a key, a value, and a category - that gets automatically included whenever an agent (or a generated report) asks for a project's primer: its onboarding briefing.
Categories
Every fact belongs to one category, which determines where it renders in the primer and in generated reports:
| Category | What belongs here |
|---|---|
| Tech stack | Languages, frameworks, major dependencies, versions |
| Conventions | Coding standards, naming rules, commit message format |
| Deployment | How and where the project ships, environment specifics |
| Architecture | High-level structure, module boundaries, key design decisions |
| Integrations | External services and APIs the project talks to |
| Gotchas | Hard-won, non-obvious pitfalls worth flagging up front |
| Commands | Exact CLI commands to build, test, run, or deploy |
| Non-functional | Explicit non-functional requirements - performance, security, data-protection, operational targets |
| Glossary | Project- or domain-specific terminology and definitions |
| Other | Anything that doesn't fit the above |
Scope: workspace vs. project
A fact is either project-scoped (visible only in that project's primer) or workspace-scoped (visible in every project's primer, automatically). Workspace facts are for things genuinely true everywhere - a company-wide coding convention, a shared deployment platform - not project specifics. Because a workspace fact adds to every project's primer regardless of relevance, the admin UI shows a standing reminder to use this scope sparingly; a fact that only applies to one project belongs there instead.
Source: manual, imported, or agent-observed
A fact records where it came from:
- Manual - a person typed it in directly.
- Imported - it arrived via a data import from another system.
- Agent-observed - an AI agent, working on the project, noticed something worth recording and proposed it as a fact on its own.
Agent-observed facts start unverified - useful context, but not yet confirmed accurate by a human - and that's exactly what the review queue below exists for.
Managing workspace facts (Admin -> Primer facts)
The Workspace facts tab lists every workspace-scoped fact (visible in every project's primer). Filter by category and by verified state.
- Add workspace fact - create one directly, choosing its category, key, and value.
- Edit (pencil icon) - change an existing fact's content.
- Supersede - replace a fact with a new version while keeping the old one's history rather than silently overwriting it; use this when the old value was genuinely correct at the time but has since changed (a version bump, a process change), so there's still a record of what used to be true.
- Verify (shield icon) - mark a fact as human-confirmed accurate.
- Delete - remove it outright, with a confirmation naming the fact's key.
Reviewing agent-observed facts (Pending review)
The Pending review tab is a cross-project queue of every agent-observed fact that hasn't yet been verified by a human - regardless of which project (or the workspace scope) it belongs to. A badge on the tab shows the current queue count.
Filter by project (or workspace scope) and category, then work each entry with one of three actions:
- Verify - confirm it's accurate as written; it flips to verified and stops appearing in this queue.
- Edit - correct the wording or value before verifying it, for a fact that's directionally right but needs a fix. Editing doesn't auto-verify it - a deliberate Verify click afterward is still required, so an edit alone can't silently mark something as human-confirmed.
- Reject - remove it, with a required reason captured in the audit log, for a fact that's simply wrong or not worth keeping. This is the one place in the primer-facts UI with an explicit "why" prompt, because a rejected agent observation is worth knowing the reason for later (was the agent wrong, or just capturing something too transient to keep?).
Where facts surface
- The project primer - the structured briefing an AI agent or the MCP/skill surfaces pull when it starts work on a project. Facts render grouped by category, in a fixed display order, with workspace facts merged in alongside that project's own.
- Generated requirements-style reports - the non-functional and glossary categories specifically exist to feed the matching chapters of orboto's generated requirements specification report, so those categories carry weight beyond just agent context.
- Personal facts - a related, separate concept: individual users can also record their own personal facts (visible only to them across the projects they work in), which is a different surface from the workspace/project facts this admin page manages.
Why verification matters
An agent proposing "the deploy command is X" and being wrong costs
real time the next time an agent (or a person) trusts it. Verification
is the deliberate human checkpoint between "an agent noticed this" and
"this is now treated as reliable project knowledge" every future agent
session will be handed as fact. Leaving agent-observed facts unverified
indefinitely isn't dangerous by itself - unverified facts still surface
in the primer - but reviewing the queue regularly is what keeps
project knowledge trustworthy rather than merely plausible.
Troubleshooting
- A fact I added to one project shows up in every project's primer
- it was created at workspace scope instead of project scope; edit it (or delete and re-add it under the specific project) to narrow it.
- An agent keeps re-proposing the same fact after I rejected it - rejection removes that specific fact record, but doesn't prevent an agent from observing the same thing again in a later session; if it keeps recurring and is actually correct, verifying it once (or adding it manually) stops the cycle since it will no longer look "new" to the agent.
- The pending-review badge count doesn't match what I see after filtering - the badge counts the full cross-project queue; your current project/category filter narrows what's displayed without changing the underlying count until you act on entries.
- A category I need isn't in the list - the category set above is fixed; use Other for anything that doesn't fit, or note the gap for your workspace's own conventions rather than trying to force a fit into an unrelated category.