> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kanaeru.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Blueprints and understanding gaps

> How Kana shows you what she understood before writing code, and how you correct her.

A **blueprint** is a generated mockup, diagram, or spec that shows what Kana understood. Blueprints are produced before any code is written, so you can confirm they match what you meant. A misunderstanding caught in a blueprint costs a comment. Caught after delivery, it costs a rebuild.

## Blueprint types

| Type | Shows |
| - | - |
| **UX Mockup** | Screens and layout, built as a live, clickable prototype of the real route. Screens not yet prototyped show as planned |
| **User Journey** | The steps a user takes, broken into scenarios |
| **Sequence Diagram** | How components talk to each other over time |
| **API Contract** | Endpoints, requests, and responses (OpenAPI) |
| **Data Model** | Entities and relationships |
| **Domain Model** | Business concepts and their rules |
| **Architecture** | Components, deployment, integrations, and data flow |
| **State Machine** | States and the transitions between them |
| **Quality Profile** | The quality attributes the work must meet |
| **Intent Spec** | The intent behind the outcome, stated precisely |
| **Tech Stack** | The technologies the work will use |
| **Exploration Canvas** | Free-form planning prose |
| **Code Graph** | How the existing code is structured |
| **Code Wiki** | Written notes on how the existing code works, which agents read while planning and building |

[Blueprint examples](/concepts/blueprint-examples) shows the planning types for one example outcome, rendered and as source. It doesn't include Exploration Canvas, Code Graph, or Code Wiki, because those come from free-form planning or from analysing your existing code. For the editors and review tools, see [Blueprint editor and tools](/guides/blueprint-editor).

Outcome blueprints describe the change. Once an outcome is completed, its blueprints are promoted into the vision's shared baseline, so the next outcome starts from an up-to-date picture.

## Reviewing a blueprint

Open a blueprint from its outcome in the workspace, or from the link Kana posts in chat.

* **Approve** it when it matches what you meant. You can add a comment.
* **Reject** it with a reason and a clarifying question. Kana revises the blueprint and asks you to review again.
* **Annotate** a specific part to start a thread about it, or edit the blueprint directly. Data models, state machines, domain models, and user journeys have visual editors.

Approved blueprints become part of the evidence package for the outcome.

## Understanding gaps

An **understanding gap** is a place where what Kana understood may not match what you meant. Gaps appear in the workspace and in chat as questions for you.

| Type | Meaning |
| - | - |
| Missing info | Kana needs information she doesn't have |
| Ambiguity | The request can be read more than one way |
| Assumption | Kana made an assumption you should confirm |
| Decision | A choice that has been made and recorded |
| Risk | Kana sees a risk worth raising before building |
| Escalation | Something needs a person's call |
| Spec gap | Part of the request isn't covered by any blueprint or task |
| Intent drift | The plan has drifted from what you asked for |
| Comprehension | A check that you and Kana understand the plan the same way |
| Context | Context you hold that Kana couldn't have known |

You resolve a gap by answering it, deferring it, or marking it not applicable. **Risk, escalation, spec gap, intent drift, comprehension, and context gaps are blocking**: the outcome can't move from Review to Execution until they're resolved. Any gap raised before planning starts must be resolved before planning can begin.

## Spec drift

A **spec drift** is a place where what was built no longer matches the approved spec or blueprint. Drifts come from two places:

* An agent finds that the code diverges from the spec while it's building or checking a task.
* You or Kana edit a task's content or acceptance criteria after approval, which records an **Outdated doc** drift so the docs catch up.

Each drift has a type (**Missing feature**, **Incorrect behavior**, **Outdated doc**, or **Deviation**) and a severity from Low to Critical. They're listed in the **Specification Drifts** panel.

The easiest way to deal with drifts is to ask Kana to take care of them. She checks each one against the code and the spec, fixes whichever side is wrong, and marks it resolved. You can also choose **Mark Resolved** yourself.

Drifts don't block phase changes. They're separate from the retrospective's drift check, whose **Drift blocker** verdict does hold up completing the outcome (see [Accepting a delivery](/concepts/outcomes#accepting-a-delivery)). Separately, during a task's pipeline, a **blueprint conformance** check verifies the implementation against its API contract blueprint, and that check does block the task until it passes.


## Related topics

- [How Kanaeru works](/concepts/how-kanaeru-works.md)
- [Kanaeru overview](/index.md)
- [Outcomes](/concepts/outcomes.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.