christian/helmdocs-proposal-system
1
0
Fork 0
Code Issues 8 Pull Requests Actions Packages Projects Releases Wiki Activity

Collect real retail RFPs and vendor responses #22

New Issue
Closed
opened 2026-08-02 03:05:55 +00:00 by christian · 1 comment
christian commented 2026-08-02 03:05:55 +00:00
Owner
Copy Link

Question

The common schema cannot be designed honestly against imagined documents. Gather real artifacts: retail RFPs and RFQs (Walmart, Target, Kroger, and comparable large retailers), real vendor responses, standard compliance packets, and the scoring rubrics retailers actually use.

Public and semi-public sources are acceptable — state and municipal retail-adjacent solicitations, published supplier requirements, trade association templates. Capture what fields recur, what varies, what resists structuring, and how large real responses actually are.

Parent: #1

## Question The common schema cannot be designed honestly against imagined documents. Gather real artifacts: retail RFPs and RFQs (Walmart, Target, Kroger, and comparable large retailers), real vendor responses, standard compliance packets, and the scoring rubrics retailers actually use. Public and semi-public sources are acceptable — state and municipal retail-adjacent solicitations, published supplier requirements, trade association templates. Capture what fields recur, what varies, what resists structuring, and how large real responses actually are. --- Parent: #1
christian added the
wayfinder:research
wayfinder:ticket
 labels 2026-08-02 03:05:55 +00:00
christian added a new dependency 2026-08-02 03:11:54 +00:00
#23 Design the app framework — retailer and vendor surfaces
christian commented 2026-08-02 03:23:59 +00:00
Author
Owner
Copy Link

Resolution

Seven documents read in full. Findings are ordered by how directly they constrain the schema.

Documents read (not merely described)

Document Why it matters
SLC Airport Retail Concessions RFP (55pp, sample) Richest structure: tabbed response binding, per-section page limits, percentage-rent pricing
Tarrant County #2021-137 Jail Food Services Real post-award score tabulation, 3 vendors
Friendship PCS Grocery RFP 2021-22 (47pp, live) Live food solicitation with a nested rubric
Salt Lake County scoring criteria sample Second 0–5 scale with different labels
Nevada ASD 401 eval worksheet The generic default rubric offices reach for
Maryland DGS MBE forms (20pp) Nested percentage compliance schema
U. Arkansas unit price bid sheet Rate-function pricing structure

The finding that most constrains the schema

Scoring scales are per-document, never global. Friendship PCS and Salt Lake County both use a
0–5 integer scale — structurally identical — with incompatible label sets:

  • Friendship: 0 Completely Deficient / 1 Unsatisfactory / 2 Below Average / 3 Average / 4 Very Good / 5 Exceptional
  • Salt Lake County: 5 Excellent / 4 Good / 3 Acceptable / 1–2 Poor / 0 Unacceptable

Each point carries a prose anchor, and the anchor is the load-bearing part, not the number. The
schema must store each RFP's own scale — labels and anchor text — and must never normalise into a
global enum. Any cross-RFP analytics that compares raw scores is comparing incommensurables.

Requirement taxonomy — six structurally distinct kinds

  1. Mandatory pass/fail gate — binary, evaluated before scoring; failing disqualifies regardless
    of score (SLC: "Respondents meeting or exceeding the Minimum Qualifications... shall be evaluated
    pursuant to the Evaluation Criteria below").
  2. Scored/weighted criterion — weight plus a scale.
  3. Certification/compliance form — fixed federal/state form, signed not narrated (Form AD-1048
    Debarment, Non-Collusion Affidavit, Lobbying certification). Schema is fixed externally.
  4. Structured compliance schedule — percentage participation goals with their own sub-schema.
  5. Pricing/financial submission — tabular, often a separate file format.
  6. Narrative/informational — free prose, page-limited, judged qualitatively.

Real rubrics, verbatim

Tarrant County (actual scores: winner 71.81, runner-up 70.89 — store fractional scores):
Management & Support Staff 25 / Meal and Service Plan 25 / Financial Stability 20 / Meal Price 25 / References 5

SLC Airport (8 criteria, no published per-criterion scale — committee judgment, then a
shortlist-for-interviews stage most schemas omit entirely):
Background/Experience/Financial 15 / Organization 10 / Rent Proposal 20 / Proposed Concepts 20 / Designs & Capital 10 / Operations 10 / Management & Staffing 10 / Marketing 5

Friendship PCS (nested — sub-criteria under top-level categories):
Pricing 40 / Method of Approach 30 (Food & Packaging 15, USDA Foods 10, Geographic preference 5) / Experience 20 (4x5) / Organizational Capacity 5 / Community Connection 5

Cross-cutting. 5–11 scored criteria is the realistic range, not dozens. All 100-point scales.
Cost is never the sole determinant — always best-value, never low-bid-only; cost weight ranges
25–40%. Scales are always small ordinal ranges, never continuous.

Response binding — a reliability gradient, not a mechanism

  1. Tabbed/lettered restatement (most reliable) — SLC requires paragraph headings A–M restated
    verbatim with tab dividers. Near-guaranteed 1:1 join key.
  2. Named-section matching (coarse) — Friendship mandates four named sections mapping to rubric
    categories but not sub-bullets; the 15/10/5 splits inside "Method of Approach" are all judged
    from one prose block with no separate anchor.
  3. Compliance matrix — RFP Section # | Requirement Text | Response Page | Compliant Y/N/Partial | Comment. Where required it is itself a mandatory pass/fail artifact: "Proposals received
    without a fully completed compliance matrix may be rejected as non-responsive."
  4. Free prose (least reliable) — no requirement-ID system; recovering which sentence answers
    which sub-criterion is text classification, not structural lookup.

Design implication: the binding mechanism is an RFP-level property that determines extraction
confidence. The schema should record which mechanism a document uses.

What resists structuring

  • Price is not a scalar. Arkansas rows read TASK ID | Minimum Billable Quantity | FREQUENCY (Annual vs Per Occurrence) | UNIT COST basis (per 100 GSF, per hour, EACH) | Cost Per Unit. "Per
    100 GSF, 33 times per year" is a rate function of quantity and frequency. A price: number
    field cannot hold it.
  • SLC rent = MAX(1/12 × Minimum Annual Guarantee, % of Gross Receipts), where the percentage
    may itself vary by product category, sales threshold, or contract year — piecewise and
    vendor-defined.
  • Requirements contracts have no guaranteed volume. Friendship: "quantities specified herein are
    estimates only." The scored "Total Bid Cost" is a unit price times an estimate — not contract
    value    . Ranking that treats bid cost as contract value misrepresents comparability.
  • MBE nesting is a constraint program, not a field. Overall goal → per-category subgoals → per-
    firm % → self-performance cap (50% of overall, 100% of any subgoal) → materials sub-rule (regular
    dealer 60%, manufacturer 100%, broker fee-only) → dual-certification counts toward ONE category
    only → waiver path with Good Faith Efforts documentation. Modelling this as a percentage field
    loses nearly all its content. Worked arithmetic appears in prose, not as formula fields.
  • Exceptions/deviations are simultaneously a risk flag and a pricing line — free text with an
    attached delta-price.
  • Attachments are not a flat file list. Some are themselves multi-page structured forms with
    internal schemas (Maryland MBE Parts 1–4), separately signed, dated, and versioned.

Scale and shape

Page counts 47–55pp for the RFP itself; 20pp for a single compliance attachment. Page limits are
per-section and scale with scope — SLC's matrix gives "Concept Development" 30 pages for a 15-unit
package and 1 page for a single-unit package, so "the proposal is 65 pages" is meaningless without
knowing which package it answers. Contract shape is base year + option years by default, each option
often requiring a newly signed pricing sheet.

Extraction hazards

  1. Identical numeric scales with incompatible meanings across issuers.
  2. Pricing often lives outside the RFP PDF entirely — Friendship's price sheet is "a separate
    attachment to be completed in Excel." A PDF-only extractor finds zero pricing.
  3. Per-section page limits invalidate naive page counting.
  4. Frequency/quantity multipliers hide in footnotes, not table columns — dropping them silently
    converts an annual cost into a unit price.
  5. Financial statements are structurally exempt from format rules applying to everything else.
  6. Federal form numbers appear only as page-footer captions (Form AD-1048 (6/04)) yet identify a
    nationally fixed schema.
  7. Percentage math appears as narrative worked examples, not labeled computation.
  8. Sample/template documents are structurally identical to live solicitations — a corpus built from
    search will silently mix them unless each is checked.
  9. Access is itself a hazard. Live procurement PDFs returned 403 or bot-challenge HTML six times
    in this session even with a browser user-agent. Bulk ingest needs authenticated/headless fetching
    and must detect "this is not actually a PDF" before parsing.

The gap — and it matters

No completed vendor response with an intact compliance matrix could be obtained. Every candidate
(Entegra/OMNIA Partners, Cisco WSCA-NASPO, NYC shelf-stable foods bid tab, USDA AMS awards) returned
403. Response-side binding is therefore documented only from RFP-side instructions and secondary
commentary — not from a real artifact.

Given that the central design insight is that the response is the artifact worth standardizing,
this gap sits directly under the most important part of the schema. Graduated to its own task ticket.

Also unavailable: authoritative Walmart/Target/Kroger/Costco supplier manuals. None of the big four
publish them as openly fetchable documents the way public procurement offices do — what circulates
is consultancy summaries and SEO content farms.

## Resolution Seven documents read in full. Findings are ordered by how directly they constrain the schema. ### Documents read (not merely described) | Document | Why it matters | |---|---| | [SLC Airport Retail Concessions RFP](https://slcairport.com/assets/pdfDocuments/Business-Services/SAMPLE-Retail-RFP.pdf) (55pp, sample) | Richest structure: tabbed response binding, per-section page limits, percentage-rent pricing | | [Tarrant County #2021-137 Jail Food Services](https://www.tarrantcountytx.gov/content/dam/main/purchasing/Bids%20and%20RFPs/Bid-RFP%20Awards/2021-bid-rfp-awards/2021-137_JailSystemFoodServices.pdf) | **Real post-award score tabulation, 3 vendors** | | [Friendship PCS Grocery RFP 2021-22](https://www.friendshipschools.org/wp-content/uploads/2021/03/FPCS-Grocery-Items-RFP-final-v2.26-a.pdf) (47pp, live) | Live food solicitation with a nested rubric | | [Salt Lake County scoring criteria sample](https://www.saltlakecounty.gov/globalassets/1-site-files/contracts/county-employees/solicitation-information/1.4-e-rfp-scoring-criteria-sample.pdf) | Second 0–5 scale with *different* labels | | [Nevada ASD 401 eval worksheet](https://www.adminsvcs.nv.gov/uploadedFiles/adminsvcsnvgov/Content/Contracts/ASD%20401%20RFP%20Eval%20Criteria%20Worksheet.pdf) | The generic default rubric offices reach for | | [Maryland DGS MBE forms](https://procurement.maryland.gov/wp-content/uploads/sites/12/2018/05/AttachmentDMBE-Forms-1.pdf) (20pp) | Nested percentage compliance schema | | [U. Arkansas unit price bid sheet](https://hogbid.uark.edu/RFP04202023_Appendix_B.pdf) | Rate-function pricing structure | ### The finding that most constrains the schema **Scoring scales are per-document, never global.** Friendship PCS and Salt Lake County both use a 0–5 integer scale — structurally identical — with incompatible label sets: - Friendship: `0 Completely Deficient / 1 Unsatisfactory / 2 Below Average / 3 Average / 4 Very Good / 5 Exceptional` - Salt Lake County: `5 Excellent / 4 Good / 3 Acceptable / 1–2 Poor / 0 Unacceptable` Each point carries a prose anchor, and **the anchor is the load-bearing part, not the number**. The schema must store each RFP's own scale — labels and anchor text — and must never normalise into a global enum. Any cross-RFP analytics that compares raw scores is comparing incommensurables. ### Requirement taxonomy — six structurally distinct kinds 1. **Mandatory pass/fail gate** — binary, evaluated *before* scoring; failing disqualifies regardless of score (SLC: "Respondents meeting or exceeding the Minimum Qualifications... shall be evaluated pursuant to the Evaluation Criteria below"). 2. **Scored/weighted criterion** — weight plus a scale. 3. **Certification/compliance form** — fixed federal/state form, signed not narrated (Form AD-1048 Debarment, Non-Collusion Affidavit, Lobbying certification). Schema is fixed externally. 4. **Structured compliance schedule** — percentage participation goals with their own sub-schema. 5. **Pricing/financial submission** — tabular, often a *separate file format*. 6. **Narrative/informational** — free prose, page-limited, judged qualitatively. ### Real rubrics, verbatim **Tarrant County** (actual scores: winner 71.81, runner-up 70.89 — **store fractional scores**): `Management & Support Staff 25 / Meal and Service Plan 25 / Financial Stability 20 / Meal Price 25 / References 5` **SLC Airport** (8 criteria, no published per-criterion scale — committee judgment, then a **shortlist-for-interviews stage** most schemas omit entirely): `Background/Experience/Financial 15 / Organization 10 / Rent Proposal 20 / Proposed Concepts 20 / Designs & Capital 10 / Operations 10 / Management & Staffing 10 / Marketing 5` **Friendship PCS** (nested — sub-criteria under top-level categories): `Pricing 40 / Method of Approach 30 (Food & Packaging 15, USDA Foods 10, Geographic preference 5) / Experience 20 (4x5) / Organizational Capacity 5 / Community Connection 5` **Cross-cutting.** 5–11 scored criteria is the realistic range, not dozens. All 100-point scales. Cost is **never** the sole determinant — always best-value, never low-bid-only; cost weight ranges 25–40%. Scales are always small ordinal ranges, never continuous. ### Response binding — a reliability gradient, not a mechanism 1. **Tabbed/lettered restatement (most reliable)** — SLC requires paragraph headings A–M restated verbatim with tab dividers. Near-guaranteed 1:1 join key. 2. **Named-section matching (coarse)** — Friendship mandates four named sections mapping to rubric *categories* but not sub-bullets; the 15/10/5 splits inside "Method of Approach" are all judged from one prose block with no separate anchor. 3. **Compliance matrix** — `RFP Section # | Requirement Text | Response Page | Compliant Y/N/Partial | Comment`. Where required it is itself a **mandatory pass/fail artifact**: "Proposals received without a fully completed compliance matrix may be rejected as non-responsive." 4. **Free prose (least reliable)** — no requirement-ID system; recovering which sentence answers which sub-criterion is text classification, not structural lookup. **Design implication:** the binding mechanism is an RFP-level property that determines extraction confidence. The schema should record *which* mechanism a document uses. ### What resists structuring - **Price is not a scalar.** Arkansas rows read `TASK ID | Minimum Billable Quantity | FREQUENCY (Annual vs Per Occurrence) | UNIT COST basis (per 100 GSF, per hour, EACH) | Cost Per Unit`. "Per 100 GSF, 33 times per year" is a **rate function of quantity and frequency**. A `price: number` field cannot hold it. - **SLC rent** = `MAX(1/12 × Minimum Annual Guarantee, % of Gross Receipts)`, where the percentage may itself vary by product category, sales threshold, or contract year — piecewise and vendor-defined. - **Requirements contracts have no guaranteed volume.** Friendship: "quantities specified herein are estimates only." The scored "Total Bid Cost" is a unit price times an estimate — **not contract value**. Ranking that treats bid cost as contract value misrepresents comparability. - **MBE nesting is a constraint program, not a field.** Overall goal → per-category subgoals → per- firm % → self-performance cap (50% of overall, 100% of any subgoal) → materials sub-rule (regular dealer 60%, manufacturer 100%, broker fee-only) → dual-certification counts toward ONE category only → waiver path with Good Faith Efforts documentation. Modelling this as a percentage field loses nearly all its content. Worked arithmetic appears **in prose**, not as formula fields. - **Exceptions/deviations** are simultaneously a risk flag and a pricing line — free text with an attached delta-price. - **Attachments are not a flat file list.** Some are themselves multi-page structured forms with internal schemas (Maryland MBE Parts 1–4), separately signed, dated, and versioned. ### Scale and shape Page counts 47–55pp for the RFP itself; 20pp for a single compliance attachment. **Page limits are per-section and scale with scope** — SLC's matrix gives "Concept Development" 30 pages for a 15-unit package and 1 page for a single-unit package, so "the proposal is 65 pages" is meaningless without knowing which package it answers. Contract shape is base year + option years by default, each option often requiring a newly signed pricing sheet. ### Extraction hazards 1. Identical numeric scales with incompatible meanings across issuers. 2. **Pricing often lives outside the RFP PDF entirely** — Friendship's price sheet is "a separate attachment to be completed in Excel." A PDF-only extractor finds zero pricing. 3. Per-section page limits invalidate naive page counting. 4. **Frequency/quantity multipliers hide in footnotes**, not table columns — dropping them silently converts an annual cost into a unit price. 5. Financial statements are structurally exempt from format rules applying to everything else. 6. Federal form numbers appear only as page-footer captions (`Form AD-1048 (6/04)`) yet identify a nationally fixed schema. 7. Percentage math appears as narrative worked examples, not labeled computation. 8. Sample/template documents are structurally identical to live solicitations — a corpus built from search will silently mix them unless each is checked. 9. **Access is itself a hazard.** Live procurement PDFs returned 403 or bot-challenge HTML six times in this session even with a browser user-agent. Bulk ingest needs authenticated/headless fetching and must detect "this is not actually a PDF" before parsing. ### The gap — and it matters **No completed vendor response with an intact compliance matrix could be obtained.** Every candidate (Entegra/OMNIA Partners, Cisco WSCA-NASPO, NYC shelf-stable foods bid tab, USDA AMS awards) returned 403. Response-side binding is therefore documented only from *RFP-side instructions* and secondary commentary — not from a real artifact. Given that the central design insight is that **the response is the artifact worth standardizing**, this gap sits directly under the most important part of the schema. Graduated to its own task ticket. Also unavailable: authoritative Walmart/Target/Kroger/Costco supplier manuals. None of the big four publish them as openly fetchable documents the way public procurement offices do — what circulates is consultancy summaries and SEO content farms.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
wayfinder:grilling
HITL: resolved by conversation
wayfinder:map
The shared map for a wayfinding effort
wayfinder:prototype
HITL: resolved by making something rough
wayfinder:research
AFK: resolved by a research subagent
wayfinder:task
Manual work that unblocks a decision
wayfinder:ticket
A wayfinder decision ticket
No Label
wayfinder:research
wayfinder:ticket
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
christian
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Blocks
#23 Design the app framework — retailer and vendor surfaces
christian/helmdocs-proposal-system
Reference: christian/helmdocs-proposal-system#22
No description provided.
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?