feat(skills): wren-usage memory-aware rewrite + new wren-enrich-context

docs/core/guides/refine.md

@@ -32,7 +32,7 @@ Without the `memory` extra, the memory commands below will not be available.
 
 ## The flow today
 
-The day-to-day refinement loop runs entirely on the `wren-usage` skill plus a few `wren memory` and `instructions.md` edits. Nothing requires a separate enrichment skill — that is on the roadmap (see [Coming soon](#coming-soon-wren-enrich-context) below).
+The day-to-day refinement loop runs on the `wren-usage` skill plus a few `wren memory` and `instructions.md` edits. When you need to go deeper than incremental edits — backfilling enum meanings, units, default filters, synonyms, or named metrics across a whole project — reach for the [`wren-enrich-context`](#wren-enrich-context) skill described below.
 
 ### 1. Capture business rules in `instructions.md`
 
@@ -108,14 +108,16 @@ Three commands to keep memory tidy:
 
 See the [CLI reference](/oss/reference/cli) for the full memory command surface.
 
-## Coming soon: `wren-enrich-context`
+## `wren-enrich-context`
 
-A dedicated `wren-enrich-context` skill is in **active development**. It will surface two structured modes for going deeper than `instructions.md` edits:
+The `wren-enrich-context` skill goes deeper than incremental `instructions.md` edits. It reads everything you drop into `<project>/raw/` (PDFs, glossaries, handbooks, analyst SQL, data dictionaries), compares it against the current MDL / `instructions.md` / `queries.yml` / memory, and fills the gaps — writing back only to reviewable, version-controlled artifacts. It works from a ten-category gap catalog: enum value meanings, units, NULL semantics, magic sentinels, default filters, synonyms, time conventions, cross-system identifiers, currency rules, and canonical-table preferences. Named aggregation metrics (ARR, churn, DAU) are proposed as cubes.
 
-- **Grill mode** — the agent walks the MDL one piece at a time and asks focused questions ("Which of `customers`, `customers_v3`, `loyalty_v3` is canonical?", "What does `status = 4` mean?"). You answer in plain language; the agent patches MDL, `instructions.md`, `queries.yml`, or memory based on the answer category.
-- **Auto-pilot mode** — drop docs, glossaries, SQL history, or a metric handbook into `<project>/raw/` and the agent reads them, proposes context changes with evidence, and surfaces a diff for review. Nothing writes to production context without your approval.
+Pick one of two modes at session start:
 
-Until that ships, the flow above (manual `instructions.md` edits + `wren-usage` loop + `queries.yml` curation) covers the same ground. Watch the [WrenAI repo](https://github.com/Canner/WrenAI) for updates.
+- **Grill mode** — the agent walks each gap one question at a time and asks focused questions ("Which of `customers`, `customers_v3`, `loyalty_v3` is canonical?", "What does `status = 4` mean?"). You answer in plain language; the agent drafts the change and patches MDL, `instructions.md`, `queries.yml`, or memory based on the answer category. With your OK, it can also sample low-cardinality columns from the live DB to discover enum and sentinel values.
+- **Auto-pilot mode** — drop docs, glossaries, SQL history, or a metric handbook into `<project>/raw/` and the agent reads them, applies its best inferences directly, and escalates to grill only on raw-vs-MDL conflicts and high-blast-radius additions (new cubes / views / relationships). It hands you a confidence-tagged audit at the end.
+
+Both modes only **add** — they never modify an existing field; contradictions are surfaced on a "please fix manually" list. Install it with the other skills (`npx skills add Canner/WrenAI --skill wren-enrich-context`) and trigger it by saying "enrich context" or "grill me on this project". See the [skills reference](/oss/reference/skills#wren-enrich-context) for the full breakdown.
 
 ## See also
 

docs/core/reference/skills.md

@@ -9,6 +9,7 @@ Wren AI provides **skills** — reusable AI agent workflow guides that teach Cla
 | **wren-onboarding** | Entry point: environment checks, project scaffolding, profile setup, first query |
 | **wren-generate-mdl** | One-time setup: explore database schema, normalize types, scaffold MDL YAML project |
 | **wren-usage** | Day-to-day workflow: gather schema context, recall past queries, write SQL, execute, store results |
+| **wren-enrich-context** | Deepen business context the schema can't carry: enum/unit/null semantics, default filters, synonyms, currency rules, and named aggregation metrics as cubes — via grill or auto-pilot mode |
 | **wren-dlt-connector** | Connect SaaS APIs (HubSpot, Stripe, Salesforce, GitHub, Slack, …) into DuckDB via dlt, then auto-generate a Wren project |
 
 ## Installation
@@ -158,6 +159,47 @@ The skill includes two reference documents loaded on demand:
 
 ---
 
+## wren-enrich-context
+
+The "enrich deep" companion to `wren-usage`. A schema-generated MDL only carries what the database can describe about itself — column names and types. The business meaning (what `status = 'A'` means, whether `amount` is in cents, which table is canonical, how the team defines ARR) lives in handbooks, glossaries, and analyst SQL. This skill brings that meaning into the project's reviewable context.
+
+### Two modes (chosen at session start)
+
+| Mode | Behavior | Best for |
+|------|----------|----------|
+| **Grill** | Walks each gap one question at a time, proposes a concrete draft, waits for accept / edit / skip. May sample low-cardinality columns from the live DB (with your OK) to discover enum and sentinel values. | Sensitive data, or when you want to review every change |
+| **Auto-pilot** | Reads `raw/` + current context, applies its best inferences directly, escalates to grill only on raw-vs-MDL conflicts and high-blast-radius additions (new cubes / views / relationships). Hands you a confidence-tagged audit at the end. | Bulk backfill from a large doc set |
+
+Both modes only **add** — they never modify an existing field. Contradictions are surfaced on a "please fix manually" list.
+
+### What it fills
+
+The skill works from a ten-category gap catalog covering the business semantics a schema can't express:
+
+| Sink | Categories |
+|------|-----------|
+| Column `properties.description` (prose + `[tag]` line) | enum value meanings, units (USD vs cents), NULL semantics, magic sentinels, time-grain / TZ conventions |
+| `instructions.md` (fixed `##` sections) | soft-delete default filters, business synonyms, cross-system identifiers, currency rules, canonical-table preferences |
+| `cubes/<name>/metadata.yml` | named aggregation metrics (ARR, churn, DAU) — proposed as cubes, the preferred aggregation primitive |
+| `queries.yml` / `wren memory store` | canonical and ad-hoc NL→SQL pairs |
+
+### When to trigger
+
+The skill activates on phrases like:
+
+- "enrich context" / "augment my project" / "grill me on this project"
+- "the agent doesn't understand our docs / enum values / units"
+- "what does `status = A` mean" / "is this amount in USD or cents"
+- "we keep getting wrong aggregations" / "add cubes for ARR / DAU / churn"
+- "we have a handbook / glossary / data dictionary the agent should know"
+
+### Reference files
+
+- **gap_catalog.md** — the ten gap categories with triggers, default sinks, and the prose-first `[tag]` write format.
+- **cube_proposals.md** — the decision tree for proposing a cube vs view vs calculated column, the cube YAML template, naming policy, duplication guard, and validation flow.
+
+---
+
 ## wren-generate-mdl
 
 A one-time setup skill that walks the agent through creating an MDL project from a live database.
@@ -257,6 +299,11 @@ Skills are installed to `~/.claude/skills/` with this layout:
 │   └── references/
 │       ├── memory.md          # Memory command decision logic
 │       └── wren-sql.md        # CTE rewrite pipeline reference
+├── wren-enrich-context/
+│   ├── SKILL.md              # Two-mode (grill / auto-pilot) context enrichment
+│   └── references/
+│       ├── gap_catalog.md     # Ten business-semantic gap categories
+│       └── cube_proposals.md  # When/how to propose cubes for aggregation metrics
 └── wren-dlt-connector/
     ├── SKILL.md              # SaaS-via-dlt → DuckDB → Wren project
     ├── references/

skills/SKILLS.md

@@ -57,6 +57,41 @@ Generates a Wren MDL project by exploring a live database using whatever tools a
 
 ---
 
+## wren-enrich-context
+
+**File:** [wren-enrich-context/SKILL.md](wren-enrich-context/SKILL.md)
+
+Augments a Wren project with the business context that DB schema cannot carry. The session starts by asking the user to pick one of two modes:
+
+- **Grill mode** — one question at a time, agent proposes a draft, user accepts / edits / skips.
+- **Auto-pilot mode** — agent reads `raw/` + current context, applies best inferences directly, escalates to grill only on raw-vs-MDL conflicts and high-blast-radius additions (new metrics / views / relationships), and hands the user a confidence-tagged audit at the end.
+
+Both modes read everything under `<project>/raw/` (PDFs, glossaries, handbooks, code, data dictionaries), compare against the current MDL / `instructions.md` / `queries.yml` / memory pairs, then fill missing relationships, metrics, views, default filters, business rules, and NL→SQL patterns. Confirmed findings are written back to the right sink — **only adds, never modifies existing fields**.
+
+### When to use
+
+- After scaffolding an MDL when the agent still doesn't grasp business semantics
+- When the user has handbooks / glossaries / financial reports / data dictionaries the agent should know
+- When schema-derived MDL is too thin to drive accurate SQL generation
+- When the user wants to commit project-wide rules (e.g., "user means type=default by default") into a place the agent will see them
+
+### Sinks
+
+| Sink | Type of finding |
+|------|-----------------|
+| MDL YAML | Schema structure, relationships, metrics, views, descriptions |
+| `instructions.md` | Default filters, implicit rules, business conventions |
+| `queries.yml` | Canonical NL→SQL pairs (git-trackable, team-shared) |
+| `wren memory store` (only when memory extra installed) | Ad-hoc user-local NL→SQL pairs |
+
+### Dependent skills
+
+| Skill | Purpose |
+|-------|---------|
+| `wren-generate-mdl` | Generate the initial MDL before context augmentation |
+
+---
+
 ## wren-dlt-connector
 
 **File:** [wren-dlt-connector/SKILL.md](wren-dlt-connector/SKILL.md)
@@ -93,4 +128,5 @@ Then invoke in your AI client:
 ```
 /wren-usage
 /wren-generate-mdl
+/wren-enrich-context
 ```

skills/index.json

@@ -83,6 +83,28 @@
         "wren-generate-mdl"
       ],
       "repository": "https://github.com/Canner/WrenAI/tree/main/skills/wren-usage"
+    },
+    {
+      "name": "wren-enrich-context",
+      "version": "1.0",
+      "description": "Augment a Wren project with business context that DB schema cannot carry — enum value meanings, units (USD vs cents, ms vs sec), NULL semantics, magic sentinels, soft-delete default filters, business synonyms, time-grain / TZ conventions, cross-system identifiers, currency rules, canonical-table preferences, and named aggregation metrics (ARR, churn, DAU) proposed as cubes. Two modes: `grill` (one question at a time) or `auto-pilot` (agent infers and applies, escalates on conflicts and high-blast-radius additions like new cubes / views / relationships). Reads raw/ (PDFs, glossaries, handbooks, code, data dictionaries) and optionally samples low-cardinality columns from the live DB (grill mode), compares against MDL / cubes / instructions.md / queries.yml / memory pairs, fills gaps via a ten-category gap catalog and a cube proposal flow. Only adds, never modifies existing fields.",
+      "tags": [
+        "wren",
+        "context",
+        "mdl",
+        "enrich",
+        "grill",
+        "auto-pilot",
+        "business-rules",
+        "instructions",
+        "queries",
+        "memory",
+        "semantic-layer"
+      ],
+      "dependencies": [
+        "wren-generate-mdl"
+      ],
+      "repository": "https://github.com/Canner/WrenAI/tree/main/skills/wren-enrich-context"
     }
   ]
 }

skills/install.sh

@@ -13,7 +13,7 @@ set -euo pipefail
 REPO="Canner/WrenAI"
 BRANCH="${WREN_SKILLS_BRANCH:-main}"
 DEST="${CLAUDE_SKILLS_DIR:-$HOME/.claude/skills}"
-ALL_SKILLS=(wren-dlt-connector wren-generate-mdl wren-onboarding wren-usage)
+ALL_SKILLS=(wren-dlt-connector wren-enrich-context wren-generate-mdl wren-onboarding wren-usage)
 
 # Parse --force flag and skill list from arguments
 FORCE=false

skills/versions.json

@@ -1,6 +1,7 @@
 {
   "wren-dlt-connector": "1.0",
   "wren-generate-mdl": "2.3",
+  "wren-enrich-context": "1.0",
   "wren-onboarding": "2.2",
   "wren-usage": "2.4"
 }