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

Your dashboard — a high-level snapshot of project health.

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:

• Scan budget bars for overruns (red) or margin (green)
• Check node health pips and per-child health dots
• Drill into a child subsystem, or preview its requirements, interfaces, and visuals

The Overview lens doesn't edit your model — it orients you before diving into detail work.

Brief Lens

Renders a node as an 8-section narrative document.

When to use it:

• Explaining a node in readable prose
• Onboarding someone to a subsystem
• Preparing a written summary for a review

What you'll do:

• Generate or update the brief via ⌘K
• Edit any section inline — changes save when you click away
• Lock a section to protect your edits from AI regeneration

The Brief is prose, not a source of truth — the structured lenses own the underlying facts.

Visuals Lens

Generates concept imagery — a 2D gallery and an interactive 3D mesh.

When to use it:

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

What you'll do:

• Generate 2D renders with a chosen style kit, then refine them
• Browse the version timeline for each render series
• Generate and view an interactive 3D mesh

Visuals produces illustration, not engineering data — generated images and meshes aren't model facts.

Architecture Lens

Shows interfaces — how nodes connect and communicate.

When to use it:

• Defining interfaces between subsystems
• Reviewing signal flows (data, power, physical)
• Checking for missing or orphan connections

What you'll do:

• Drag blocks to arrange the diagram; auto-layout, zoom, and export from the toolbar
• Right-click any node for the contextual menu (add, connect, decompose, delete — all with cascade-aware safety)
• Click interfaces to view/edit signals
• Use ⌘K: "Add interfaces to this subsystem"

Tip: Create interfaces early. They clarify boundaries before you've detailed the internals.

Requirements Lens

Manages requirements scoped to the selected node and its children.

When to use it:

• Adding requirements to a subsystem
• Reviewing requirement coverage
• Reviewing requirements across a node and all its descendants

What you'll do:

• Filter by requirement type (functional, safety, etc.)
• Use ⌘K: "Generate safety requirements for battery handling"
• Check the status column for traced vs. orphan requirements

Requirements are scoped — select the system node to see all, or a subsystem to see just that branch.

Behavior Lens

Visualizes state machines for the selected node.

When to use it:

• Modeling operating modes and transitions
• Analyzing startup/shutdown sequences
• Documenting fault handling logic

What you'll do:

• Right-click any state, the canvas, or a transition row for the contextual menu (add state, add transition from/to here, edit, delete with cascade preview)
• Add states via toolbar or ⌘K
• Draw transitions by dragging between states
• Edit every state and transition field from the Inspector — name, type, description, trigger, guard, action, and timing

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

Causality Lens

Renders Harney's Pyramid — a technology dependency view.

When to use it:

• Identifying technology risks
• Understanding what depends on what
• Reviewing technology maturity distribution

What you'll do:

• View the pyramid with nodes layered by abstraction
• Review maturity labels on each item and spot decomposition gaps
• Trace from goals at top to physics at bottom

The Causality lens is read-only — it visualizes structure you've built elsewhere. It answers: "What's holding this up?"

Completeness Lens

Finds gaps in your model.

When to use it:

• Before milestone reviews (is the model ready?)
• Prioritizing where to add detail next
• Auditing model quality

What you'll do:

• Read the three-axis fidelity radar and per-axis cards
• Scan the sidebar tree heatmap for low-fidelity nodes
• Use the gap alert's ⌘K fix prompt: "What's missing from this subsystem?"

Completeness scoring scales with decomposition depth — a leaf part and a top-level system aren't held to the same bar.

Narrative Lens

Generates a systemigram — a visual story of how your system works.

When to use it:

• Explaining the system to stakeholders
• Identifying the "mainstay" (critical path)
• Creating documentation graphics

What you'll do:

• View the auto-generated systemigram
• See the mainstay path highlighted
• Pan, zoom, and export the diagram; regenerate it when interfaces change

If the story doesn't make sense, your model structure might need work.

Dendritic Lens

Shows your decision tree — including the paths you didn't take.

When to use it:

• Reviewing trade study decisions
• Explaining why alternatives were rejected
• Onboarding new team members to history

What you'll do:

• View active nodes vs. pruned nodes
• Click pruned nodes to see rejection rationale
• Search the tree and toggle pruned-node visibility
• Filter the tree by decision type (physics, engineering, mission)

Pruned nodes aren't deleted — they're preserved context. The Dendritic lens makes that context visible.

Verification Lens

Tracks test coverage and verification status.

When to use it:

• Planning verification activities
• Checking requirement coverage before reviews
• Recording test results

What you'll do:

• View coverage metrics per requirement
• Toggle between node-level and tree-level (subtree) coverage
• Add verification records (test, analysis, demo, inspection)
• Link verifications to requirements

Low coverage isn't bad in early phases. Before release, gaps need attention.

Operational Lens

Shows the selected node's use cases as a card grid.

When to use it:

• Reviewing the operational scenarios defined for a node
• Checking which actors and steps a scenario involves

What you'll do:

• Scan use-case cards for actors and the first few steps
• Click a card to open the full scenario in the Inspector
• Generate use cases with AI from the empty state, or any time through ⌘K

Use cases are produced by the dedicated Operational specialist — ask for them through ⌘K and edit them in the Inspector. There is no in-lens add form yet.