Skip to content

Standardize all v1 template READMEs to the canonical structure#95

Draft
cafzal wants to merge 7 commits into
mainfrom
readme-standardization
Draft

Standardize all v1 template READMEs to the canonical structure#95
cafzal wants to merge 7 commits into
mainfrom
readme-standardization

Conversation

@cafzal

@cafzal cafzal commented Jul 1, 2026

Copy link
Copy Markdown
Collaborator

What

Brings all 48 customer-facing v1 template READMEs to the canonical sample-template structure. This is the standardization follow-up to the runbook PR (#93) — that PR intentionally deferred the portfolio-wide README pass, and a /dev-templates-review sweep confirmed most of the portfolio predated the current standard.

Every README now follows the same section order and rules as sample-template/README.md and the exemplar telco_network_recovery:

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 → Support

Per-README transforms

  • Remove the body H1 — the gallery renders the title from front matter.
  • Description — 1–2 plain sentences, acronyms expanded (GNN, MIP, MILP, CSP, MTZ, NGO, ERCOT…), no colon-then-list fragments or symbol shorthand.
  • What this template is for — accessible problem/value statement + one bold reasoning-approach sentence; per-reasoner tours and "why X reasoner over Y" apologetics moved into How it works.
  • What you'll build — outcomes/artifacts (each naming the RAI feature), not imperative steps.
  • Prerequisites — split into ### Access / ### Tools with the relationalai SDK pin.
  • Quickstart — ends with a tiny Expected-output snippet; oversized full printouts trimmed and pointed at the runbook.
  • Template structure — annotated tree + a Start here pointer to the one entrypoint.
  • Model overview — opens with Key entities / Primary identifiers / Important invariants bullets, then one Property | Type | Identifying? | Notes table per concept, built by reading each template's script.
  • Customize this template — the four H3 subheads (### Use your own data / ### Tune parameters / ### Extend the model / ### Scale up / productionize).
  • Learn more + Support — added where missing.

Also fixed (customer-facing bugs surfaced by the review)

  • Broken private.relational.ai download URLs → docs.relational.ai (cell_tower_coverage, financial_index_replication).
  • Zip-name copy-paste mismatches (disease-outbreak-prevention, humanitarian-aid-supply-chain, wildlife-conservation-network).
  • Setup-breaking GRANT typo FAVORITA → FAVORITA_MINI (demand_forecasting).
  • Stray </content></invoke> / tool-markup rendering as literal text (memory_supply_allocation, and two introduced-then-removed during this pass).
  • Stale raiconfig.toml → raiconfig.yaml across 7 READMEs (rai init now emits raiconfig.yaml).
  • entity_resolution chain-summary count 30 → 31 (matches the resolve step).

Verification

  • No runtime numbers changed — objective values, costs, metrics, and expected-output figures are byte-preserved; only excess lines/prose were trimmed and descriptive counts/SDK pins added. Audited via numeric-token diff against the pre-standardization baseline across all 48.
  • Structural conformance re-checked programmatically after a /dev-templates-review verification pass: all 48 domain READMEs have the canonical first heading, section order (Troubleshooting → Learn more → Support), the four Customize H3s, Model-overview lead-in bullets, and a Start-here pointer; no stray markup.
  • README-only: no scripts or runbooks were modified.

Out of scope (unchanged): the 5 utility / data-generation READMEs (rai-agent-scaffold, simple-start, synthetic_eligibility_records, synthetic_order_lifecycle, test_data_generation), and the ~12 README-vs-script numeric reconciliations that need per-script reruns (tracked separately).

Note on stacking

This branch is stacked on the small raiconfig/entity-resolution fix in #94, so this PR's diff currently includes that commit. Merge #94 first and it drops out, or merge this PR and close #94 as superseded.

cafzal added 7 commits July 1, 2026 14:35
@cafzal
Fix stale raiconfig.toml references and an entity_resolution count
c4c8170 
- 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.
@cafzal
Standardize READMEs to canonical structure (batch 1/8)
a8f5b10 
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.
@cafzal
Standardize READMEs to canonical structure (batches 2-4/8)
1f92a24 
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.
@cafzal
Standardize READMEs to canonical structure (batches 5-8/8)
1545fab 
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.
@cafzal
wildlife README: restore dataset counts (12 orgs, 19 partnerships) in…
321ee65 
… Sample data
@cafzal
Strip stray tool-markup tags from two standardized READMEs
2214186 
cell_tower_coverage and cicd_runner_allocation had </content></invoke>
appended at EOF during the standardization write; remove them.
@cafzal
README standardization: close conformance-pass gaps
b7f3b53 
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.
@cafzal cafzal marked this pull request as draft July 1, 2026 22:19
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@somacdivad somacdivad Awaiting requested review from somacdivad somacdivad is a code owner
@jablonskidev jablonskidev Awaiting requested review from jablonskidev jablonskidev is a code owner

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@cafzal