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

# Session Practices

> Built-in prompt modules (Product Feature, Project Clarifier), how they compose, and how to add another practice.

## Overview

A **practice** is a built-in prompt module. Each practice adds its own instructions to the live discourse prompt, the post-session Pattern synthesis prompt and the summary prompt, and may define structured output that is sanitised and stored in its own tables.

Sessions can carry up to **three** practices. They compose in **registry order**, independent of selection order. A session with **no** practices keeps byte-identical prompts to the pre-practices baseline (protected by tests).

| Practice | Registry key | Suggested for | Output |
| - | - | - | - |
| Product Feature | `product_feature` | Meeting | Work items (features, improvements, bugs) |
| Project Clarifier | `project_clarifier` | Meeting, Assembly group, Interview | Project candidates with pre-filled onboarding |

Facilitators choose practices on the session setup wizard (create and edit). Session type only drives **suggestions**, not pipeline behaviour on its own.

## Framework

Implementation lives in `api/crates/core/src/practice/`:

* `Practice` enum and `PracticeModule` trait (`label`, `description`, `suggested_for`, directives, optional `output_schema`).
* `compose_pattern_block`, `compose_summary_block`, `compose_output_schema` for prompt assembly.
* `sanitise_and_persist` per module (called from Pattern synthesis after `practice_outputs` are returned).
* `render_summary_sections` appended when a session summary is read (independent of the summarisation job).

Persistence and API routes: `api/crates/core/src/session_practices/` and `api/crates/api/src/routes/session/session_practices_routes.rs`.

Redis publishes `kair:session_practices` when work items change so the session UI can refresh.

## Product Feature

**Purpose:** turn product discussion into a triage-ready list of features, improvements and bugs, each grounded in transcript evidence.

**Work item kinds:** `feature`, `improvement`, `bug`.

**Common fields:** title, area, origin (`stated` | `inferred`), reception, priority signal, raised\_by, evidence (verbatim excerpt + `start_time_seconds`), optional `pattern_card_key`, confidence, suggested labels.

**Kind-specific body** (stored in JSONB, validated on read): user story / problem / proposal / acceptance criteria for features; current and desired behaviour for improvements; observed / expected behaviour and reproduction context for bugs.

**Sanitisation highlights** (`product_feature.rs`):

* Drops items without grounded evidence.
* Caps inferred items at three.
* Merges duplicates by normalised title (`card_keys_match`).
* Regeneration merge respects `edited_by_user` and `dismissed` / `exported` rows.

**UI:** work items panel on the session summary view, GitHub-issue Markdown copy (`ui/src/lib/workItems/renderWorkItem.ts`), pattern canvas badge when a card links to items.

## Project Clarifier

**Purpose:** surface initiatives that deserve their own `project` (or `event`) workspace, pre-fill onboarding from the transcript, and create a workspace plus Origin brief in one confirmed step.

**Candidate fields:** name, pitch, maturity (`idea` | `shaped` | `committed`), champions, onboarding answers (template ids from `onboarding_template`), clarifying questions, pattern card keys.

**Onboarding template** is server-side (`context.rs`); the create-project modal reuses `OnboardingEditor`.

**Create project:** `POST /sessions/:session_id/project-candidates/:id/create-workspace` with placement (`child_project`, `child_event`, `top_level_project`) and carry-forward sections for the Origin brief. See shaping notes in `agent-os/specs/2026-09-24-1200-session-practices/shape.md`.

## Adding a practice

1. Add a Postgres enum value on `practice` (migration `ALTER TYPE ... ADD VALUE`).
2. Add a `Practice` variant and a module implementing `PracticeModule`.
3. Register the module in `registry()` in fixed order.
4. Implement `sanitise_and_persist` and `render_summary_sections`.
5. Wire `practice_outputs` sanitisation in `practice/mod.rs` `persist_practice_outputs`.
6. Expose the key via `GET /practices` and add wizard copy in `ui/src/lib/i18n/locales/*.json`.

No change to the work-item or candidate tables is required beyond the enum value.

## Reference evaluation

Hand-labelled **synthetic** fixtures and metric code live under:

* Fixtures: `api/crates/core/eval/session_practices/fixtures/`
* Scoring: `api/crates/core/src/practice/evaluation.rs`

```bash theme={null}
cd api/crates/core
cargo run --bin eval-session-practices
cargo test -p kair-voice-core practice::evaluation::
```

### Product Feature metrics

| Metric | Meaning |
| - | - |
| Stated recall | Share of gold **stated** items matched after sanitisation |
| Stated precision | Share of predicted **stated** items that match gold |
| Grounding rate | Share of raw model rows with non-empty evidence excerpts |
| Kind accuracy | Share of gold stated items matched with the correct kind |
| Duplicate rate | Share of duplicate title pairs in the raw model payload |
| Inferred acceptance | Share of gold acceptable inferred items present; penalised if rejected gold appears |

Fixture: `syn_product_team_export_work_items.json`.

### Project Clarifier metrics

| Metric | Meaning |
| - | - |
| Candidate recall / precision | Gold candidate names vs sanitised predictions (`card_keys_match`) |
| Over-promotion rate | Gold **false project** titles that appear as candidates |
| Answer accuracy per question | Substring match on `goal`, `partners`, `project`, `actors` |
| Unsupported name rate | Partner/actor answers containing forbidden names or no allowed name |

Fixtures (one per session type): `syn_meeting_playground_candidates.json`, `syn_assembly_garden_candidates.json`, `syn_interview_mobility_candidates.json`.

### No-practice regression

`practice::evaluation::discourse_reference_suite_unchanged_without_practices` asserts live and synthesis discourse prompts match when the practice block is empty. The moderator **eval-discourse** fixture suite runs without practices; re-run it when changing discourse prompts:

```bash theme={null}
cd api/crates/moderator-agent
CONFIG_FILE=../../config.local.yml cargo run --bin eval-discourse -- eval/fixtures/syn_one_card.json
```

Summary prompt byte identity without practices is covered in `api/crates/summarisation/src/summary_prompt.rs` (`empty_practice_block_is_byte_identical`).

## Related docs

* [Summary health evaluation](https://docs.kair.is/platform/summary-evaluation.md) (summary job quality; practice sections are composed at read time)
* [Moderator discourse agent](https://docs.kair.is/platform/moderator-agent.md) (live and synthesis prompts accept practice blocks)
* Shaping spec: `agent-os/specs/2026-09-24-1200-session-practices/shape.md`


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