Adding an Analysis Playbook

Minara retired the standalone Scenario Registry in May 2026. Do not create SCENARIO_* definition files, edit a scenario catalog, or add SCENARIO_LEARNING flags. User-intent routing now belongs to Skills. The remaining analysis playbooks serve Institution Mode and Deep Research directly.

Choose the correct surface

Add an Institution playbook

An Institution playbook supplies the analytical substance for one or more roles. Give it a stable namespaced ID such as institution.playbook.stock_quality and add it to INSTITUTION_PLAYBOOKS.

"institution.playbook.stock_quality": {
  id: "institution.playbook.stock_quality",
  description: "Evaluate earnings quality, reinvestment, and balance-sheet resilience.",
  body: `1. Verify the latest filing period and data freshness.
2. Compare cash conversion, margins, and invested-capital returns.
3. Identify the strongest disconfirming evidence.
4. State the conditions that would invalidate the conclusion.`,
},

Keep each body self-contained. Name the required evidence, state how conflicting evidence changes the conclusion, and define failure behavior when live data is unavailable. Do not duplicate universal safety, citation, or language rules from the system prompt.

Map the ID in apps/agent/src/tools/institution/roles.ts only when a built-in role should receive it by default. Asset-specific mappings belong in playbookIdsForRole(). The test suite verifies that every referenced ID resolves.

Tunable values use a methodology placeholder with a safe fallback:

Treat beta above `{{methodology:stock_beta_high_corr_threshold|default:0.8}}`
as market-sensitive.

Do not bury a reusable investment rule inside a long playbook. Move it to the methodology store, then reference it through a placeholder or methodology_lookup.

Add a built-in Roundtable template

The Roundtable Builder supports five phase types: context, parallel, debate, synthesis, and final. Built-in Agent, phase, and full Roundtable templates live in builder-templates.ts; their shared types come from @minara/types.

The validator enforces these invariants:

• phase and Agent IDs are unique across the pipeline;
• a debate phase contains at least two Agents;
• synthesis and final phases contain exactly one manager;
• the pipeline contains exactly one final phase, and it is last;
• loop, tool-call, timeout, and output-token limits stay within the declared bounds.

A template change updates Agent tests and the Web UI builder tests. User-created templates are persisted through the builder store and do not belong in source control.

Extend Deep Research

Deep Research keeps its six-step outer contract in deep-research/SKILL.md. Add topic-specific collection and analysis guidance to references/scenarios.md. Keep the reference focused on source selection, evidence quality, comparison logic, and the shape of the final synthesis.

If the playbook requires a new capability, add and test the Tool first, expose it through the Skill's tool_names, then update the reference. A playbook must degrade honestly when a source or credential is unavailable.

Verify the contribution

pnpm --filter @minara/agent exec vitest run tests/unit/tools/institution.test.ts
pnpm --filter @minara/agent exec vitest run tests/unit/tools/institution-builder.test.ts
pnpm --filter @minara/agent typecheck

For a Deep Research change, also run its focused Skill and report-flow tests. If the change affects public behavior, update the matching Institution Mode or Deep Research documentation in all four languages.