governed-research

name	governed-research
description	Run one governed strategy research/promotion cycle. Use this whenever the user asks to run autoresearch, improve a strategy config, evaluate a challenger, or do a governed research round. The skill enforces a hard separation between research configs (agents may modify) and promoted configs (require explicit human approval to change).

Governed Research

Run one bounded strategy research cycle for any executor while preserving a hard separation between research configs and promoted configs.

The goal: let agents iterate on configs cheaply within a budget, produce evidence, and propose promotions. Never let an agent silently promote a config that an operator is actually running.

Hard Rules

• Never edit a promoted config (whatever that executor's equivalent of live is). The operator owns those changes.
• Never pass humanDirected: true to governance code from this skill.
• Never start or stop live/running executor processes.
• Never fabricate or impute market data. Missing data is a red gate, not a research opportunity.
• Always use a topic worktree and MQ for repo changes.

What "config" means here

This skill doesn't prescribe a config format. Different executors use different approaches:

• A JSON file with multiple named profiles (research, promoted, etc.)
• Separate JSON files per config
• TypeScript exports
• Env vars selecting a variant

Whatever the executor uses, there are two categories:

Category	Who modifies it	This skill
Research config	Agents (this skill, during research cycles)	May update after governance approval
Promoted config	Humans only (operator decision)	Must not touch

Tell the governance script which config names are "protected" (e.g., ["live", "live-primary", "promoted"]) via the protectedProfiles parameter. If the executor has no protected configs yet, pass an empty array.

Read First

Load only the references needed for the current task:

• references/workflow.md — the end-to-end research cycle
• references/governance-input.md — the JSON artifact consumed by the script
• references/gates.md — how to grade hard gates

Core Command

pnpm tsx .agents/skills/governed-research/scripts/governed-research.ts \
  evaluate <path-to-governance-candidate.json>

The script evaluates:

• Variant Equivalent search cost vs rolling budget (daily/weekly/monthly)
• Hard promotion gates (8 defined gates, extensible)
• The $1 minimum tradable balance rule
• Protected config diffs (if you pass before/after config paths)

If the script fails, stop. Fix the root cause. Do not bypass it.

Standard Cycle

1. Create a topic worktree.
2. Run the user-requested research/scoring loop.
3. Choose at most one finalist.
4. Write a candidate artifact using references/governance-input.md.
5. Run the governance script.
6. If the decision is PROMOTION_PROPOSAL or SHADOW, update only the research config.
7. If the executor tracks protected configs, run the governance script again with --profiles-before and --profiles-after to verify no protected config changed.
8. Run targeted tests and pnpm qa.
9. Commit with /recall-commit.
10. Land with MQ.

Decision Handling

• PROMOTION_PROPOSAL: may update research config. Never update promoted configs.
• SHADOW: may update research config if the user asked for shadow/dry-run operation.
• CHALLENGER_ONLY: save evidence, do not update any config.
• NO_CHANGE: save evidence, do not update any config.
• QUARANTINE: stop and report the failed gate. Do not update any config.

Config Update Procedure (when protected configs exist)

Before editing:

cp <path-to-config> /tmp/config.before.json

After editing only the research portion, validate:

pnpm tsx .agents/skills/governed-research/scripts/governed-research.ts \
  evaluate <governance-candidate.json> \
  --profiles-before /tmp/config.before.json \
  --profiles-after <path-to-config>

The script must pass. If it reports a protected config changed, revert and keep working only on the research portion.

VE Budget

Each config iteration costs Variant Equivalents (VE). The budget prevents unbounded search pressure that leads to overfitting.

Defaults (configurable via the candidate JSON's budget field):

• Daily: 8 VE
• Weekly: 40 VE
• Monthly: 120 VE

Each changed dimension has a base cost. Opening multiple knobs per dimension or touching runtime code paths adds surcharges. See @recallnet/skunk-research-governance's DEFAULT_VARIANT_EQUIVALENT_COSTS for the full pricing table and calculateVariantEquivalentCost() for how surcharges compose.

The 16 built-in change kinds cover common parameter types (thresholds, cooldowns, features, models, sleeves). If your executor's change doesn't fit cleanly, pick the closest kind or file a TradeCore issue to extend the set.

Optional Advanced Features

These gates are defined in the package but you can mark them green without evidence if your executor doesn't use them yet:

• lockbox — held-out data gate; only relevant if the executor maintains a lockbox dataset
• shadow — shadow/live-feed evidence gate; only relevant if there's a shadow runtime pipeline
• segment_stability — regime-specific analysis; only relevant if the executor segments data by regime

Mark irrelevant gates green with a summary like "not applicable — executor has no lockbox data." The script will let them pass; it only blocks on red.

Governance Package

The governance logic lives in @recallnet/skunk-research-governance. It provides pure functions for VE pricing, budget tracking, gate evaluation, decision hurdles, and protected profile guards. The script in this skill is a thin CLI wrapper around the package.

Skill Integrations

• /build-executor — loads this skill during Stage 3 (PROMOTE) for bounded config iteration
• /recall-commit — use for all commits from research cycles

Required Final Report

End with:

• Candidate name and incumbent
• Decision from the governance script
• VE cost and remaining budget
• Gate summary
• Whether the research config changed
• Verification commands run
• Commit SHA and MQ landing status