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

# Process observations

> Pull the evidence trail behind a process — what changed, what happened, why it ran this way.

Use these tools when the user asks "what changed?", "what happened?", or "why does this run this way?"

| Tool                         | When to use                                                                                                                                                                                                                                                                                                                                                                            |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `get_recent_process_changes` | Workspace-wide version-change feed. "What has been edited recently?"                                                                                                                                                                                                                                                                                                                   |
| `get_process_observations`   | Observations on a specific process. Each surfaces the friction signals — `rationale`, `windows_time_frame`, `negative_deviations`, `positive_deviations` — and a session reference. Default response is the summary shape; pass `verbosity="full"` to also include the runtime inputs, outputs, and the step-by-step narrative (heavy — use a small `limit`). Optional version filter. |
| `get_observation_citation`   | The activity timeline behind an observation: what the user did, when, on which systems. The most "primary source" evidence Klarity has. Pass the `observation_resource_key`; use `verbosity` (`low`/`medium`/`high`) for detail, and `activity_block_index` to page through the timeline one block at a time. Only works for your own sessions.                                        |
| `list_sessions`              | Recent workspace sessions, paginated. Each entry returns the processes the session updated, its duration, and who created it — a quick way to see recent activity and who's driving it.                                                                                                                                                                                                |

## What an observation is

An observation is a captured execution of a process — a real session, attached to a specific process and version. The **activity timeline** is the underlying sequence of user actions that produced the observation — the systems they used, what they did, when.

If you only call one tool from this group, call `get_observation_citation` on a top observation. It is the closest thing the workspace has to a video replay. It only works for your own sessions.

## Common chains

* **State-of-team brief**: `get_recent_process_changes` → drill into specific processes via [`fetch`](/tools/entry-points) or `get_process_details`
* **Deep-dive on a process**: `get_process_observations` (summary mode, scan the friction signals) → pick the most relevant → re-call with `verbosity="full"` for the narrative, or jump straight to `get_observation_citation` for the activity timeline
* **Confirm a transformation candidate**: `get_process_observations` for exception patterns → `get_observation_citation` to confirm the manual pattern with concrete evidence

## Cite what you find

Observations have timestamps and version pointers. When the user asks "what's the evidence?", surface the observation timestamp and the version it was logged against — that's a citation the user can audit in Klarity.

## Deviations

Each observation carries the agent's per-session understanding of how that run compared to the documented process:

* **Positive deviations** — places where the user went *beyond* the documented path in a useful way: a shortcut, a better validation step, a quality-improving move worth promoting.
* **Negative deviations** — friction or workarounds: an extra manual step, a retry, a small fix to keep moving.

Both are judgments made in isolation against one session's activity timeline. Per-session friction often looks routine on its own, so `negative_deviations` is frequently empty on individual observations even when a pattern is present across many sessions.

### How to use deviations

A single observation gives you the single-session view. The signal most teams want — "the same workaround appears on 4 of 5 captures," "this retry is systemic" — is **cross-observation deviation analysis**: the surface-level patterns that only emerge when you aggregate across the observation set for a process.

Two paths:

1. **Klarity Advisor** does this aggregation natively across the workspace.
2. **MCP-stitched**: pull `get_observation_citation` across the observation set for the process, then diff against the pinned process version yourself. The MCP exposes everything Advisor reads — the cross-observation pass is what you stitch.