Adding a Methodology

A methodology is a reusable investment rule that can be evaluated independently of the conversation or playbook that produced it. It may describe a signal, a threshold, an expected direction, a time horizon, and the conditions where the rule should not apply.

Minara has two sources of methodologies:

• Authored seeds in apps/agent/src/learning/methodology-seeds.ts provide a reviewed starting corpus.
• Learned candidates come from evaluated decisions and trading cases. They begin in quarantine and must earn enough evidence before they can surface.

Apply the independence test

Place the rule alone in a prompt such as “analyze the trend in NVDA.” If it still has a clear meaning, required evidence, and failure condition, it can be a methodology. If it refers to “the previous step,” a role, a Roundtable phase, or another active rule, keep it in the analysis playbook.

Good:

When free-cash-flow conversion stays below 70% for two reporting periods while receivables grow faster than revenue, treat earnings quality as deteriorating.

Too dependent on context:

After the analyst completes step 3, use the result above to reduce the rating.

Add an authored seed

Add a focused entry to METHODOLOGY_SEEDS:

{
  stableId: "stock.earnings_quality.cash_conversion.v1",
  version: "v1",
  source: "authored",
  asset_class: "stock",
  methodology:
    "When free-cash-flow conversion stays below 70% for two reporting periods " +
    "while receivables grow faster than revenue, treat earnings quality as deteriorating.",
  thresholds: { fcf_conversion_floor_pct: 70 },
  anti_patterns: [
    "Do not apply to pre-revenue companies.",
    "Skip periods distorted by a disclosed acquisition close.",
  ],
  applies_only_to: ["stock"],
  benchmark_profile: "asset_benchmark",
},

Do not seed a rule simply because it sounds plausible. Explain its rationale and expected evidence in the pull request. A rule derived from a paper or public dataset must preserve the citation and license context.

Understand the lifecycle

Authored seeds enter through the trusted bundled-seed source. Untrusted learned or imported entries start with confidence 0.1 in quarantine. A candidate graduates only after at least 10 observations, at least 5 correct observations, and a Wilson lower bound of at least 0.55. A graduated rule returns to quarantine when its Wilson score falls below 0.40 after at least 20 uses.

Only graduated methodologies reach the Agent through methodology_lookup or {{methodology:...}} placeholders. A placeholder always carries a safe default. Operators can disable reads, case recording, or all mutations independently through the methodology safety preferences and fallback environment switches.

Every change to confidence, counters, or quarantine state must use the methodology repository lifecycle contract. Direct SQL updates lose the atomic lifecycle event and are not acceptable.

Verify the contribution

pnpm --filter @minara/agent lint:methodology
pnpm --filter @minara/agent exec vitest run tests/unit/learning/methodology-seeds-lint.test.ts
pnpm --filter @minara/agent exec vitest run tests/unit/learning/methodology-store.test.ts
pnpm --filter @minara/agent typecheck

If you add a placeholder to an Institution playbook, test the fallback and the store-backed override. If the rule changes public behavior, update the relevant analysis documentation in all four languages.

Operators can inspect the live system without editing SQLite:

minara learning methodology explain <id>
minara learning methodology lifecycle --id <id>
minara learning methodology cases --id <id>