# documentation_standards.md
---
otto:
  rule:
    alwaysApply: true
    description: 
      Require documentation for all components and flows
      as they are created.
---

## Documentation Requirements

Every flow you create or modify must include a README with the following sections:

### Required fields:
- Description: WHAT it does and WHY it exists
- Business context: who consumes this data and for what
- Owner: team or person responsible for maintenance
- Input/output: expected schemas and data sources

### For SQL transformation components always include:
- Header comment with purpose and grain
- Inline comments on non-obvious business logic
- Document any hardcoded values with reasoning

### For Python components always include:
- Module-level docstring with component purpose
- Google-style docstrings on all functions
- Type hints on all parameters

If modifying an undocumented component, add docs first.

# sql_style.md
---
otto:
  rule:
    alwaysApply: false
    description:
      Enforce our team's SQL style conventions when writing
      or reviewing any SQL code in this project.
    globs:
      - *.sql
---

## Our SQL Style Guide

### Formatting:
- Use uppercase for all SQL keywords (SELECT, FROM, WHERE)
- Use trailing commas in SELECT column lists
- One column per line in SELECT statements
- Indent JOIN and WHERE clauses by 2 spaces

### Structure:
- Prefer CTEs (WITH clauses) over nested subqueries
- Name CTEs descriptively (filtered_orders, not t1)
- Always alias tables and reference columns with aliases
- Never use SELECT * — always list columns explicitly

### Comments:
- Add a header comment explaining the transform's purpose
- Comment any non-obvious business logic inline
- Document hardcoded values with business context

✅ Good:
-- Calculate monthly revenue by product category
with monthly_orders as (
  SELECT
    o.product_category,
    DATE_TRUNC('month', o.order_date) as order_month,
    SUM(o.revenue) as total_revenue,
  FROM orders as o
  WHERE o.status = 'completed'
  GROUP BY 1, 2
)

# python_standards.md
---
otto:
  rule:
    alwaysApply: false
    description: 
      Enforce our team's Python coding standards when writing
      or reviewing Python components.
    globs:
      - *.py
---

## Our Python Standards

### Naming:
- snake_case for variables and functions
- PascalCase for classes
- UPPER_SNAKE_CASE for constants
- Prefix private helpers with underscore

### Functions:
- Google-style docstrings on all public functions
- Type hints on all parameters and return values
- Max line length: 88 characters (Black standard)
- Use f-strings for formatting, never .format() or %

### Error handling:
- Catch specific exceptions — never bare except
- Log errors with context (component name, input params)
- Write error messages a human can act on immediately

### Imports:
- Group: stdlib → third-party → local, with blank lines
- Alphabetize within each group
- No wildcard imports (from x import *)

# naming_conventions.md
---
otto:
  rule:
    alwaysApply: true
    description: 
      Enforce our org's naming conventions when creating or
      renaming flows, components, tables, and columns.
---

## Our Naming Standards

### Flows:
- Format: {domain}_{purpose} (e.g., sales_daily_rollup)
- Always lowercase snake_case
- Keep it under 40 characters

### Components:
- Read: src_{source}_{entity} (e.g., src_postgres_orders)
- Staging: stg_{entity} (light cleaning, renaming)
- Intermediate: int_{purpose} (joins, business logic)
- Final: fct_{entity} (facts) or dim_{entity} (dimensions)
- Write: out_{destination}_{entity}

### Columns:
- Always snake_case
- Booleans: prefix with is_ or has_ (is_active, has_subscription)
- Dates: suffix with _date (order_date, created_date)
- Timestamps: suffix with _at (updated_at, processed_at)
- IDs: suffix with _id (user_id, order_id)
- Counts: prefix with count_ or suffix _count
- Never abbreviate unless universally understood

# metric_definitions.md
---
otto:
  rule:
    alwaysApply: false
    description: 
      Canonical definitions for key business metrics. Otto must
      use these exact definitions when building transforms that
      calculate or reference these metrics.
    keywords:
      - metric
      - revenue
      - active user
      - churn
      - KPI
      - definition
---

## Our Metric Definitions

When Otto builds transforms involving these metrics, it must
use these exact definitions. No exceptions without approval.

### Active User:
- Definition: User who logged in at least once in the last 30 days
- Table: dim_users
- Filter: last_login_at >= current_date - interval '30 days'
- Excludes: internal/test accounts (is_internal = false)

### Revenue (Net):
- Definition: Gross revenue minus refunds and credits
- Formula: gross_revenue - refund_amount - credit_amount
- Currency: Always USD, converted at transaction-date rates
- Excludes: trial periods, internal test transactions

### Churn Rate (Monthly):
- Definition: Users active last month who are inactive this month
- Formula: churned_users / prior_month_active_users
- Excludes: users on pause, seasonal accounts

-- ✏️ Customize: Replace these with YOUR team's actual
-- metric definitions. Add as many as your org needs.

# git_standards.md
---
otto:
  rule:
    alwaysApply: true
    description:
      Enforce our team's Git commit standards
      for all changes Otto makes.
---

## Commit Message Format

- Format: type(scope): short description
- Types: feat, fix, refactor, docs, test, chore
- Scope: component or flow name affected
- Under 72 characters, imperative mood

### Examples:
feat(orders-flow): add incremental processing strategy
fix(user-transform): resolve null handling in email field
docs(revenue-pipeline): add metric definition comments

## Commit Squash & Sync Template

Every squashed commit must include:

- **What changed**: Brief summary of the change
- **Why**: Business context or ticket reference
- **How to test**: Steps to verify the change works
- **Impact**: Downstream effects or breaking changes
- **Reviewer notes**: Anything the reviewer should know

# communication_style.md
---
otto:
  rule:
    alwaysApply: true
    description: 
      Define how Otto communicates with our team.
---

## How Otto Should Communicate

### Default response style:
- Lead with the answer, then explain if needed
- Use bullet points for lists of 3+ items
- Keep responses concise — skip the preamble
- Use code blocks for any SQL, Python, or YAML

### When presenting options:
- List no more than 3 options
- Include a recommendation with a brief rationale
- Note tradeoffs (cost, complexity, time)

### When flagging risks:
- Use clear severity labels: ⚠️ Warning, 🔴 Critical
- Explain the potential impact in business terms
- Always suggest a mitigation or next step

### Before making changes:
- Always summarize what will change before doing it
- Ask for confirmation on destructive operations
- Never deploy to production without human approval

# incident_reporting.md
---
otto:
  rule:
    alwaysApply: false
    description: 
      Define how Otto reports pipeline failures and data
      quality issues. Use a structured template that includes
      root cause, impact, and next steps.
    keywords:
      - failure, incident, alert, broken, error, outage
---

## Incident Report Format

When reporting a pipeline failure or data issue,
you must use this structure:

### 1. Summary (1 sentence):
- What failed, when, and severity level

### 2. Root Cause:
- What went wrong and why
- Link to the specific component or flow

### 3. Blast Radius:
- Which downstream tables/dashboards are affected
- Which teams or stakeholders should be notified

### 4. Current Status:
- Is data stale, missing, or incorrect?
- Last successful run timestamp

### 5. Recommended Action:
- Suggested fix with steps
- Estimated time to resolution
- Whether it requires human intervention

# slack_notifications.md
---
otto:
  rule:
    alwaysApply: false
    description: 
      Define when and where Otto should send Slack
      notifications, and how messages should be formatted.
    keywords:
      - notify, slack, alert, notification, message
---

## Slack Notification Standards

### Channel routing:
- Pipeline failures → #data-alerts
- Successful deployments → #data-releases
- Data quality issues → #data-quality
- General updates → #data-team

### Message format:
- Lead with severity emoji: ✅ 🟡 🔴
- One-line summary, then details in thread
- Include direct links to the affected component
- Tag the component owner, not @channel

### Do NOT notify for:
- Successful routine pipeline runs
- Auto-resolved transient errors
- Dev environment changes

-- ✏️ Customize: Replace channel names and routing
-- rules with your team's actual Slack workspace setup.