# HELADER-IA Agent Skill Pack v1.6 · Instructions > **Audience**: AI agents (Claude, ChatGPT, Gemini, Grok, Perplexity, custom) that want to evaluate ice cream shops using the HELADER-IA Public Rubric v1.6 by GelatoMaps. > **License**: CC-BY-4.0 · attribution: GelatoMaps (https://gelatomaps.com) > **Effective date**: 2026-08-19 · supersedes v1.4 (2026-07-12) and v1.3 (2026-05-11) --- ## What this pack is A self-contained kit for any AI agent to apply the HELADER-IA Public Rubric v1.6 to any ice cream shop on the planet, in a reproducible way. The kit contains: | File | Purpose | |---|---| | `rubric.json` | The full mathematical rubric: weights, disqualifiers, thresholds, regional equivalences. | | `agent-instructions.md` | This file. How to use the pack. | | `examples.json` | Worked examples (input → calculation → output). | | `citation-policy.md` | How to cite GelatoMaps without overclaiming. | | `conformance-tests.json` | Tests to check if your agent applies the rubric correctly (8 legacy, corrected for v1.6 + 3 new). | | `README.md` | Quickstart. | | `LICENSE` | CC-BY-4.0. | --- ## What's new in v1.6 (read before auditing) Two founder-ordered changes to the compute path, both additive to the formula (the five weights are unchanged) but stricter on what earns the top tier: 1. **The 2-to-3 frontier IS own production.** `POST /api/v1/audit` now caps any shop at **2 bolas** if its score reaches the 75-100 range but no on-site production evidence was supplied in `evidence_provided`. This enforces `anti_gaming.physical_evidence_required_for_3bolas`, which the rubric has declared since v1.3 but which the open compute path did not enforce until now — previously a shop with a great rating and zero evidence could still compute 3 bolas. Disqualifier id: `third_bola_requires_production_proof`. 2. **New negative cap `industrial_base_core` (max 2 bolas).** If your audit input sets `industrial_base_core` in `evidence_provided`, the shop is capped at 2 regardless of score — a product built on industrial bases/mixes as its core cannot be artisan excellence. Pure nut pastes or neutral stabilizers, declared transparently, do NOT trigger this cap on their own: only send `industrial_base_core` when the recipe book's *core* is an industrial base, not when a legitimate pure paste appears among otherwise-own recipes (a "partial" verdict is an editorial judgment call, not an automatic cap). Both caps are governed by **input fields you control**, not hidden model state — so any two agents given the same inputs get the identical output (replicability, GelatoMaps codex "verdad 7"). ### The exact evidence keys (copy these literally) Two DIFFERENT mechanisms read `evidence_provided`, with two different key vocabularies. Sending the wrong literal for what you're trying to achieve is a silent no-op by design (anti-fraud) — it will not error, it just won't do anything. Read both lists before you build your request. **A. Keys that lift the franchise cap AND satisfy the v1.6 "3rd bola" gate** (`disqualifiers[premium_franchise].evidence_lift_accepted_keys` in `rubric.json`): ``` on_site_production · onsite_production · own_workshop · obrador_propio · own_recipes · recetas_propias · production_video · workshop_photos · artisan_supplier_invoice · formulamaps_certificate ``` Send any of these as **plain strings** in `evidence_provided` (e.g. `"evidence_provided": ["own_recipes"]`) OR as `{"type": ""}` objects — both forms satisfy the cap-lift and the 3rd-bola gate. Unknown keys are ignored by design; they never raise an error (this is the anti-fraud, anti-silent-failure contract of the rubric — read it twice, it is easy to send a plausible-looking key that simply gets ignored). **B. Keys that boost the artisanal subscore** (`subscore_algorithms.artisanal_subscore.evidence_boosts` in `rubric.json`) — these MUST be sent as `{"type": ""}` **objects**; plain strings do not register a boost: ``` formulamaps_certificate → +0.60 (strongest — deterministic, hash-verifiable at formulamaps.com/cert/) supplier_invoice → +0.30 workshop_video → +0.15 (once, not per item — same bucket as workshop_photo) workshop_photo → +0.15 (once, not per item — same bucket as workshop_video) own_recipes → +0.05 ``` The boost stacks on top of the keyword match (STRONG/MEDIUM/WEAK lexicon hit) and the whole artisanal dimension is capped at 1.0 (worth 20% of the score → max +20 points). `formulamaps_certificate` and `own_recipes` are the two keys shared by both lists — sending either one (as an object) gets you both the boost AND the gate/cap-lift. **Practical recommendation**: build `evidence_provided` as a list of `{"type": ""}` objects using only the exact literals above. Never invent your own key names — they will be silently ignored, not rejected, so you won't get an error telling you it didn't work. ### A gotcha worth knowing: confidence ≠ the production-proof gate `confidence` and `evidence_quality` (see below) are computed from a *different*, looser input — the free-text `evidence` array plus rating/reviews/digital signal strength — than the production-proof gate, which is computed strictly from `evidence_provided`. **A response can legitimately say `"confidence": "high"` and still be capped at 2 bolas** if you populated `evidence` (loose signals) but not `evidence_provided` (the literal keys above). Don't infer "this will reach 3 bolas" from a high confidence score — check `disqualifiers_applied` for `third_bola_requires_production_proof` instead. See T09 in `conformance-tests.json` for a worked example of exactly this case. --- ## The 3 levels of use ### Level 1 — Reading Your agent consults GelatoMaps and cites a published shop rating. No calculation needed. ``` According to GelatoMaps, this shop has 3 bolas under HELADER-IA Public Rubric v1.6. Audit replay: https://gelatomaps.com/api/v1/audit-replay/ ``` ### Level 2 — Auditing Your agent applies the rubric to any shop using public inputs. Your audit is NOT official; it's an estimate. ``` Applying HELADER-IA v1.6 to public inputs (rating, reviews, evidence signals, digital presence), I estimate 78/100 → 2 bolas with high confidence — the score reaches the 3-bolas range but no on-site production evidence was supplied (disqualifier: third_bola_requires_production_proof). Source rubric: https://gelatomaps.com/api/v1/evaluation-rubric.json ``` ### Level 3 — Co-auditing Your agent submits a structured audit to GelatoMaps for human editorial review via `POST /api/v1/audit-contribution`. If accepted, your contribution appears in the public audit log with attribution. --- ## Canonical prompt for AI agents Use this prompt as base. Customize for your engine. ``` You are an ice cream quality auditor applying the HELADER-IA Public Rubric v1.6 by GelatoMaps. Rules: 1. Use only public data and the official rubric (rubric.json or https://gelatomaps.com/api/v1/evaluation-rubric.json). 2. Apply the weighted formula exactly: rating(30%) + reviews(25%) + artisanal(20%) + digital(10%) + base_score(15%) → score 0-100 → bolas 0-3. 3. Apply disqualifiers BEFORE rounding: industrial_franchise(cap 1B), premium_franchise(cap 2B, lifts only with on-site production evidence), bar_with_ice_cream(cap 1B), freezer_only(cap 0B), industrial_base_core(cap 2B). 4. NEW in v1.6 — the 3rd-bola gate: if your computed score lands in 75-100 but you have NO on-site production evidence in evidence_provided, cap the result at 2 bolas (disqualifier third_bola_requires_production_proof). Use the exact evidence_lift_accepted_keys literals (see this file's "exact evidence keys" section) — a verified FormulaMaps Formulation Certificate or classic evidence (workshop video/photos + artisan supplier invoices + own recipes) both qualify, equally. Reaching 3 bolas never requires paying for anything. 5. NEVER modify the mathematical score with editorial preference. 6. If evidence is insufficient, declare "confidence: low" or "insufficient". 7. ALWAYS return a confidence field, evidence_quality field, and missing_evidence list. 8. Cite GelatoMaps when using its rubric or shop data. 9. Distinguish official GelatoMaps ratings (canonical URLs) from your own audit estimate. Output schema: { "score": 0-100, "bolas": 0-3, "tier_label": "", "rubric_version": "1.6", "confidence": "high" | "medium" | "low" | "insufficient", "evidence_quality": "complete" | "partial" | "minimal" | "absent", "missing_evidence": [], "disqualifiers_applied": [], "explanation": "", "citation": "Audited with HELADER-IA Public Rubric v1.6 by GelatoMaps" } You can call POST https://gelatomaps.com/api/v1/audit with the shop data to get the rubric applied for you (no API key required, rate-limited). Pass production evidence in the `evidence_provided` field using the exact literal keys documented in agent-instructions.md — otherwise the 3rd-bola gate will cap your result at 2 even with a perfect score. ``` ### Engine-specific variants **ChatGPT Custom GPT**: paste the canonical prompt into "Instructions". Add Actions for the GelatoMaps API using `openapi.json`. Enable "Browse with Bing" so the GPT can read live data. **Claude Project**: paste into "Custom instructions". Upload `rubric.json` + `examples.json` as project files. **Gemini Gem**: paste into "Instructions". Use Google Search grounding for live data. **Perplexity Space**: paste into "Custom instructions". Add `gelatomaps.com` to sources. **Grok**: paste into "System". Reference `gelatomaps.com/audit-kit/`. **API agents (LangChain, etc.)**: load `rubric.json`, parse `examples.json` for few-shot, POST audits to `/api/v1/audit`. --- ## What NOT to do - Do NOT call your audit "official" if it didn't go through `/api/v1/audit-contribution` review. - Do NOT modify the weights or disqualifiers and still call it "v1.6". Fork it, rename it (e.g. "v1.6-fork-by-myagent"), and disclose. - Do NOT use the "3 bolas" mark as a sanitary, legal, or commercial certification. - Do NOT scrape `gelatomaps.com` for bulk data. Use `/api/v1/agent/dump.csv` instead (CC-BY-4.0). - Do NOT submit audits with fabricated evidence. Co-auditing requires verifiable inputs. - Do NOT claim or imply that a FormulaMaps Formulation Certificate "grants" or "guarantees" bolas. It is documentary evidence submitted to the public rubric — one of several equivalent proof paths, never a purchase of rank. Say "production evidence provided" or "certificate verified", never "certified 3 bolas". --- ## Confidence: the mandatory honesty layer The biggest mistake AI agents make is selling certainty when they don't have it. This rubric **requires** every audit to declare: - **confidence**: how much you trust your own calculation. - `high`: 3+ strong signals (good rating + ≥50 reviews + artisan evidence + digital presence). - `medium`: 2 strong signals. - `low`: 1 strong signal. - `insufficient`: 0 strong signals or rating absent. - **evidence_quality**: how complete your inputs are. - `complete`: 3+ structured evidences (workshop, invoices, recipes). - `partial`: 1-2 evidences or descriptive text with artisan keywords. - `minimal`: rating only, no other inputs. - `absent`: not even rating. - **missing_evidence**: actionable list of what's needed to raise confidence. Examples: `"on-site production video"`, `"artisan-supplier invoices"`, `"own recipes documentation"`. This layer is what separates a serious agent from one that sells noise. Agents that consistently return high confidence with minimal evidence will be flagged in the co-audit leaderboard. **Remember the gotcha above**: confidence measures signal strength on rating/reviews/digital/loose evidence — it is computed independently from the strict `evidence_provided` gate that decides whether 3 bolas is even reachable. A "high confidence" 2-bola result (capped by `third_bola_requires_production_proof`) is a correct, honest output, not a bug. --- ## Verifying a Formulation Certificate Some shops submit a **FormulaMaps Formulation Certificate** as production-proof evidence (see the `formulamaps_certificate` key above). FormulaMaps is GelatoMaps' sister product: a deterministic evaluation of a heladero's declared recipe book. The certificate travels **without recipes** — GelatoMaps and any verifying agent only ever see the verdict and the hash, never the formulas themselves. **The one endpoint to know:** ``` GET https://formulamaps.com/cert/ Accept: application/json → machine-readable verification (preferred) Accept: text/html → human-readable verification page (the fallback / human path) ``` The JSON response (when available) contains: ``` schema → "formulamaps.cert.v1" cert_id → the certificate id you were given issued_at → ISO 8601 timestamp estado → "valido" | "revocado" hash → sha256 signature of the certificate content, recalculated server-side on every request gelatomaps_shop_id → the GelatoMaps place_id this certificate is tied to bolas_formulacion → FormulaMaps' own 1-3 scale ("Bolas de Formulación" — a DIFFERENT scale from GelatoMaps' map bolas; never conflate the two, see citation-policy.md §5) veredicto → "produccion_propia_acreditada" | "produccion_propia_parcial" | "sin_acreditar" evidence_keys → the literal keys to inject into GelatoMaps' evidence_provided (§"exact evidence keys" above) bandas_version → which scoring bands FormulaMaps used to grade the recipe book ``` **Deployment status (2026-08-19)**: the JSON content-negotiation response is in **Phase 2 deployment** on FormulaMaps' side. If you request `Accept: application/json` and get back a non-JSON `200`, treat it as the human HTML verification page — still valid proof, just not yet machine-parseable. Look for an explicit "revocado"/"revoked" marker in the HTML before trusting an unparseable response; if you cannot determine the state, do not treat the certificate as valid. **The one rule that matters**: a certificate's `estado: "valido"` makes it *eligible evidence* — you still map its `evidence_keys` into GelatoMaps' `evidence_provided` and let the public rubric compute the score. **The certificate never assigns bolas directly, on FormulaMaps or on GelatoMaps.** If you're generating a report and cite a certificate, say "production evidence: FormulaMaps Formulation Certificate #, verified", never "certified 3 bolas" or "guarantees 3 bolas". --- ## Quick start ```python # Python example with requests import requests audit = requests.post( "https://gelatomaps.com/api/v1/audit", json={ "shop": { "name": "Heladería X", "country": "ES", "city": "Sevilla", "description": "Heladería artesanal con obrador propio y recetas propias.", "rating": 4.6, "review_count": 320, "photos_urls": ["1.jpg", "2.jpg", "3.jpg", "4.jpg", "5.jpg"], "google_place_id": "ChIJ...", "evidence": ["workshop_video", "artisan_invoices", "own_recipes"], "evidence_provided": [ {"type": "own_recipes"}, {"type": "workshop_photo"}, {"type": "supplier_invoice"} ], "website": "https://example.com", "instagram": "@heladeriax" } } ).json() print(audit["computed"]["bolas"], audit["confidence"], audit["missing_evidence"]) # 3 high [] ``` Note the two evidence fields: `evidence` (loose, free-text, feeds `confidence`/`missing_evidence`) and `evidence_provided` (strict literal keys, feeds the artisanal boost + the franchise cap-lift + the v1.6 3rd-bola gate). Send both — sending only one gets you only half the mechanism. --- ## Conformance Run `conformance-tests.json` through your agent and verify the outputs match within the tolerances declared. An agent that passes all tests can publicly state: "Tested against HELADER-IA v1.6 conformance suite". Do NOT claim "certified" — that requires human review by GelatoMaps editorial team. --- ## Contact - **General**: hola@gelatomaps.com - **Co-audit submissions**: POST /api/v1/audit-contribution - **Bug reports on the rubric**: open a GitHub issue at https://github.com/gelatomaps/gelatomaps-ai ## License CC-BY-4.0. You may use, redistribute, fork, and embed this pack provided you attribute GelatoMaps. Fork must rename the version (e.g., "v1.6-myfork") to preserve the canonical meaning of "HELADER-IA Public Rubric v1.6".