create-contextkit 0.3.2 → 0.3.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-contextkit",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Scaffold a new ContextKit project",
   "license": "MIT",
   "author": "Eric Kittelson",

package/templates/minimal/context/AGENT_INSTRUCTIONS.md

@@ -122,7 +122,93 @@ When you discover data quality issues (null values, broken joins, missing data),
 
 **Bronze (7):** descriptions, owner, security, grain, table_type
 **Silver (+6):** trust, 2+ tags, glossary linked, lineage, refresh, 2+ sample_values
-**Gold (+21):** semantic_role on ALL fields, metric aggregation/additive, 1+ guardrail, 3+ golden queries, 1+ business rule, 1+ hierarchy, 1+ default_filter, trust=endorsed, contactable owner, 1+ relationship, description >=50 chars, ai_context (no TODO), 1+ business_context, version, field descriptions not lazy, glossary definitions substantive, lineage references real sources, grain statements specific, ai_context filled in
+**Gold (+24):** semantic_role on ALL fields, metric aggregation/additive, 1+ guardrail, 3+ golden queries, 1+ business rule, 1+ hierarchy, 1+ default_filter, trust=endorsed, contactable owner, 1+ relationship, description >=50 chars, ai_context (no TODO), 1+ business_context, version, field descriptions not lazy, glossary definitions substantive, lineage references real sources, grain statements specific, ai_context filled in, 3+ relationships (models with 3+ datasets), 1+ computed metric, 3+ glossary terms (models with 5+ datasets)
+
+## How to Reach Gold: Curation Recipes
+
+### Metrics (gold/metrics-defined)
+
+Inspect computed views in the database. Any calculated column is a candidate metric.
+
+```sql
+-- Find computed columns in views
+SELECT column_name, data_type
+FROM information_schema.columns
+WHERE table_name LIKE 'vw_%' AND data_type IN ('DOUBLE', 'FLOAT', 'INTEGER', 'BIGINT', 'DECIMAL');
+```
+
+For each computed column (e.g., `opportunity_score`, `shops_per_10k`, `demand_signal_pct`):
+1. Query it to understand what it measures
+2. Add it to the model's `metrics[]` array in the OSI YAML
+3. Include the SQL expression, aggregation type (SUM/AVG), and a human description
+4. Mark whether it's additive (can be summed across dimensions)
+
+Example:
+```yaml
+metrics:
+  - name: opportunity_score
+    expression:
+      dialects:
+        - dialect: DuckDB
+          expression: "(population/10000)*2 + (income/50000)*2 + (10-shops_per_10k)*3 + transit*1.5 + demand*0.5"
+    description: Composite score ranking census tracts for coffee shop viability
+    aggregation: AVG
+    additive: false
+```
+
+### Glossary Terms (gold/glossary-coverage)
+
+For each key business concept your model measures, create a glossary term file.
+
+Think about the terms a new analyst would need defined:
+- What is "supply saturation"? (> 5.0 shops per 10k people)
+- What is a "demand signal"? (review mentioning wait/line/crowded/busy)
+- What is "opportunity score"? (composite ranking formula)
+
+For each term, create `context/glossary/<term-name>.term.yaml`:
+```yaml
+term: supply-saturation
+definition: >
+  A measure of coffee shop density per census tract. Calculated as
+  shops per 10,000 residents. Tracts with > 5.0 are considered saturated.
+owner: analytics-team
+tags: [coffee-analytics]
+```
+
+Models with 5+ datasets need at least 3 glossary terms linked by shared tags or owner.
+
+### Relationships (gold/relationships-coverage)
+
+For each join in the SQL views, define a relationship in the OSI model.
+
+```sql
+-- Find joins by examining view definitions
+-- Look for patterns: ON table_a.col = table_b.col
+-- Or spatial joins: ABS(a.lat - b.lat) < threshold
+```
+
+For each join:
+```yaml
+relationships:
+  - name: business-to-tract
+    left_dataset: yelp_business
+    right_dataset: census_tract
+    join_type: spatial
+    cardinality: many-to-one
+    description: Businesses assigned to nearest census tract within 0.02 degrees (~1 mile)
+```
+
+Models with 3+ datasets need at least 3 relationships.
+
+### Golden Queries
+
+Write 3-5 SQL queries answering common business questions. **Test each query first!**
+
+```sql
+-- Run the query, verify it returns sensible results, then document:
+SELECT geoid, tract_name, opportunity_score
+FROM vw_candidate_zones ORDER BY opportunity_score DESC LIMIT 10;
+```
 
 ## YAML Formats