docs/iteration_plan.md

SupplyMind Iteration Plan

This document captures the next disciplined improvement loop for SupplyMind.

Iteration Principles

1. Change one thing at a time.
2. Evaluate on fixed train seeds and held-out eval seeds.
3. Judge progress by both score and behavior.
4. Keep the environment black-box from the agent's perspective.

Seed Discipline

Use small repeated seed sets instead of one-off runs.

Suggested split:

• train seeds: 1, 2, 3
• eval seeds: 101, 102, 103

Use the same seeds before and after each change.

Curriculum

Run experiments in this order:

• cooperative_restock for API and policy sanity
• scarcity_negotiation for strategy formation
• crisis_coalition for dynamic robustness

The goal is not to learn only on the hardest task.

Iteration 1: Better End-of-Run Learning Signal

Hypothesis:

• Agents need a clearer terminal summary to improve across repeated episodes.

Success criteria:

• agents can explain what caused score loss
• policy revisions become more targeted

Candidate additions:

• reward lost to stockouts
• reward lost to transfer friction
• invalid inventory proposals
• missed coalition opportunities

Iteration 2: Reduce Passive Stock Hoarding

Hypothesis:

• repeated no-transfer decisions can be too attractive when transfer friction is high.

Success criteria:

• agents stop gaining from passive stock hoarding
• strategic reserve holding remains viable

Candidate changes:

• track avoidable stockouts when surplus exists elsewhere
• penalize only when a feasible coalition transfer was available
• keep reserve behavior legal when future demand risk is plausible

Iteration 3: Make Medium/Hard More Distinct Strategically

Hypothesis:

• scarcity_negotiation and crisis_coalition should differ not only in pressure, but in the kind of planning they demand.

Success criteria:

• medium rewards truthful scarcity management
• hard rewards coalition formation under demand shocks and transfer friction

Candidate changes:

• keep scarcity_negotiation steady but inventory-constrained
• make crisis_coalition reward anticipation of late premium demand more strongly

Evaluation Protocol

For each iteration:

1. Run baseline and target on train/eval seeds.
2. Run one black-box agent with the prompt in docs/agent_eval_prompt.md.
3. Compare:

• cumulative reward
• stockout rate
• transfer friction cost
• invalid proposals
• qualitative strategy

Keep the change only if both behavior and metrics improve.