docs(repo): add 5 batch-runner INITIAL docs

[w7-mgfcode]

Closes #277.

Adds the batch-runner MVP INITIAL plus the 4 downstream INITIALs that depend on it:

• PRPs/INITIAL/INITIAL-batch-runner-mvp.md (493 lines) — the unblocker
• PRPs/INITIAL/INITIAL-batch-champion-and-heatmap.md (418 lines)
• PRPs/INITIAL/INITIAL-batch-export-and-retry.md (768 lines)
• PRPs/INITIAL/INITIAL-batch-parallel-execution.md (479 lines)
• PRPs/INITIAL/INITIAL-batch-priority-queue.md (405 lines)

The MVP's Cross-Slice Coordination Matrix pins the contract every downstream PRP reads against:

• batch_job_item.metrics JSONB shape: exactly `{wape, smape, mae, bias, sample_size}`
• MVP migration ships: `batch_job_item.metrics`, `batch_job_item.priority`, the partial picker index `ix_batch_job_item_picker WHERE (status = 'pending')`, and `batch_job.{max_parallel, running_items, cancelled_items, default_child_priority}`
• MVP migration defers (to each downstream's own forward-only migration): `attempts`, `last_attempt_at`, `parent_item_id`, `is_champion`, `priority_updated_at`, `priority_history`, `max_attempts`, `champion_summary`
• Runner uses `FOR UPDATE SKIP LOCKED` (no-op single-worker today; load-bearing for parallel/priority later)
• Cross-slice calls use lazy in-method imports (precedent: `app/features/forecasting/service.py`)

Test plan

• All 5 files are net-new (5 `A` entries in `git status`)
• MVP doc stays ≤ 500 lines (493 lines — sanity-checked before commit)
• Commit format passes `.claude/hooks/check-commit-format.sh` (scope: `repo` — these are cross-cutting planning artifacts per the `commit-format.md` "Scope exception" rule)
• CI gates green: Lint & Format, Type Check, Test, Migration Check (docs-only — should pass trivially)

Next

After merge, the MVP PRP gets generated via `base_prp:prp-create` against the MVP INITIAL. The 4 downstream PRPs are blocked on the MVP PRP merging — they need its merged column types as ground truth.

[sourcery-ai]

Sorry @w7-mgfcode, your pull request is larger than the review limit of 150000 diff characters

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 0264b541-4ad0-40b4-acb8-8f8d44046bf6

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/batch-initial-docs

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}