Show & Tell: Phase 16.3 — ImprovementPlanner architecture (rule table, priority formula, safety gate)

[web3guru888]

Phase 16.3 — ImprovementPlanner: turning ranked weaknesses into actionable improvement plans

Issue: #423 | Depends on: #420 (WeaknessDetector) | Feeds: Phase 16.4 SelfOptimiser

---

The gap ImprovementPlanner fills

WeaknessDetector tells you what is degraded and how badly. ImprovementPlanner tells you what to do about it. It is the bridge between diagnostic signal and executable change.

PerformanceProfiler
       |  ModuleProfile stream
       v
WeaknessDetector --> ranked WeaknessReport[]
                                |
                     ImprovementPlanner  <---- SafetyFilter (Phase 11)
                                |
                     ImprovementAction[]  (priority-sorted, safety-gated)
                                |
                       SelfOptimiser (Phase 16.4)

---

ActionKind — the six interventions

ActionKind	When used	Cost
TUNE_THRESHOLD	Detector/profiler param too aggressive	0.05
INCREASE_BUDGET	Module running over time/memory budget	0.30
REDUCE_LOAD	Module overloaded, can shed non-critical tasks	0.20
HOT_SWAP_MODULE	Module fundamentally underperforming	0.70
FLAG_FOR_REVIEW	Safety constraint, or composite degradation	0.01
NO_OP	Weakness acknowledged but no safe action available	0.00

---

Priority formula

urgency  = severity x confidence           # both in [0, 1]
priority = urgency - cost_weight x cost    # default cost_weight = 0.3
priority = clamp(priority, 0.0, 1.0)

Example with severity=0.9, confidence=0.95 (urgency=0.855):

Action	Cost	Priority
TUNE_THRESHOLD	0.05	0.840
REDUCE_LOAD	0.20	0.795
INCREASE_BUDGET	0.30	0.765
HOT_SWAP_MODULE	0.70	0.645

Low-cost actions float to the top — the planner prefers cheap fixes unless urgency is extreme.

---

Rule table: WeaknessKind to ActionKind

HIGH_LATENCY    -> HOT_SWAP_MODULE, INCREASE_BUDGET
HIGH_ERROR_RATE -> HOT_SWAP_MODULE, FLAG_FOR_REVIEW
LOW_THROUGHPUT  -> REDUCE_LOAD, TUNE_THRESHOLD
LATENCY_SPIKE   -> INCREASE_BUDGET, TUNE_THRESHOLD
DEGRADED        -> FLAG_FOR_REVIEW, HOT_SWAP_MODULE

---

Safety gate

Before emitting any action, RuleBasedPlanner optionally calls safety_filter.is_safe(action). If the filter rejects it, _downgrade() replaces the action kind with FLAG_FOR_REVIEW:

HOT_SWAP_MODULE --[safety blocks]--> FLAG_FOR_REVIEW
  priority=0.645                       priority=0.645
  cost=0.70                            cost=0.01
  rationale="[safety-gated] ..."

This keeps the safety gate non-lossy: the operator still sees the intent, just escalated rather than auto-executed.

---

ImprovementAction frozen dataclass

parameters uses a tuple of 2-tuples (not a dict) so the dataclass remains hashable. Convert with dict(action.parameters) when reading.

---

Prometheus metrics + PromQL

# Alert: planner emitting high fraction of safety-gated actions
rate(asi_planner_actions_gated_total[5m])
  / rate(asi_planner_actions_planned_total[5m]) > 0.5

# Alert: planner taking too long
histogram_quantile(0.99, rate(asi_planner_plan_duration_seconds_bucket[5m])) > 0.1

---

Open questions for contributors

1. Learning rule weights — should _RULES be static, or learned from past SelfOptimiser outcomes?
2. Multi-module batching — global cap or per-module cap when many modules are degraded simultaneously?
3. Rollback awareness — should ImprovementPlanner consult VersionManager (Phase 15.4 — VersionManager: module version lineage, rollback targeting & compatibility assessment #410) to check whether a rollback is cheaper than a hot-swap?