Cairn Documentation

Lens Workflows

Each lens in Cairn shows your model from a different angle. This section explains when to reach for each lens and what you'll accomplish there.

Overview Lens

The hub for the selected node: what it is, how it is doing, and the way into every other lens.

When to use it:

Starting a work session (what needs attention?)
Preparing for a review (are we on track?)
Checking budget status (mass, power, cost)

What you'll do:

Rename the node or rewrite its description where you read it
Scan the lens cards: requirements traced, verification coverage, states, use cases, brief sections out of date. Click one to open that lens.
Take the suggested next step, the first gap Completeness finds that AI can help close, which opens ⌘K with an editable prompt
Scan budget bars for overruns (red) or margin (green)
Drill into a child (its top edge shows its health), or preview requirements, interfaces, and visuals

"Traced" means the same thing here, in the Requirements lens and in Quality: a trace link that hasn't been rejected touches the requirement.

Brief Lens

The selected node in eight short sections of prose, for someone reading it for the first time, each of which knows what it was written from.

When to use it:

Explaining a node in readable prose
Onboarding someone to a subsystem
Preparing a written summary for a review, and checking it still matches the model

What you'll do:

Read each section with what it covers (Purpose & Scope draws on the node and its requirements, Interface Summary on its interfaces, and so on) and the entities it cites. Click a cited id to open it; one struck through is no longer in the model.
See which sections are out of date, and why: "interfaces changed", "requirements and verification changed". The header counts them.
Use the header's one AI action, which does what the brief needs most: update the sections that are out of date, write the missing ones, or rewrite it. ◆ Rewrite on a section asks for just that one. Every AI rewrite goes through Change Review, which shows each section's old and new text.
Edit a section in place; it saves when you click away, and Esc puts it back
Text you write locks its section, so AI leaves it as it is. Unlock it to let AI rewrite it.
On a node with no brief, write it with AI or start it by hand

The Brief is prose, not a source of truth: the structured lenses own the facts. A locked section that the model has moved on from says so quietly, but stays yours.

Visuals Lens

Concept images of the selected node, and a 3D model of it. Each image says what it was drawn from, and the lens says when that has changed since.

When to use it:

Picturing what a system or subsystem looks like
Iterating on a concept render across style kits
Building a 3D model for spatial reference

What you'll do:

Generate an image in a style kit, drawn from the node's brief, its description, its parameters or its parent's brief. A kit you have used before adds a version to that series.
Read the gallery: each series shows its newest version, and one drawn from something that has changed since says Out of date. Regenerate it to draw it from the model as it is.
Open a series for its versions, its provenance, a download, and Refine when the image provider can edit
On the 3D Viewer tab, generate a model from the description and a reference image (the newest, one you pick, or none). A new model replaces the old one only once it is built.
← → move between the two tabs.

Visuals produces illustration, not engineering data: generated images and meshes are saved with the project, but they aren't model facts and History doesn't list them. Images made before 1.15 didn't record what they were drawn from, so they never read as out of date.

Architecture Lens

How the selected node is built: its children as blocks, and every interface between them at any depth.

When to use it:

Defining the interfaces between subsystems, or between a subsystem's assemblies
Checking what crosses a node's boundary before you detail its insides
Finding blocks nothing connects to, and interfaces with no signals or protocol

What you'll do:

Read the Diagram: solid connectors run between the blocks themselves, dashed ones through their parts or across the boundary. Arrows show which way signals flow. Click a connector for its interfaces; double-click a block to open its parts.
Scan the N² chart: row A, column B is what A sends to B. An empty row means a block feeds nothing to its siblings. Click an empty cell to start an interface. Arrow keys move between cells and Enter opens one.
Work through the Interfaces list: filter by where an interface sits or to those with issues, and expand a row (→) for its signals' direction, data type and rate.
On a node with no parts, see it in context: everything it connects to, and where those nodes live
Drag blocks to arrange them, or use Auto layout; right-click a block to add a part, connect it, decompose it or delete it

Tip: define a subsystem's boundary interfaces before its insides. The parent's diagram picks them up as connections straight away.

Requirements Lens

What the selected node must do, where each requirement comes from, and what is still missing.

When to use it:

Writing or reviewing a subsystem's requirements
Flowing system requirements down to subsystems and assemblies
Finding gaps before a review: untraced, unverified, failing, or poorly worded

What you'll do:

Read each requirement with its statement, type, priority, what satisfies it, and its verification methods (I, A, D, T, coloured by status)
Switch to Flowdown to see derived requirements nested under their parents across levels, each tagged with the node it lives on
Use the gap chips (Untraced, No verification, Failing, Wording) and the type, priority and search filters
Add a requirement with its statement, and pick the parent it derives from, or use ◆ Flow down to have AI derive child requirements
Move with ↑ ↓, open with Enter, search with /

The inspector edits the links themselves: the parent a requirement is derived from, the nodes that satisfy it (link or unlink), and the verification activities that cover it (add one by method).

Behavior Lens

The selected node's state machine: the modes it can be in, the events that move it between them, and whether the machine holds together.

When to use it:

Modeling operating modes and the events between them
Checking that every mode can be reached and none is a trap
Seeing which events a mode ignores, such as a fault only one state handles

What you'll do:

Read the Diagram, laid out top to bottom by steps from the initial state, and step through it with the simulator
Switch to Transitions for the transition table, or Events for the state × event matrix
Add states and transitions with + State and + Transition, a drag between states, the right-click menus, or Enter on an empty matrix cell
Fix what the header flags (no initial state, unreachable states, dead ends, final states with exits, competing transitions) by hand, or with ◆ Fix with AI
Move with ↑ ↓ in the table and the arrow keys in the matrix, open with Enter, search with /

The inspector shows where a state or transition sits in its machine: a state's transitions in and out, and a transition's From and To, which you can change to any state of the same machine.

Focus on nodes with meaningful operating modes — controllers, power systems, anything with fault states.

Causality Lens

Harney's Pyramid of Causality: the selected node on top, what it rests on tier by tier beneath it, and how far along each stone is. The node can be no further along than the least mature thing it rests on, and the lens says what that is.

When to use it:

Finding the technology that holds a system back
Checking a declared readiness against what it rests on
Seeing what has never been assessed

What you'll do:

Read the note under the header: the limit ("can be no further along than prototype"), the stones that set it, and whether the node claims more than that.
Scan the tiers: domain technologies, components, then parts and materials, with the interfaces and requirements beneath. Each stone shows its stage and confidence; one not assessed says how far along it can be at most. Alternatives set aside in a trade study are not stones.
Click a stone to set its stage, confidence and evidence in the inspector, or double-click it to rebuild the pyramid on it.
◆ Assess maturity asks AI for a stage, confidence and evidence for each stone not yet assessed. It arrives in Change Review, and it never changes a stage you set.

Stages run concept, prototype, in development, tested, in production, mature. Deprecated is an obsolescence risk and counts as mature in the roll-up. It answers: "What's holding this up?"

Completeness Lens

What is missing from the selected node, as checks the model can answer, along Pace's fidelity axes: what it is, what it does, how it connects, and how we know.

When to use it:

Before milestone reviews (is the model ready?)
Deciding where to add detail next
Walking down the tree to the node with the most gaps

What you'll do:

Read the four axes, then each check: described, broken into parts, has a state machine and is it sound, has use cases and are they complete, requirements traced and with acceptance criteria, parts connected, actors in the model, requirements verified, nothing failing.
On a gap, open the lens that fixes it, or ◆ Ask AI where AI can help. ↑ ↓ move between checks, and Enter opens the lens.
Pick a part from Its parts, which lists how many gaps each one has, to go there next
While the lens is open, the System Tree shows each node's gaps, or ✓ when nothing is missing

A check is a fact about the model, never a count held to a target. Checks that don't apply are left out: systems and subsystems are expected to have parts, requirements and a state machine, while an assembly or part can be a leaf, and an external actor or an alternative set aside only has to say what it is.

Narrative Lens

How the selected node's parts work together, told as a systemigram: a mainstay that turns what the node takes in into what it is for, and the flows that feed it or support it.

When to use it:

Explaining a system or subsystem to stakeholders
Finding the mainstay, the chain of parts that carries the node's purpose
Spotting parts that nothing connects to, which the story has to leave out

What you'll do:

See the parts (the node's children, less alternatives a trade study set aside) and the links between them, drawn before any AI runs. A link joins two parts that an interface connects, at any depth, and nodes outside that the parts connect to appear dashed.
◆ Write the narrative to have AI pick the mainstay and a verb for each link, and write the sentence and a few paragraphs. It arrives in Change Review like any other proposal.
Read the systemigram from the top left along the mainstay. Click a part to inspect it, press Enter on a focused one, or double-click it to read its own narrative.
Use the Links table: who does what for whom, its role, and the interfaces that carry it. Click an interface to open it.
When the node's description, its parts or the links between them change, the lens says which, and ◆ Update the narrative retells what that touches. Export the diagram as a PNG in either theme.

The inspector shows where a part sits in its parent's story: its role, what it does for its neighbours, and the mainstay with it marked. If the story doesn't make sense, the model's structure may need work.

Dendritic Lens

The decisions behind the selected node's design, dead branches included: for every part that has parts, what was chosen, what was set aside and why, and what is still open.

When to use it:

Reviewing trade study decisions
Explaining why alternatives were rejected
Finding decisions whose reasoning is not in the model

What you'll do:

Read each decision: the parts chosen, then each alternative set aside, with the part it was weighed against ("instead of Battery Pack"), its decision type and phase, the reason it lost and the first principle that decided it.
Filter to the decisions with alternatives, without any, or still open, and by decision type when there is a mix.
Move between decisions with ↑ ↓ and open one with Enter. In the inspector, mark an option chosen, open or set aside, say what it was weighed against, and write why.
◆ Suggest alternatives asks AI for options a competent engineer would have weighed. They arrive in Change Review as alternatives set aside.

Alternatives aren't deleted: they stay in the model, set aside, so the reasoning travels with the design. A decision type or phase shows only where one is recorded.

Verification Lens

How each requirement will be shown to be met, and where that stands.

When to use it:

Planning verification: which method proves each requirement
Tracking closure before a review or a test campaign
Recording results

What you'll do:

Read the Matrix, a verification cross-reference matrix: one row per requirement, a column for Inspection, Analysis, Demonstration and Test, and the requirement's overall state
Click an empty cell to add that method for that requirement
Switch to Activities to work through every verification by status (failing first) and set status in place
Read closure on the bar: passed, in progress, failing, and requirements with no method yet
Record results and change the method in the inspector, next to the acceptance criteria the activity must show

Closure counts requirements, not activities. A requirement passes when every activity verifying it has passed, and it is failing as soon as one fails or is blocked.

Operational Lens

How the selected node is used: its use cases, who takes part in each, what holds before and after, the steps, and the requirements traced to them.

When to use it:

Writing the operational scenarios a system must support
Checking that every actor a scenario names is in the model
Tracing requirements back to the scenarios they come from

What you'll do:

Read the actors: the external actors of the node and the nodes above it, with how many use cases each takes part in. A name no use case can match is flagged, and + Add to the model adds it as an external actor.
Scan each use case: its actors, Before and After, its steps, and the requirements traced to it. ↑ ↓ move between them, and Enter opens one in the Inspector.
In the Inspector, edit every list in place: Enter adds a line after, Esc puts it back, and steps move up and down. Trace a requirement from the node or below.
+ Add use case starts one by hand; ◆ Suggest use cases asks AI, which names actors the way the model does.

An actor is linked by its name. Conditions and steps are prose, and Cairn reads nothing into them that you didn't write.