Standardize all v1 template READMEs to the canonical structure#95
Merged
Conversation
- raiconfig.toml -> raiconfig.yaml across 7 READMEs (rai init now emits raiconfig.yaml; the .toml name was stale). - entity_resolution runbook: chain summary said the pipeline resolves 51 records into 30 parties, but STAGE 1 and the resolve step both report 31 auto-resolved (30 true people plus one review-band split); fix the summary to 31 to match.
ad_spend_allocation, bom-reachability, book_slate_recommendation, campaign_roi, cell_tower_coverage, cicd_runner_allocation. Bring each README to the sample-template structure: remove body H1; plain-sentence description with acronyms expanded; business-framed 'What this template is for' with one bold reasoning sentence; outcome- based 'What you'll build'; Access/Tools prerequisites; trimmed Quickstart expected-output; annotated structure tree + Start here; Sample data; Model overview (Key entities/identifiers/invariants + per-concept tables built from the script); H3 Customize subheads; Learn more + Support. No runtime numbers or runbooks/scripts changed.
commercial_underwriting, cybersecurity-attack-paths, datacenter_compute_allocation, defect_root_cause, demand_forecasting, demand_planning_temporal, diet, disease-outbreak-prevention, energy_grid_planning, entity_resolution, factory_production, financial_index_replication, fraud-detection, hospital_staffing, humanitarian-aid-supply-chain, it-dependency-mapping, memory_supply_allocation, money_laundering_motif_detection, network_flow_planning, patient_cohort_recruitment, planogram_optimization. Same canonical pass as batch 1 (remove body H1; plain description with acronyms expanded; business-framed intro + one bold reasoning sentence; outcome-based What you'll build; Access/Tools; trimmed Quickstart output; annotated tree + Start here; Sample data; Model overview from the script; H3 Customize; Learn more + Support). Compress reasoner apologetics into How it works. No runtime numbers, runbooks, or scripts changed.
pod_placement, portfolio_balancing, product_configurator, production_planning, retail_markdown, retail_planning, shift_assignment, shipment_compliance, smoker_status_prediction, sprint_scheduling, subscriber_retention, supplier_reliability, supply_chain_resilience, supply_chain_transport, telco_network_recovery, transaction_screening_local, traveling_salesman, underwriting_audit, warehouse_allocation, water_allocation, wildlife-conservation-network. Completes the canonical README pass across all 48 v1 templates. Same transforms as prior batches (H1 removal, plain description, business intro + one bold reasoning sentence, outcome What you'll build, Access/Tools, trimmed Quickstart output, Start here, Sample data, Model overview from the script, H3 Customize, Learn more + Support), plus: normalize British->American spelling (pod_placement), cut tag sprawl (portfolio_balancing), fix loop->single-solve wording (production_planning, verified from the script). No runtime numbers, runbooks, or scripts changed.
cell_tower_coverage and cicd_runner_allocation had </content></invoke> appended at EOF during the standardization write; remove them.
Post-standardization verification (re-running dev-templates-review + sample-template) surfaced residual gaps; fixed here: - Add missing Model-overview lead-in bullets (Key entities / Primary identifiers / Important invariants) and per-concept tables where a template had prose-only overviews (commercial_underwriting, defect_root_cause, retail_planning, subscriber_retention). - Add missing '### Scale up / productionize' Customize subhead; rename '### Tune the model' -> '### Tune parameters' (smoker_status_prediction). - Convert remaining bold-label Customize sections to H3 subheads (subscriber_retention). - Add missing 'Start here' pointer (demand_forecasting); reorder to Troubleshooting -> Learn more -> Support (patient_cohort_recruitment, traveling_salesman); Support last (demand_forecasting). - Add 'Identifying?' column to concept tables missing it (retail_planning, smoker_status_prediction, entity_resolution). - Tighten over-long / colon-list / jargon descriptions (energy_grid, book_slate, memory_supply_allocation, money_laundering, patient_cohort, traveling_salesman, underwriting_audit); expand acronyms. - Trim oversized Quickstart expected-output blocks (datacenter, supply_chain_resilience, fraud-detection, warehouse_allocation, water_allocation, underwriting_audit). - Remove reasoner apologetics from 'What this template is for' (water_allocation, wildlife); restructure flat 'What's included'. No runtime numbers, runbooks, or scripts changed.
…ates - datacenter_compute_allocation: troubleshooting said time_limit_sec=120 but the script's SOLVER_TIME_LIMIT_SEC is 240; correct the prose. - book_slate_recommendation, datacenter_compute_allocation, planogram_optimization: private: true -> false so these customer v1 templates publish to the gallery.
Ran each shipped script on Snowflake; the runbooks were correct and the README 'Expected output' blocks were stale. Updated to the real output: - diet: $35.49 total across the 0.8/1.0/1.2 demand scenarios (single solve; basket hamburger + icecream + milk), was $6.53/$8.20/$9.87. - supply_chain_transport: $1444.00, both groups ship LTL on day 2, zero TL trucks, was $5080.00 / TL. - production_planning: $44,735 single-solve over three demand scenarios, was the stale 14650/15950/16800 three-separate-solves loop output. - retail_markdown: $23,374.65, was $18,432.50; trimmed to a tiny snippet.
- hospital_staffing: best-service overtime is $1,728 (real epsilon-sweep run), not $1,116; last marginal $64.25/patient, not $36.00. - demand_planning_temporal: January horizon is 14 weeks (not 13) in the How-it-works note; clarify that cost rises with the horizon as holding cost (demand is met from opening inventory, zero production) rather than from more demand orders. Expected-output costs already matched the run. - shift_assignment: verified — already documents that the feasibility-CSP roster varies run to run; no change.
…hes script) The shipped script prints raw eigenvector centrality (S004=0.5016, S006=0.3895, S003=0.3688); the runbook had normalized-to-1.0 values (1.000/0.776/0.735). Align the runbook to the raw values the script surfaces (README already uses them). Cost figures ($1,865 baseline, +88.5% on S004-offline) already matched the real run. energy_grid_planning verified against its run (qualitative centrality ranking + $300M knee) with no change needed.
- retail_planning: markdown 62,038.94 and demand-planning 8,761.30 (the seeded local run, matching the runbook), was 62,096.89 / 8,985.53. - fraud-detection: add a GNN-variance caveat (GPU training isn't bit-reproducible even seeded; a rerun gave 117.3M captured vs the documented 111.8M); the MILP-over-naive uplift is the stable result. Note the runbook covers the full-PaySim Snowflake run at larger scale.
Post-change dev-templates-review verification caught two READMEs whose documented relationalai pin lagged the pyproject pin: shipment_compliance (Tools line) and synthetic_order_lifecycle (Tools line + two troubleshooting references).
Reframe the README as a compelling overview and table of contents that links out, rather than a mirror of the script and runbook. Net -2,920 lines across the portfolio. - Model overview: keep the Key entities / Primary identifiers / Important invariants bullets, drop the per-concept property tables (they restated the script's declarations), and point to the script for full definitions and runbook.md for how they're built. - How it works: plain-language walkthrough of the chain; remove verbatim script code (kept at most one text flow diagram), pointing to the script and runbook instead. - Runbook prominence: a **Runbook** bullet in What's included and a dual Start-here (script for the end-to-end run, runbook.md for the skill-driven step-by-step reproduction) — equal billing with the script. - sample-template updated to this shape as the canonical reference. No runtime numbers changed; Quickstart expected-output snippets intact.
The lean pass had reduced some Model-overview Key-entities bullets to bare concept-name lists, dropping the one-line 'what it represents' context a new reader needs to orient to the domain. Re-add a concise domain phrase per concept (recovered from the pre-lean descriptions), kept to a single bullet — no property tables. Workflow narrative was already preserved in the How-it-works prose.
cafzal
added a commit
that referenced
this pull request
Jul 6, 2026
The README standardization (#95) rewrote most template descriptions but merged before the index regen, leaving the v1 per-version index and the root README template index stale. Regenerate so the Verify version indexes CI passes on main.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Reshapes all 48 customer-facing v1 template READMEs into a compelling overview + navigation hub — a map that anchors the reader and links out to the script and the runbook — and reconciles every documented number to a real shipped-script run. Follow-up to the runbook PR (#93); a
/dev-templates-reviewsweep confirmed most of the portfolio predated the current standard.Net effect: −2,920 lines of README across the portfolio — the previously-bloated multi-reasoner templates shrank the most (portfolio_balancing −296, supply_chain_resilience −272, datacenter −207, energy_grid −201) while every template gained the missing canonical sections.
Every README now follows
sample-template's section order:What this template is for → Who this is for → What you'll build → What's included → Prerequisites (### Access / ### Tools) → Quickstart (ending in a small Expected-output snippet) → Template structure (annotated tree + **Start here**) → Sample data → Model overview → How it works → Customize this template → Troubleshooting → Learn more → SupportThe README is an overview, not a mirror of the script/runbook
runbook.md(how they're built). The per-concept property tables were dropped — they restated the script and were the single biggest source of bloat.runbook.mdfor the step-by-step reproduction with the RAI skills).Other per-README transforms
### Access/### Toolswith therelationalaiSDK pin (aligned to each pyproject).Numbers reconciled to real runs (no simulation)
Every flagged README-vs-script / README-vs-runbook figure conflict was resolved by running the shipped script on Snowflake and matching the docs to the real output:
Also fixed (customer-facing bugs)
private.relational.aidownload URLs →docs.relational.ai.FAVORITA→FAVORITA_MINI(demand_forecasting).</content></invoke>tool-markup (memory, cell_tower, cicd).raiconfig.toml→raiconfig.yaml(7 READMEs).time_limit_secprose → 240; SDK-pin drift (shipment_compliance, synthetic_order_lifecycle → 1.13.0).private: true(book_slate, datacenter, planogram).Verification
/dev-templates-reviewpass — all 48 domain READMEs pass (first heading, section order, four Customize H3s, Model-overview bullets, Start-here + runbook); 0 per-concept property tables remain; no stray markup; no leftover run artifacts.dev-templates-reviewchecklist andsample-templatewere updated to define this lean-overview shape.Out of scope (unchanged): the 5 utility / data-generation READMEs.
Note on stacking
Stacked on the raiconfig/entity-resolution fix in #94; merge #94 first (it drops out) or merge this and close #94 as superseded.