feat: rewrite builder prompt with skills-first architecture and surface altimate_core tools

- Restructure `builder.txt` from flat tool list to skills-first architecture
- Surface 6 `altimate_core` offline SQL analysis tools (validate, semantics, lint, column_lineage, correct, grade)
- Add structured 5-phase workflow: Explore → Plan → Analyze → Execute → Validate
- Add Common Pitfalls section from benchmark failure analysis
- Fix dbt-tools CLI: improve error handling in `columns`, `init`, and main dispatch
- Update dbt-develop and dbt-troubleshoot skills with `altimate-dbt` references

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: suryaiyer95

.opencode/skills/dbt-develop/SKILL.md

@@ -33,28 +33,48 @@ Before writing any SQL:
 - Read the task requirements carefully
 - Identify which layer this model belongs to (staging, intermediate, mart)
 - Check existing models for naming conventions and patterns
+- **Check dependencies:** If `packages.yml` exists, check for `dbt_packages/` or `package-lock.yml`. Only run `dbt deps` if packages are declared but not yet installed.
 
 ```bash
 altimate-dbt info                           # project name, adapter type
 altimate-dbt parents --model <upstream>     # understand what feeds this model
 altimate-dbt children --model <downstream>  # understand what consumes it
 ```
 
-### 2. Discover — Know Your Data
+### 2. Discover — Understand the Data Before Writing
 
-Never write SQL without knowing the columns:
+**Never write SQL without deeply understanding your data first.** The #1 cause of wrong results is writing SQL blind — assuming grain, relationships, column names, or values without checking.
+
+**Step 2a: Read all documentation and schema definitions**
+- Read `sources.yml`, `schema.yml`, and any YAML files that describe the source/parent models
+- These contain column descriptions, data types, tests, and business context
+- Pay special attention to: primary keys, unique constraints, relationships between tables, and what each column represents
+
+**Step 2b: Understand the grain of each parent model/source**
+- What does one row represent? (one customer? one event? one day per customer?)
+- What are the primary/unique keys?
+- This is critical for JOINs — joining on the wrong grain causes fan-out (too many rows) or missing rows
 
 ```bash
 altimate-dbt columns --model <name>                         # existing model columns
 altimate-dbt columns-source --source <src> --table <tbl>    # source table columns
-altimate-dbt column-values --model <name> --column <col>    # sample values
+altimate-dbt execute --query "SELECT count(*) FROM {{ ref('model') }}" --limit 1
 altimate-dbt execute --query "SELECT * FROM {{ ref('model') }}" --limit 5
+altimate-dbt column-values --model <name> --column <col>    # sample values for key columns
 ```
 
-Read existing models in the same directory to match patterns:
+**Step 2c: Query the actual data to verify your understanding**
+- Check row counts, NULLs, date ranges, cardinality of key columns
+- Verify foreign key relationships actually hold (do all IDs in child exist in parent?)
+- Check for duplicates in what you think are unique keys
+
+**Step 2d: Read existing models that your new model will reference**
+- Read the actual SQL of parent models — understand their logic, filters, and transformations
+- Read 2-3 existing models in the same directory to match patterns and conventions
+
 ```bash
 glob models/**/*.sql     # find all model files
-read <model_file>        # understand existing patterns
+read <model_file>        # understand existing patterns and logic
 ```
 
 ### 3. Write — Follow Layer Patterns
@@ -64,20 +84,37 @@ See [references/medallion-architecture.md](references/medallion-architecture.md)
 See [references/incremental-strategies.md](references/incremental-strategies.md) for incremental materialization.
 See [references/yaml-generation.md](references/yaml-generation.md) for sources.yml and schema.yml.
 
-### 4. Validate — Always Build After Writing
+### 4. Validate — Build, Verify, Check Impact
 
 Never stop at writing the SQL. Always validate:
 
+**Build it:**
 ```bash
 altimate-dbt compile --model <name>                        # catch Jinja errors
 altimate-dbt build --model <name>                          # materialize + run tests
-altimate-dbt execute --query "SELECT * FROM {{ ref('<name>') }}" --limit 10  # spot-check
 ```
 
-If building downstream too:
+**Verify the output:**
+```bash
+altimate-dbt columns --model <name>                        # confirm expected columns exist
+altimate-dbt execute --query "SELECT count(*) FROM {{ ref('<name>') }}" --limit 1
+altimate-dbt execute --query "SELECT * FROM {{ ref('<name>') }}" --limit 10  # spot-check values
+```
+- Do the columns match what schema.yml or the task expects?
+- Does the row count make sense? (no fan-out from bad joins, no missing rows from wrong filters)
+- Are values correct? (spot-check NULLs, aggregations, date ranges)
+
+**Check SQL quality** (on the compiled SQL from `altimate-dbt compile`):
+- `sql_analyze` — catches anti-patterns (SELECT *, cartesian products, missing filters)
+- `altimate_core_validate` — validates syntax and schema references
+- `altimate_core_column_lineage` — traces how source columns flow to output columns. Use this to verify your SELECT is pulling the right columns from the right sources, especially for complex JOINs or multi-CTE models.
+
+**Check downstream impact** (when modifying an existing model):
 ```bash
-altimate-dbt build --model <name> --downstream
+altimate-dbt children --model <name>                       # who depends on this?
+altimate-dbt build --model <name> --downstream             # rebuild downstream to catch breakage
 ```
+Use `altimate-dbt children` and `altimate-dbt parents` to verify the DAG is intact when changes could affect downstream models.
 
 ## Iron Rules
 

.opencode/skills/dbt-troubleshoot/SKILL.md

@@ -40,6 +40,7 @@ If `doctor` fails, fix the environment first. Common issues:
 - Python not found → reinstall or set `--python-path`
 - dbt-core not installed → `pip install dbt-core`
 - No `dbt_project.yml` → wrong directory
+- Missing packages → if `packages.yml` exists but `dbt_packages/` doesn't, run `dbt deps`
 
 ### Step 2: Classify the Error
 

packages/dbt-tools/src/commands/columns.ts

@@ -3,15 +3,29 @@ import type { DBTProjectIntegrationAdapter } from "@altimateai/dbt-integration"
 export async function columns(adapter: DBTProjectIntegrationAdapter, args: string[]) {
   const model = flag(args, "model")
   if (!model) return { error: "Missing --model" }
-  return adapter.getColumnsOfModel(model)
+  try {
+    const result = await adapter.getColumnsOfModel(model)
+    if (!result) return { error: `Model '${model}' not found in manifest. Try: altimate-dbt execute --query "SELECT * FROM ${model} LIMIT 1"` }
+    return result
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e)
+    return { error: `Failed to get columns for '${model}': ${msg}. Try: altimate-dbt execute --query "SELECT * FROM ${model} LIMIT 1"` }
+  }
 }
 
 export async function source(adapter: DBTProjectIntegrationAdapter, args: string[]) {
   const name = flag(args, "source")
   const table = flag(args, "table")
   if (!name) return { error: "Missing --source" }
   if (!table) return { error: "Missing --table" }
-  return adapter.getColumnsOfSource(name, table)
+  try {
+    const result = await adapter.getColumnsOfSource(name, table)
+    if (!result) return { error: `Source '${name}.${table}' not found. Try: altimate-dbt execute --query "SELECT * FROM ${table} LIMIT 1"` }
+    return result
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e)
+    return { error: `Failed to get columns for source '${name}.${table}': ${msg}` }
+  }
 }
 
 export async function values(adapter: DBTProjectIntegrationAdapter, args: string[]) {

packages/dbt-tools/src/commands/init.ts

@@ -36,7 +36,7 @@ export async function init(args: string[]) {
   const cfg: Config = {
     projectRoot: project,
     pythonPath: py ?? python(),
-    dbtIntegration: "core",
+    dbtIntegration: "corecommand",
     queryLimit: 500,
   }
 

packages/dbt-tools/src/index.ts

@@ -1,4 +1,6 @@
-import { read } from "./config"
+import { join, resolve } from "path"
+import { existsSync } from "fs"
+import { read, type Config } from "./config"
 import { init } from "./commands/init"
 import { validate } from "./check"
 
@@ -27,6 +29,11 @@ const USAGE = {
 const cmd = process.argv[2]
 const rest = process.argv.slice(3)
 
+function flag(args: string[], name: string): string | undefined {
+  const i = args.indexOf(`--${name}`)
+  return i >= 0 ? args[i + 1] : undefined
+}
+
 function diagnose(err: Error): { error: string; fix?: string } {
   const msg = err.message || String(err)
   if (msg.includes("private field") || msg.includes("#stdin") || msg.includes("#stdout")) {
@@ -102,6 +109,17 @@ async function main() {
   const cfg = await read()
   if (!cfg) return { error: "No config found. Run: altimate-dbt init" }
 
+  // Override projectRoot: --project-dir flag > cwd auto-detect > config
+  const dirFlag = flag(rest, "project-dir")
+  if (dirFlag) {
+    cfg.projectRoot = resolve(dirFlag)
+  } else {
+    const cwdProject = join(process.cwd(), "dbt_project.yml")
+    if (existsSync(cwdProject) && resolve(process.cwd()) !== resolve(cfg.projectRoot)) {
+      cfg.projectRoot = resolve(process.cwd())
+    }
+  }
+
   if (cmd === "doctor") return (await import("./commands/doctor")).doctor(cfg)
 
   // Validate prerequisites before loading the heavy adapter

packages/opencode/src/altimate/index.ts

@@ -45,7 +45,7 @@ export * from "./tools/altimate-core-validate"
 export * from "./tools/dbt-lineage"
 export * from "./tools/dbt-manifest"
 export * from "./tools/dbt-profiles"
-export * from "./tools/dbt-run"
+
 export * from "./tools/finops-analyze-credits"
 export * from "./tools/finops-expensive-queries"
 export * from "./tools/finops-query-history"