| name | inventory-readiness-provider-dispatch |
| description | Build and operate a computable readiness matrix that connects raw-data-to-GTM package stages with Codex/Codex/Gemini dispatch lanes and weekly credit pacing. |
| version | 1.0.0 |
| category | ai |
| type | workflow |
| tags | ["provider-routing","inventory-readiness","github-issues","quota-management","llm-wiki","gtm"] |
| related_skills | ["agent-usage-optimizer","gh-work-execution","multi-provider-adversarial-review"] |
Inventory Readiness Provider Dispatch
Use this when the user wants to optimize Codex/Codex/Gemini usage around a staged GitHub work pipeline, especially:
raw data -> inventory -> llm-wiki -> calculation code -> parametric outputs -> website/GTM
The key lesson: do not rely only on narrative backlog notes or a provider work queue. Create a machine-readable readiness matrix that makes package stage status, evidence, downstream issue refs, and provider dispatch lanes computable.
Canonical Workspace-Hub Pattern
For workspace-hub, the implemented pattern from #2487 is:
- canonical matrix:
config/knowledge/inventory-readiness.yaml
- validator/renderer:
scripts/knowledge/validate_inventory_readiness.py
- derived report:
docs/reports/inventory-readiness-matrix-YYYY-MM-DD.md
- targeted tests:
tests/knowledge/test_inventory_readiness.py
The Markdown report should be generated from YAML, not hand-authored as the source of truth.
Required Workflow Gate
All packages surfaced by the matrix must follow:
plan -> adversarial plan review -> user approval -> implementation -> adversarial implementation review -> closeout
Do not execute downstream issue candidates just because they appear in the matrix. Keep them as references/candidates/dependencies unless explicitly approved for execution.
Provider Fit
- Gemini: raw data discovery, source inventory, standards/competitor/GTM scouting, gap discovery.
- Codex: plan synthesis, adversarial plan review, governance/architecture decisions, implementation review.
- Codex: calculation code, validators, tests, CI fixes, bounded implementation/refactors, deterministic report generation.
Avoid burning Codex on mechanical coding when Codex has credits and the task is bounded.
Weekly Credit Pacing Policy
Goal: keep long-running provider-ready packages staged ahead of time so work can execute continuously while credits are available.
- Target about 90% weekly usage by day 5.
- Preserve about 10% for the final 2 days.
- Apply this only when quota telemetry is sufficient.
- If telemetry is weak, route directionally using the provider scorecard plus the readiness matrix, and state confidence limits.
Matrix Contents
Each package family should include:
- package/stage names for the full pipeline
- readiness status per stage, e.g.
READY, PARTIAL, BLOCKED, MISSING, STALE
- evidence for every non-ready stage
- downstream issue references with role/approval state
- provider dispatch lanes for Codex/Gemini/Codex
- dependency issues needed to make the lane executable
- explicit boundary text for downstream/reference-only work
Validation Rules Learned from #2487
Add regression tests and validator rules for these pitfalls:
- Blocked/partial/missing/stale evidence must be explicit in the rendered report. A plain status label is not enough for dispatch.
- Dispatch
dependency_issues must mirror all actionable/non-reference issue refs in stage evidence. Otherwise valid downstream work silently disappears from provider queues.
- Reference-only issues should be allowed in evidence but excluded from actionable dependency-mirror requirements.
- Provider queue counts should be labeled as observed values, not acceptance thresholds, because utilization snapshots age quickly.
- Downstream issues must remain references/candidates/dependencies unless the current approved scope explicitly includes execution.
TDD Implementation Checklist
- Verify issue gate and approval state before coding.
- Write failing tests first for schema, allowed statuses, required stages, provider lanes, downstream refs, CLI behavior, report content, and evidence requirements.
- Implement the minimal validator/config/report needed to pass tests.
- Add negative tests for missing evidence and missing dispatch dependency mirrors.
- Render the report deterministically.
- Run targeted tests and validator commands.
- Run adversarial implementation review before closeout.
- Commit generated source/config/report/review artifacts together.
- Post closeout evidence and close only after validation + review pass.
Useful Commands
uv run pytest tests/knowledge/test_inventory_readiness.py -q
uv run python scripts/knowledge/validate_inventory_readiness.py \
--config config/knowledge/inventory-readiness.yaml \
--validate-only
uv run python scripts/knowledge/validate_inventory_readiness.py \
--config config/knowledge/inventory-readiness.yaml \
--output docs/reports/inventory-readiness-matrix-$(date +%F).md
uv run python -m py_compile scripts/knowledge/validate_inventory_readiness.py
Closeout Evidence
Before closing, capture:
- test result count
- validator pass output
- report render output
- py_compile pass
- adversarial implementation review verdicts
- commit hash
- GitHub closeout comment URL
