# Intelligence — Methodology Library

The methodology library is **the architectural mechanism for SME
knowledge to enter the BID framework** (Pillar 2 spec §SME
Methodology Library). SMEs encode their expertise as structured YAML
entries; Intelligence agents read those entries at runtime and apply
them. Adding analytical capability to the framework means adding
methodology files — no agent code has to change.

## Directory layout

```
src/intelligence/methodologies/
  README.md                              ← this file
  banking/
    tech_opex_efficiency_banking.yaml
    [other banking-specific methodologies]
  wealth_management/
    [populated as SMEs contribute]
  insurance/
    [populated as SMEs contribute]
  cross_domain/
    peer_benchmark_three_year_growth.yaml
    [other cross-domain methodologies]
```

The loader scans every `*.yaml` file under this directory, indexes
them by `methodology_id`, `type`, and `domain`, and exposes them
through `src/intelligence/library.ts`. Agents query the library
through the Anthropic-tool surface in `src/intelligence/tools.ts`.

## Entry format

Every methodology has at minimum:

```yaml
methodology_id:   <unique snake_case identifier>
name:             <human-readable name>
type:             metric_definition | comparison_method | insight_framework | normalization_rule
domain:           <banking | wealth_management | insurance | all | ...>

applies_to:
  agent:          <which Intelligence agent uses this>
  triggers:       <conditions under which the agent selects this methodology>

definition:
  <the methodology itself — formula, comparison rule, insight rule, etc.>

inputs:
  - <data inputs the methodology needs>

outputs:
  - <what the methodology produces>

rationale: |
  <why this methodology exists, when to use it, when not to>

declared_by:    <SME name or team>
declared_date:  <YYYY-MM-DD>
last_reviewed:  <YYYY-MM-DD>
status:         active | deprecated | under_review
```

See `banking/tech_opex_efficiency_banking.yaml` and
`cross_domain/peer_benchmark_three_year_growth.yaml` for full
examples.

## How methodologies get added

1. **Direct encoding.** SME writes a `.yaml` file and PRs it into the
   library. Reviewed before merge.
2. **Escalation-driven.** An Intelligence agent escalates a
   missing-methodology case (Std 9). The SME's resolution either
   becomes a permanent library entry or one-time guidance for this
   run.
3. **Periodic review.** SMEs review the library at intervals;
   outdated entries get marked `deprecated`.

## What agents do with this

At runtime an Intelligence agent:

1. Identifies the analytical operation it needs (compute metric X,
   compare entities A vs. B, generate insight on Y).
2. Queries the library via the `find_methodologies` /
   `get_methodology` tools.
3. Selects the best-matching active methodology by `domain`,
   `type`, and trigger match.
4. Applies it.
5. Records the `methodology_id` in the audit trail.

If nothing matches, the agent escalates per Std 9 — never improvises.