model-code-analyzer

Purpose

Define exactly what code must implement and save. Do not expand the approved experiment scope or fully plan a dormant fallback.

Preconditions

• methods/Qx/qx_method_card.md and probe summary exist.
• methods/Qx/qx_decisions.jsonl contains a human DECIDED method choice.
• A usable baseline is identified.
• Cleaned data and data_profile.json are ready when data is required.
• Implementation target and round are known.

Read legacy candidate/decision artifacts only when the new artifacts are absent.

Workflow

1. Read the approved choice, method card, probe conditions, and experiment budget.
2. Plan only:
   • approved main;
   • approved usable_baseline;
   • shared helpers and comparison logic.
3. Record the fallback ID and trigger, but do not plan its full implementation unless the trigger is already evidenced and the human chose activation.
4. Map mathematical definitions to inputs, processing steps, intermediate evidence, outputs, and validation checks.
5. Define a directly comparable metric/output contract for main and baseline.
6. Define the round output:

results/Qx/experiments/roundN/
├── figures/
├── tables/
├── metrics/
└── run_summary.json

Create logs/ only for failures, warnings, or reproducibility needs. 7. Write code/Qx/qx_code_plan.md for Python or code/matlab/Qx/qx_code_plan.md for MATLAB. 8. Hand off to the matching language generator.

Run Summary Contract

Require:

{
  "schema_version": 1,
  "question": "Q1",
  "round": "round1",
  "implementation_target": "python",
  "random_seed": 2026,
  "approved_decision_id": "q1_method_choice",
  "methods": [
    {
      "method_id": "M1",
      "role": "usable_baseline",
      "script": "code/Q1/q1_baseline.py",
      "status": "success",
      "execution_time_seconds": 0,
      "input_files": [],
      "output_files": [],
      "figure_files": [],
      "metrics_summary": {},
      "warnings": [],
      "errors": []
    }
  ],
  "comparison": {},
  "fallback_trigger": {
    "fallback_id": null,
    "condition": null,
    "observed": false,
    "evidence": null
  },
  "environment": {}
}