Key Concepts
What repository indexing, document freshness, flows, and guards mean — and why they matter.
Superpositional has a few core concepts that appear throughout the product. This page defines them.
Repository indexing
When you connect a repository, Superpositional clones it, analyses the code, and indexes everything into its internal datastore.
The result is a structured understanding of your codebase:
- Entities. Functions, classes, files, modules — the building blocks of your codebase, extracted and stored as structured data.
- Relationships. Which functions call which, what imports what, how modules depend on each other. The graph of connections between entities.
- Semantic search. Your code is indexed so you can search by meaning, not just keywords. When you ask "where is the authentication logic?", Superpositional finds the relevant code even if your query doesn't match any exact names.
Indexing runs automatically when you first connect a repo and re-runs when code is pushed. You don't need to trigger it manually (though you can).
Document freshness
Generated docs go stale. A function signature changes, a parameter gets renamed, a module gets restructured — and the docs still describe the old version. Normally you wouldn't notice until someone reads the doc and gets confused.
Superpositional detects this automatically. When documents are generated, structured claims are extracted from them — specific, verifiable statements about the code ("function X takes parameters A and B", "module Y exports class Z"). When code changes, those claims are checked against the updated codebase.
If a claim no longer holds, the document is flagged as stale.
The key detail: freshness checks are a structural comparison, not an LLM call. They don't burn tokens or cost credits per check. You get continuous staleness detection without continuous cost.
Flows
A flow is a pipeline run triggered by an event in your repository. Flows are how Superpositional reacts to things happening in your codebase.
Each flow has stages and a status. You can see flow progress on the Flows page in real time: what triggered it, what stage it's at, whether it succeeded or failed.
Common flow triggers:
- Push to default branch. Code was pushed. Superpositional re-indexes the affected code and checks for drift.
- Pull request. A PR was opened or updated. Superpositional reviews it — architectural violations, dependency breakage, coding standard violations via guards.
- Issue opened. A GitHub issue was created. Superpositional can investigate it, trace potential root causes, and suggest fixes.
- CI failure. A GitHub Actions workflow or check run failed. Superpositional investigates the failure automatically.
- Release published. A release was published. Superpositional can generate a changelog.
If a flow fails, the Flows page tells you which stage failed and why.
Guards
Guards are pre-built review agents that enforce coding standards on pull requests. Each guard covers a specific area — code quality, security, failure handling, readability, infrastructure wiring, observability, data consistency, and delivery practices.
The available guards are:
| Guard | What it checks |
|---|---|
| Code Quality | Simplicity, dead code, premature abstraction, consistent patterns |
| Security | Hardcoded secrets, missing auth, input validation, vendor abstraction |
| Failure Handling | Silent error swallowing, missing implementations, stale tests |
| Readability | Naming, comments, code clarity |
| Infrastructure Wiring | Function wiring, env var linkage, resource permissions, event subscriptions |
| Observability | Logging, metrics, operability, third-party failure tracking |
| Data Consistency | Cross-language key consistency, default value mismatches |
| Delivery | PR size, thin slices, focused changes |
Each guard contains multiple principles — specific rules with guidance tailored for code review and diagnostics. When a PR is reviewed, enabled guards run in parallel and report findings with the specific principle that was violated and why it matters.
Guards are enabled or disabled per organisation from the Settings page. All guards are enabled by default. You toggle off the ones that don't apply to your team.