Skip to content

Iteration Plans

This page documents how short-horizon work (1–2 weeks) is planned in SoccerPredictAI. Plans are explicit, dated, and versioned under docs/planning/.

Status: Operational. Plans are produced from audit-cycle outputs and tracked against the Implementation Status page.

Why explicit plans

The project deliberately separates three things that often get conflated in ML work:

Layer Question it answers Where it lives
Long-term direction What is this project, what is "done"? Requirements, Roadmap
Current reality What is actually wired today? Implementation Status, latest audit cycle
Short-horizon plan What am I doing in the next 1–2 weeks? This page → docs/planning/

Without (3), the gap between (1) and (2) becomes invisible and "in progress" turns into "forever". A dated plan makes the gap finite.

Plan format

Every plan is a single Markdown file with the same structure (the plan-test-coverage skill bundles a template that codifies it):

  • Header — cycle name, target window, source-of-truth links (requirements, roadmap, baseline audit).
  • Phases — Phase 0, Phase A, Phase B, … Each phase has a goal in one sentence and a time budget.
  • Tasks — T1, T2, … inside each phase. Each task has:
    • exact files touched (linked),
    • the action,
    • the verification step (concrete command — pytest …, dvc repro …, manual check),
    • explicit alternatives ruled out.
  • Idempotency rule — when re-running the planning skill, completed tasks are marked ✅ done and not re-listed; only open items + new gaps appear in the new plan.

Conventions

  • One file per plan, named <YYYYMMDD>_<scope>.md (e.g. 20260428_v1.md, 20260428_test.md).
  • Same-scope re-plans add _v2, _v3 suffix.
  • Source of truth links are mandatory — a plan that cannot point to the requirements or audit it descends from is a wishlist, not a plan.
  • Verification steps are mandatory — every task must declare how "done" is checked.

Plans on file

Date Scope File Source-of-truth
2026-04-29 Operator briefing — scope answers start.md Requirements §Project Vision
2026-04-28 v1.0 demo track 20260428_v1.md Requirements §Definition of Done, Roadmap, audit 2026-04-28
2026-04-28 Test coverage remediation (initial) 20260428_test.md Testing Strategy, test-coverage gap analysis
2026-04-28 Test coverage remediation (revised) 20260428_test_v2.md Same-day revision of 20260428_test.md

How a plan is generated

For test-coverage plans the procedure is fully encoded:

/skill-plan-test-coverage

The skill:

  1. Reads the most recent docs/planning/*_test.md (idempotency).
  2. Inventories src/ ↔ tests/ and builds a gap matrix.
  3. Prioritises gaps P0 (blocks signal) → P3 (nice to have).
  4. Emits a phased plan to docs/planning/<YYYYMMDD>_test.md.
  5. Carries forward only open items + newly discovered gaps; completed work is shown as ✅ done.

Other plans (e.g. v1.0 demo track) are written by hand against the same template, since their phasing depends on judgement about which audit findings are blockers for the Definition of Done, not on a mechanical inventory.

Why this matters for the system

A plan is not just personal scheduling — it is the contract between Requirements (what v1.0 means) and the next commit. Each closed task in a plan corresponds to a status flip on Implementation Status, and each plan's "verification" column maps directly to a check the next audit cycle will re-run.

This three-way loop — requirements → plan → audit → status — is what keeps the project honest about the difference between "designed", "in progress", and "done".