@damiangilgonzalez/harness 1.3.7

package/skills/stripe/references/webhook-events.md

@@ -0,0 +1,79 @@
+# Stripe webhook events — catalog per flow
+
+What to listen for and what each event should do to your DB. Subscribe to only
+the events a flow needs; "send all events" is discouraged.
+
+## Subscription paywall
+
+| Event | What it means | DB action |
+|---|---|---|
+| `checkout.session.completed` | Customer finished Checkout (paid or trial started) | Link `client_reference_id` (your user) to `session.customer`; mark provisional access. |
+| `customer.subscription.created` | Subscription now exists | Store `subscription.id`, `status`, `current_period_end`, price ID. |
+| `customer.subscription.updated` | Plan changed, renewed, trial→active, past_due, canceled-at-period-end | Re-sync `status` and `current_period_end`. This is the workhorse; gate access on `status`. |
+| `customer.subscription.deleted` | Subscription ended | Revoke access. |
+| `invoice.paid` | A billing cycle was paid | Confirm/extend access; optionally store the invoice ref. |
+| `invoice.payment_failed` | A charge failed | Enter dunning (below); do not revoke immediately. |
+
+Gate access on `subscription.status` (`active` or `trialing` = entitled;
+`past_due`/`unpaid`/`canceled` = not), not on a single "is_pro" boolean you
+set once at checkout.
+
+## One-time payment
+
+| Event | DB action |
+|---|---|
+| `checkout.session.completed` (mode `payment`) | Fulfill the order / unlock the download. The primary signal. |
+| `payment_intent.succeeded` | Optional confirmation if you also create PaymentIntents directly. |
+
+## Dunning (failed payment)
+
+`invoice.payment_failed` starts Stripe's automatic retry schedule (Smart
+Retries / your dunning settings). Do not revoke on the first failure — Stripe
+will retry. Mark the account `past_due` and surface a "update your card"
+prompt (link to the billing portal). Revoke only when
+`customer.subscription.deleted` fires.
+
+## Thin events vs snapshot events
+
+- **Snapshot events** (`event.data.object`) embed a full object snapshot at send
+  time. Convenient, but the object may already be stale by the time you process
+  it out of order.
+- **Thin events** carry only IDs; you fetch the current object yourself. They
+  are inherently fresher.
+
+Whichever you receive, for state that matters (subscription status), re-fetch
+or trust the latest `customer.subscription.updated` rather than reconstructing
+state from an ordered sequence — events are not ordered.
+
+## Raw-body recipes by framework
+
+```ts
+// Express — raw on this route only; keep express.json() for other routes.
+app.post("/webhook", express.raw({ type: "application/json" }), handler);
+```
+
+```ts
+// Next.js App Router — route segment runs on Node by default; read raw text.
+export async function POST(req: Request) {
+  const body = await req.text();
+  const sig = req.headers.get("stripe-signature")!;
+  const event = stripe.webhooks.constructEvent(body, sig, secret);
+  // ...
+  return new Response(null, { status: 200 });
+}
+```
+
+```ts
+// Next.js Pages Router — disable the body parser, read the raw stream.
+export const config = { api: { bodyParser: false } };
+```
+
+```ts
+// Edge / Workers — no Node crypto; use the async API + Web Crypto provider.
+const event = await stripe.webhooks.constructEventAsync(
+  body, sig, secret, undefined, Stripe.createSubtleCryptoProvider(),
+);
+```
+
+The header name is lowercase `stripe-signature`. Default replay tolerance is
+5 minutes; a clock skew larger than that rejects valid events.

package/skills/stripe/scripts/verify.sh

@@ -0,0 +1,130 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# ============================================================================
+# NAME
+#   verify.sh — stripe integration static linter
+#
+# USAGE
+#   ./verify.sh [TARGET]
+#   TARGET is a file or directory (default: current directory). Run it against
+#   the source that wires your app to Stripe. READ-ONLY: it never edits files.
+#
+# WHAT IT CHECKS (FAIL on any violation)
+#   1. Hard-coded sk_live_ / sk_test_ / whsec_ literals in source.
+#   2. A webhook handler (uses constructEvent / handles stripe-signature) that
+#      also applies JSON body parsing on that route — the raw-body violation
+#      that yields "No signatures found matching the expected signature".
+#   3. A webhook route present with NO signature verification at all.
+#   4. A Stripe client constructed with no explicit apiVersion pin.
+#
+# GUARANTEES
+#   - Read-only and idempotent; writes nothing to the target.
+#   - Exit 0 on a clean OR empty/no-Stripe target (never a false failure).
+#   - No network. Portable to stock macOS bash 3.2.
+#
+# EXIT CODES
+#   0  No violations (clean, or nothing Stripe-related found).
+#   1  At least one violation.
+# ============================================================================
+
+TARGET="${1:-.}"
+
+RED=$'\033[31m'; YEL=$'\033[33m'; GRN=$'\033[32m'; RST=$'\033[0m'
+if [ -n "${NO_COLOR:-}" ]; then RED=""; YEL=""; GRN=""; RST=""; fi
+
+FAILED=0
+bad()  { printf '%s[FAIL]%s %s\n' "$RED" "$RST" "$*" >&2; FAILED=1; }
+ok()   { printf '%s[ok]%s %s\n'   "$GRN" "$RST" "$*"; }
+info() { printf '%s[info]%s %s\n' "$YEL" "$RST" "$*"; }
+
+if [ ! -e "$TARGET" ]; then
+  info "target '$TARGET' does not exist; nothing to check"
+  exit 0
+fi
+
+# Collect candidate source files (JS/TS family). Skip vendored/build dirs.
+FILES=""
+if [ -f "$TARGET" ]; then
+  FILES="$TARGET"
+else
+  FILES=$(find "$TARGET" \
+    \( -name node_modules -o -name .git -o -name dist -o -name build -o -name .next \) -prune -o \
+    -type f \( -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.jsx' -o -name '*.mjs' \) -print 2>/dev/null || true)
+fi
+
+if [ -z "$FILES" ]; then
+  info "no JS/TS source files under '$TARGET'; nothing to check"
+  exit 0
+fi
+
+# --- 1. Hard-coded keys -----------------------------------------------------
+# Match real Stripe key prefixes followed by a body char. Documentation/example
+# placeholders like sk_test_... or sk_test_xxx are ignored.
+KEY_HITS=$(grep -REn "(sk_live|sk_test|whsec)_[A-Za-z0-9]{6,}" $FILES 2>/dev/null | grep -Ev "x{6,}|\.\.\.|YOUR_|<|placeholder" || true)
+if [ -n "$KEY_HITS" ]; then
+  bad "hard-coded Stripe key literal(s) — read from env instead:"
+  printf '%s\n' "$KEY_HITS" >&2
+else
+  ok "no hard-coded Stripe key literals"
+fi
+
+# --- Identify webhook-handling files ----------------------------------------
+# A file is "webhook-related" if it references the stripe-signature header or
+# the constructEvent API.
+WEBHOOK_FILES=""
+for f in $FILES; do
+  if grep -Eqi "stripe-signature|constructEvent" "$f" 2>/dev/null; then
+    WEBHOOK_FILES="$WEBHOOK_FILES $f"
+  fi
+done
+
+if [ -z "$WEBHOOK_FILES" ]; then
+  info "no Stripe webhook handler found; skipped webhook checks"
+else
+  for f in $WEBHOOK_FILES; do
+    # 2. raw-body violation: JSON parsing on a route that also verifies.
+    if grep -Eqi "express\.json|bodyParser\.json|req\.json\(\)|await\s+req\.json|res\.json" "$f" 2>/dev/null \
+       && grep -Eqi "express\.json\(\)|bodyParser\.json|req\.json\(\)|await\s+req\.json" "$f" 2>/dev/null; then
+      bad "$f: webhook handler parses JSON body (express.json/req.json) — breaks signature verification; use raw body (express.raw / await req.text())"
+    fi
+
+    # 3. signature verification present?
+    if grep -Eqi "constructEvent" "$f" 2>/dev/null; then
+      ok "$f: verifies webhook signature (constructEvent)"
+    else
+      bad "$f: handles stripe-signature but never calls constructEvent — unverified webhook"
+    fi
+  done
+fi
+
+# --- 4. apiVersion pin on the Stripe client ---------------------------------
+# For each file that constructs `new Stripe(`, require an apiVersion within the
+# same file.
+CLIENT_FILES=""
+for f in $FILES; do
+  if grep -Eq "new\s+Stripe\s*\(" "$f" 2>/dev/null; then
+    CLIENT_FILES="$CLIENT_FILES $f"
+  fi
+done
+
+if [ -z "$CLIENT_FILES" ]; then
+  info "no 'new Stripe(' client construction found; skipped apiVersion check"
+else
+  for f in $CLIENT_FILES; do
+    if grep -Eq "apiVersion" "$f" 2>/dev/null; then
+      ok "$f: Stripe client pins apiVersion"
+    else
+      bad "$f: 'new Stripe(' without an explicit apiVersion pin"
+    fi
+  done
+fi
+
+# --- Summary ----------------------------------------------------------------
+printf '\n'
+if [ "$FAILED" -eq 0 ]; then
+  ok "PASS — no Stripe integration violations"
+else
+  printf '%sFAIL — Stripe integration violations above%s\n' "$RED" "$RST" >&2
+fi
+exit "$FAILED"

package/skills/structured-extraction/SKILL.md

@@ -0,0 +1,230 @@
+---
+name: structured-extraction
+description: "Use when text must become a typed, schema-conformant object you can trust — pulling fields into a fixed JSON shape, extracting line items as typed records, classifying into enums, and building the Pydantic or Zod model plus the validate-and-retry loop. Covers extractors that throw parse errors, leak markdown fences, or fabricate a value where the field is absent instead of returning null. NOT getting the text out of a PDF, scan or DOCX first (that is `document-processing`), NOT general prompt craft untied to a schema (that is `prompt-engineering`)."
+tags: [structured-outputs, json-schema, pydantic, extraction, validation, llm]
+recommends: [document-processing, prompt-engineering, llm-pipeline, agent-eval, rag, data-cleaning]
+profiles: []
+origin: risco
+---
+
+# Structured extraction — text in, a typed object you can trust out
+
+The deliverable is **a typed object that conforms to a schema you defined** — not prose, not "roughly JSON."
+The whole skill rests on one distinction the rest of the file keeps returning to:
+
+> Native structured outputs make the JSON **valid and typed**. They never make the values **correct**.
+
+Constrained decoding guarantees the model cannot emit a token that breaks your schema, so `JSON.parse`
+errors, missing keys, wrong types, and stray markdown fences disappear at the source. It does **nothing**
+to stop the model from putting a plausible-but-wrong email in a `string` field, snapping a fuzzy category to
+the wrong enum, or coercing `"$1,200"` into `1200.0` when the currency mattered. Owning both halves — the
+shape (decoding) and the values (validation) — is this skill. If you only do the first half you ship a
+database full of well-typed lies.
+
+**Boundary test (bytes vs. schema).** If the input is a PDF, scan, DOCX, or HTML and the deliverable is the
+*raw text/Markdown/cells* of that document, that is upstream: [`document-processing`](../document-processing/SKILL.md)
+produces the text, this skill turns that text into typed fields. If you're holding text and want it shaped,
+you're in the right place.
+
+Current as of 2026-06-02: OpenAI Structured Outputs (`strict: true` json_schema), Anthropic Structured
+Outputs (GA since the 2025-11-14 public beta; `output_config.format`), and Instructor (built on Pydantic,
+~3M downloads/month). Exact request/response shapes and the per-provider limit tables live in
+[`references/providers.md`](references/providers.md) so this file stays lean.
+
+## Default: native constrained decoding when the provider has it
+
+If the model and provider support native structured outputs, use them. This is not a tuning knob — it is the
+difference between ~100% schema conformance and hoping a regex catches the fence.
+
+**Bad — prompt-and-pray, then parse raw text:**
+
+```python
+resp = client.chat.completions.create(
+    model="gpt-5.1",
+    messages=[{"role": "user", "content": f"Return JSON with name and email:\n{text}"}],
+)
+data = json.loads(resp.choices[0].message.content)  # markdown fence / preamble / missing key -> crash
+```
+
+**Good — OpenAI strict json_schema (Chat Completions):**
+
+```python
+resp = client.chat.completions.create(
+    model="gpt-5.1",
+    messages=[{"role": "user", "content": text}],
+    response_format={
+        "type": "json_schema",
+        "json_schema": {
+            "name": "contact",
+            "strict": True,
+            "schema": {
+                "type": "object",
+                "additionalProperties": False,
+                "required": ["name", "email"],
+                "properties": {
+                    "name": {"type": "string", "description": "Full name as written."},
+                    "email": {"type": ["string", "null"],
+                              "description": "Email exactly as written, or null if none is stated."},
+                },
+            },
+        },
+    },
+)
+data = json.loads(resp.choices[0].message.content)  # now guaranteed valid + typed
+```
+
+On the OpenAI Responses API the same block moves under `text.format` instead of `response_format`. On
+Anthropic, the equivalent is `output_config={"format": {"type": "json_schema", "schema": {...}}}` on Claude
+Opus 4.5–4.8 / Sonnet 4.5+ / Haiku 4.5; Anthropic compiles your schema into a grammar and **caches it for
+24h**, and the SDKs ship helpers (`client.messages.parse(...)` in Python, `zodOutputFormat(schema)` in TS).
+The older deprecated `output_format` param and the deprecated `structured-outputs-2025-11-13` beta header
+still work in a transition window — do not write new code against them. Full shapes in
+[`references/providers.md`](references/providers.md).
+
+**The non-negotiable strict-schema rule (OpenAI and Anthropic both):**
+
+- every object sets `"additionalProperties": false`;
+- **every** property is listed in `required`;
+- "optional" is expressed as a **union with `null`** (`"type": ["string", "null"]`), never by leaving the
+  field out of `required`. Omitting it is the single most common strict-mode error.
+
+## Schema design rules (each prevents a specific failure)
+
+| You want | Express it as | Because |
+| --- | --- | --- |
+| A field that may be absent | nullable union `["string","null"]` + `description: "...or null if not stated"` | A non-null type *forces* a value, so the model fabricates one. Nullable + instruction yields `null` instead. |
+| A closed set of categories | `enum: ["open","pending","closed"]` | Free-text `string` drifts ("Open", "in progress", "closd"); an enum makes drift impossible to emit. |
+| Many items of one kind | one object schema + a top-level `{"items": {"type":"array","items": <object>}}` wrapper | One object per extraction unit keeps each record independently validatable; arrays of scalars lose field structure. |
+| The model to read your intent | a `description` on every property | The model reads field descriptions at decode time; "amount in cents, no currency symbol" beats a bare `integer`. |
+| A number in a range / a regex / a length cap | leave it **out** of the schema; enforce in a post-decode validator | Strict modes reject or silently ignore `minimum`/`maximum`/`minLength`/`maxLength`/complex regex — see the unsupported-features table in references. |
+| A deeply nested or recursive shape | flatten it, or split into two extractions | Native modes reject recursion and cap nesting/complexity; flat schemas decode reliably. |
+
+Keep schemas **flat and shallow**. If you find yourself nesting four levels deep or describing a tree, that
+is two extractions, not one heroic schema.
+
+## The reliability ladder — escalate only on failure, and cap it
+
+Climb from the cheapest mechanism upward. Each rung catches what the rung below cannot; you stop at the
+first rung that holds for your data.
+
+| Rung | Mechanism | Catches | Does NOT catch | When you stop here |
+| --- | --- | --- | --- | --- |
+| 1 | Native constrained decoding | parse errors, wrong types, missing keys, fences | wrong values, bad units, wrong enum | shape+types only, latest single provider |
+| 2 | Pydantic / Zod validation after decode | out-of-range, bad format, cross-field contradictions, null-vs-absent | nothing the model genuinely got wrong | value rules you can express as code |
+| 3 | Bounded reask (Instructor or hand-rolled) | semantic errors the model can fix when shown the validation message | systematic model blind spots | residual errors; **cap retries (e.g. 2) and log every reask** |
+| 4 | Human / log review | everything still wrong after 3 | — | high-stakes fields or low-confidence rows |
+
+Rung 1 is mandatory when available. Rung 2 is mandatory the moment any field has a *value* rule (a range, a
+format, a "must match the order date") — because rung 1 structurally cannot enforce values. Rungs 3 and 4
+are opt-in. **Never** make rung 3 unbounded: a retry loop with no cap turns one bad document into an
+unbounded bill.
+
+## Value validation the schema can't enforce
+
+This is the half native decoding leaves on the table. Validate values *after* you have a typed object.
+
+**Pydantic — value rules + normalization the schema can't carry:**
+
+```python
+from pydantic import BaseModel, field_validator
+
+class Order(BaseModel):
+    amount_cents: int
+    discount_pct: float | None  # nullable: may be absent
+    order_date: str             # we'll normalize to ISO
+
+    @field_validator("discount_pct")
+    @classmethod
+    def pct_in_range(cls, v):
+        if v is not None and not (0 <= v <= 100):
+            raise ValueError("discount_pct must be between 0 and 100")
+        return v
+
+    @field_validator("amount_cents", mode="before")
+    @classmethod
+    def strip_currency(cls, v):
+        if isinstance(v, str):  # "$1,200.00" -> 120000
+            return int(round(float(v.replace("$", "").replace(",", "")) * 100))
+        return v
+```
+
+The Zod equivalent uses `.refine()` for cross-field and range checks and `.transform()` for normalization.
+Three normalizations bite constantly: **currency** (`"$1,200"` vs `1200` vs `120000` cents — pick one and
+enforce it), **dates** (free text → ISO 8601, and decide what a missing year means), and **enum snapping**
+(the model rounds "kinda urgent" to `urgent`; validate that the snap was legitimate, or widen the enum).
+
+**Null vs. absent.** A nullable field with a clear instruction is the entire fix for "the model invents an
+email." `"email": {"type": ["string","null"], "description": "...or null if the text states no email"}` plus
+a one-line system instruction ("use null for any field not present in the source; never guess"). If you make
+the field non-nullable, you have *told the model to produce a value* — it will.
+
+**Bounded reask with Instructor** — failed validation is fed back to the model as an error message:
+
+```python
+import instructor
+
+client = instructor.from_provider("openai/gpt-5.1")
+order = client.chat.completions.create(
+    response_model=Order,            # your Pydantic model, validators and all
+    max_retries=2,                   # BOUND it; each retry is another paid call
+    messages=[{"role": "user", "content": text}],
+)
+```
+
+On a validation failure Instructor reasks with the `ValueError` text, so `@field_validator` rules the model
+never saw in the schema still get enforced through the loop. Log every reask (count + reason): a quietly
+climbing reask rate is your early signal that a field's instruction or schema is wrong.
+
+## Multi-provider: Instructor `from_provider`
+
+When you want one Pydantic model to run across OpenAI, Anthropic, and local backends without rewriting per
+SDK, use Instructor's unified entrypoint:
+
+```python
+client = instructor.from_provider("anthropic/claude-opus-4-8")  # or "openai/gpt-5.1", "ollama/llama3.3"
+```
+
+Reach for Instructor when you need **provider portability** or **value-level validation with reask**. Reach
+for the **native SDK helper** (`client.messages.parse`, `zodOutputFormat`) when you're on one provider and
+want the simplest path with the fewest dependencies. Both sit on the same native decoding underneath.
+
+## Scale and accuracy live next door
+
+This skill is the single extraction node and its per-call validation loop. Two concerns are explicitly *not*
+here:
+
+- Running 10k documents — batching, idempotency, retries-across-calls, cost/latency budgeting, multi-step
+  chains → [`llm-pipeline`](../llm-pipeline/SKILL.md).
+- Measuring extraction quality offline — a golden set, precision/recall, a regression gate that fails CI when
+  accuracy drops → [`agent-eval`](../agent-eval/SKILL.md). This skill *builds* the extractor; that one *scores* it.
+- Answering questions over a corpus by retrieving chunks → [`rag`](../rag/SKILL.md).
+- Post-extraction tabular cleanup (dedupe rows, coerce columns, normalize categories across a whole dataset)
+  → [`data-cleaning`](../data-cleaning/SKILL.md).
+- Improving a prompt that isn't bound to a schema → [`prompt-engineering`](../prompt-engineering/SKILL.md).
+
+(Some routed siblings may not be built in this collection yet; the routing decision still holds.)
+
+## Anti-patterns
+
+| Bad | Why it bites | Good |
+| --- | --- | --- |
+| `json.loads(resp.text)` on raw model output | markdown fence, chatty preamble, or a missing key crashes at runtime | native structured outputs; parse only a decoder-guaranteed string |
+| Stripping ` ```json ` fences with a regex | treats the symptom; the model can still drop a key or change a type | turn on native decoding — the fence never appears |
+| `"type": "string"` on a field that's often absent | forces a value, so the model fabricates a plausible wrong one | nullable union `["string","null"]` + "null if not stated" |
+| Omitting an optional field from `required` (strict mode) | OpenAI/Anthropic strict reject it — *every* property must be in `required` | keep it in `required`, make its type a union with `null` |
+| `minimum`/`maxLength`/lookahead-regex inside a strict schema | rejected or silently ignored — the constraint does nothing | leave value rules out of the schema; enforce in a Pydantic/Zod validator |
+| `max_retries` unbounded (or a `while` reask loop) | one bad doc becomes an unbounded bill and a hung job | cap at 2–3, log each reask, route the rest to review |
+| Deep/recursive schema in one call | native modes reject recursion and cap complexity → compile failure | flatten, or split into multiple extractions |
+| Trusting decoding to make values *correct* | valid+typed ≠ true; you ship well-formed wrong data | add the rung-2 validation step for every value rule |
+| Building on Anthropic `output_format` / `structured-outputs-2025-11-13` header | deprecated transition-window API | use `output_config={"format": {...}}` |
+| One giant array of scalars for "many things" | loses per-item field structure and per-item validation | one object schema per unit, wrapped in a top-level `items` array |
+
+## Checklist before you ship an extractor
+
+1. Native structured outputs ON (or a documented reason the provider has no native mode).
+2. Every object has `additionalProperties: false`; every property is in `required`.
+3. Every maybe-absent field is nullable with a "use null if not stated" instruction.
+4. Closed sets are enums; value rules (ranges/format/cross-field) live in validators, not the schema.
+5. A reask loop, if any, is **bounded and logged**.
+6. You can state, for each field, whether a wrong output would be caught by decoding (shape) or only by
+   validation (value) — and you have the validation for the value cases.

package/skills/structured-extraction/evals/README.md

@@ -0,0 +1,13 @@
+# Evals — structured-extraction
+
+These cases are read by a human or an LLM grader; nothing here runs a model automatically. To check the
+skill, eyeball each `should_trigger` prompt against the SKILL.md `description` and confirm the routing
+language would pull this skill in — the set deliberately includes a symptom-led, non-obvious case (the
+"markdown fence / JSON.parse blows up" prompt, whose real fix is native structured outputs, not fence
+stripping) and a Spanish/Catalan case. Then check each `should_not_trigger` prompt routes to the named
+sibling instead (`document-processing` for raw text-out, `prompt-engineering` for schema-less prompt craft,
+`llm-pipeline` for multi-node/batch, `agent-eval` for offline scoring, `rag` for retrieval, `data-cleaning`
+for tabular cleanup) — those are the boundary lines the description must hold. The `capability` case is a
+rubric: read it as "could an agent following SKILL.md produce an answer hitting every `must_include` bullet?"
+If the body can't satisfy a bullet, fix the body, not the rubric. To statically lint the skill's own example
+code (no network, no SDK calls), run `scripts/verify.sh`.

package/skills/structured-extraction/evals/cases.yaml

@@ -0,0 +1,70 @@
+skill: structured-extraction
+
+# Prompts that MUST load `structured-extraction`. The skill owns turning text
+# into a typed, schema-conformant object: defining the schema, choosing the
+# native decoding mechanism, and building the value-validation + bounded-reask
+# loop. The deliverable is a typed object that conforms to a schema you defined
+# — both its SHAPE (decoding) and its VALUES (validation).
+should_trigger:
+  - prompt: "Extract name, email, and total amount from these invoices into a fixed JSON schema."
+    why: "Canonical text-in/typed-object-out: a defined schema plus extraction is exactly this skill."
+
+  - prompt: "My LLM keeps returning a markdown fence and a chatty intro, JSON.parse blows up — make extraction reliable."
+    why: "Non-obvious: the symptom reads like a parsing bug, but the real fix is native structured outputs, not regex fence-stripping."
+
+  - prompt: "When the document has no phone number the model invents one — I want null instead."
+    why: "The value-correctness half: null-vs-absent is solved with a nullable schema field plus a 'use null if not stated' instruction, not by re-prompting harder."
+
+  - prompt: "Build the Pydantic model and a validate-and-retry loop to pull line items from 5k receipts."
+    why: "Schema design + bounded reask loop for value validation — the rung-2/rung-3 core of this skill."
+
+  - prompt: "Convertir estos contratos en datos estructurados con un esquema fijo y validar los campos."
+    why: "Spanish/Catalan: turn contracts into structured data with a fixed schema and validate the fields — squarely this skill."
+
+  - prompt: "Classify each support ticket into one of these 6 enums and pull the order id as structured output."
+    why: "Closed-set enum classification plus field extraction, emitted as a schema-conformant object."
+
+# NEAR-MISS prompts that must NOT load `structured-extraction`. The recurring
+# trap: the real deliverable is raw document bytes/text, a generic prompt, a
+# multi-node pipeline, an offline accuracy scorecard, or a retrieval index.
+should_not_trigger:
+  - prompt: "Get the text and tables out of this scanned PDF."
+    route_to: "document-processing"
+    why: "Produces the unstructured text this skill consumes; bytes-out, not schema-out."
+
+  - prompt: "Help me write a better system prompt with few-shot examples for my chatbot."
+    route_to: "prompt-engineering"
+    why: "General prompt craft not bound to a target schema; schema design and constrained decoding live here, 'make this prompt better' lives there."
+
+  - prompt: "Orchestrate a 4-step chain that summarizes then routes then drafts, and batch 50k docs cheaply."
+    route_to: "llm-pipeline"
+    why: "Multi-node orchestration, batching, and cost/latency — not a single extraction node."
+
+  - prompt: "Score my extractor's precision and recall against a labeled golden set and gate regressions in CI."
+    route_to: "agent-eval"
+    why: "Offline measurement harness; this skill builds the extractor, agent-eval scores it."
+
+  - prompt: "Answer questions over my document corpus by retrieving the relevant chunks."
+    route_to: "rag"
+    why: "Retrieval over a corpus, not parsing one document into a fixed schema."
+
+  - prompt: "Dedupe and normalize the categories across this 200k-row CSV of customers."
+    route_to: "data-cleaning"
+    why: "Tabular cleanup across a whole dataset, not extracting typed fields out of free text."
+
+# Capability: graded against the must_include rubric.
+capability:
+  - scenario: >
+      Given a paragraph of free text describing a customer order — sometimes
+      missing the email or the discount percent, sometimes writing the amount
+      as "$1,200.00" — produce a reliable typed extraction (vendor, amount,
+      email, discount_pct, order_date). Outline the schema and the code you
+      would write.
+    must_include:
+      - "Uses a native structured-outputs mode (OpenAI strict:true json_schema OR Anthropic output_config.format), NOT prompt-and-json.loads."
+      - "Schema sets additionalProperties:false and lists every property in required."
+      - "Maybe-absent fields (email, discount_pct) are modeled as a nullable union with an instruction to use null when absent, so the model does not fabricate them."
+      - "Adds a post-decode value-validation step (Pydantic @field_validator / Zod .refine) for ranges, currency normalization ('$1,200' -> int), and date->ISO that the schema cannot enforce."
+      - "Any reask/retry on validation failure is BOUNDED (e.g. max_retries=2) and logged, never an unbounded loop."
+      - "Explicitly distinguishes 'valid JSON' (decoding) from 'correct values' (validation) and assigns each failure mode to the rung that catches it."
+      - "Uses current APIs, not the deprecated Anthropic output_format / structured-outputs-2025-11-13 header."