# Dbt Knowledgebase

> Populate the knowledge base from dbt project research. Proposes entries across all 6 categories at org, project, and connection scopes.

- Skill: `signalpilot-labs/dbt-knowledgebase-4` (Agent Skill)
- Install (CLI): `npx skillmds@latest add signalpilot-labs/dbt-knowledgebase-4`
- Raw SKILL.md: https://api.skillmd.com/api/skills/signalpilot-labs/dbt-knowledgebase-4/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- Author: signalpilot-labs (https://skillmd.com/u/signalpilot-labs)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/signalpilot-labs/dbt-knowledgebase-4

---


# dbt Knowledge Base Generator

## Purpose

Populate the knowledge base with structured entries from your research.
After completing exploration (Steps 1-5 of the workflow), propose entries
across ALL categories and scopes below. Every category MUST have at least
one entry after this step - even if it is an initial summary based on what
you observed.

## Knowledge Categories

### understanding - The onboarding doc

Scope: `org` AND `project`. Always loaded at the start of every run.

The 30-second briefing a new analyst needs before touching anything.

**At org level** (`scope="org"`): company terminology, fiscal calendar,
universal join keys, database engine. If no org-level understanding exists,
create one summarizing what you can infer from this project - the database
type, general data domain, naming patterns.

**At project level** (`scope="project"`): what the pipeline models, key
entities, data flow, how many models, what the task is about.

Example: "This project models Reddit post and comment data from paranormal
subreddits. Two mart models join posts to comments via post URL. Source
data is in DuckDB with 3 raw tables."

### conventions - The style guide

Scope: `org` AND `project`. Always loaded alongside understanding docs.

How this team writes SQL and organizes models. Not data facts - patterns
about how to work with data.

**At org level**: database-wide SQL patterns (e.g., materialization
strategy, column casing). If nothing exists, create one from what you
observe in this project's existing models.

**At project level**: project-specific patterns from sibling models -
JOIN types used, aggregation functions, column naming prefixes/suffixes,
macro usage patterns, how existing models handle NULLs.

Example: "All sibling models use LEFT JOIN for dimension tables." /
"Macro extract_hour(col) produces hour_<col> - used in existing models."

### decisions - The "why" behind a model

Scope: `project` only. Searchable by sub-agents.

Per-model reasoning from your research. Why this grain, why this driving
table, why this join type, why this filter. Document the reasoning that
saves the next agent from re-deriving the same logic.

One entry per model or per significant cross-model decision.

Example: "prod_posts_ghosts drives from stg_reddit_posts (250 rows).
LEFT JOIN not needed - single source model, no joins." /
"Join path between posts and comments is post_url, not post_id -
post_id format differs between tables (t3_ prefix in comments)."

### domain-rules - Business logic

Scope: `org` or `project`. Searchable by sub-agents.

Business rules encoded in the data that you cannot discover from schema
alone. These come from column values, status flags, data patterns.

Example: "comment score can be negative (downvoted)." /
"NULL post text means link-only post, not missing data." /
"l_returnflag values: A=accepted, N=new, R=returned."

### debugging - Known errors and fixes

Scope: `project` only. Searchable when agent hits errors.

Hard-won lessons from exploration - errors encountered during validation,
parse issues, data quality problems found.

Example: "dbt parse warns about 36 unused config paths - safe to ignore." /
"DuckDB BIGINT overflow on SUM of large integers - cast to DOUBLE."

### quirks - Database-specific surprises

Scope: `connection` only. Loaded when working with that connection.

Tied to a specific database instance. Data type mismatches, unexpected
NULLs, format oddities.

Example: "post_id in comments has t3_ prefix but posts table has bare
integer IDs." / "price column stores costs as negative values."

## Proposal Checklist

After research, create a task for EACH category below. Mark each
`in_progress` when you start proposing for that category and `completed`
when done.

1. **org:understanding** - Create or verify org-level onboarding doc
2. **org:conventions** - Create or verify org-level SQL patterns
3. **project:understanding** - Create project overview doc
4. **project:conventions** - Document sibling model patterns, macros
5. **project:decisions** - Document per-model research findings
6. **project:domain-rules** - Document business logic from data
7. **project:debugging** - Document any errors or warnings found
8. **connection:quirks** - Document data oddities for this database

For each category: call `search_knowledge` first to check if an entry
already exists. If it does, skip it. If it does not, propose one.

## Proposal Format

```
propose_knowledge(
  scope="project",
  scope_ref="<project_name>",
  category="decisions",
  title="<short-kebab-case-slug>",
  body="<detailed body with evidence>"
)
```

For org-level entries, use `scope="org"` and `scope_ref=None`.
For connection-level entries, use `scope="connection"` and
`scope_ref="<connection_name>"`.

Titles MUST be lowercase kebab-case slugs.

Body MUST include:
- WHAT: the observation or fact
- EVIDENCE: specific table, column, query result, or file

The body MUST be purely descriptive. State what EXISTS, not what to DO.

BAD IMPACT (prescriptive): "Do not add macro columns unless YML lists them."
GOOD (descriptive): "Macros produce hour_created_at and normalized_created_at
columns. These columns are not in the current YML contract."

The reader (a future builder agent) decides what to do with the fact.
You only document what you found.

## Rules

- NEVER write SQL files or run dbt build commands
- NEVER modify .yml files
- NEVER propose negative claims ("X is not used", "not needed")
- NEVER write instructions in entries ("Do not", "Always", "Use X")
 - state facts only, let the reader decide
- ALWAYS check if entry exists before proposing (avoid duplicates)
- ALWAYS include EVIDENCE in the body
- Every category MUST have at least one entry after this step
- STOP after all 8 checklist items are completed