control-loop — the router that learns

Package scope and prerequisites

This catalog ships instructions, not the executable runtime. Python modules, scripts, local services and optional tools named below must be installed separately from the upstream project. Check their availability before running commands; if they are missing, explain the prerequisite instead of claiming execution or results. The host agent may use model tokens while following these instructions.

Commands, APIs and runtime behavior described below are conditional examples for a compatible upstream installation; they are not evidence of execution in this package.

The final systemic loop: every routing decision + outcome is recorded, and the effort→tier thresholds (read live by [[auto-router]]) are nudged from the data — keep more work local when local is reliable, escalate sooner when it isn't.

python -m skills.control_loop.cli analyze            # local %, savings, escalation/success
python -m skills.control_loop.cli adapt              # proposed threshold change + why
python -m skills.control_loop.cli adapt --apply      # write it; the router uses it next time
python -m skills.control_loop.cli reset              # back to defaults

How the loop closes

1. Measure — auto_router.run records each call to ~/.botte/control-ledger.jsonl (effort, tier, local/cloud, tokens saved, escalated, success).
2. Analyze — aggregate: local %, escalation rate, success rate, tokens saved.
3. Adapt — conservative rule, needs ≥10 samples, small steps, clamped:
   • local reliable (success ≥85%, escalation <15%) → raise the LOCAL boundary (consider more work for local execution).
   • local insufficient (escalation >30%) → lower it (escalate borderline sooner).
4. Apply — write ~/.botte/routing-thresholds.json; auto_router.effort reads it live, so the next decisions reflect what actually worked.

This is an outcome-based routing adaptation pattern. A threshold change is a proposal, not proof of improved quality or savings; compare subsequent verified outcomes before retaining it. Exposed via [[llm-mcp]] as routing_stats. Related: [[auto-router]], [[conductor]], [[metrics]].