---
name: teleo-db-operator
description: Use when reading, auditing, backing up, querying, or safely writing the Teleo pipeline SQLite database, including review_records, audit_log, costs, prs, sources, and contributor feedback loops.
---

# Teleo DB Operator

Default to read-only. The database is evidence for decision-engine refinement, not a scratchpad.

## Discover

1. Read `lib/config.py` for `DB_PATH` and related paths.
2. Prefer local or copied DBs over production DBs.
3. If using production, record whether access is read-only or write-authorized.
4. Never print secret values found near DB paths or shell history.

## Read Path

Use `sqlite3` or Python `sqlite3`.

Recommended read targets:

- `review_records`: evaluator, model, outcome, rejection reason.
- `audit_log`: route decisions, approve/reject events, failure details.
- `costs`: model cost by date/stage.
- `prs`: status, tier, route compatibility fields, verdicts.
- `sources`: priority, feedback, extraction model.

For refinement work, export aggregated JSON or CSV into `.crabbox-results/` or `proof/`, not raw private DB snapshots.

## Write Path

Writes require explicit authorization and a backup.

Required sequence:

1. Create a backup or operate on a copy.
2. Write the exact SQL in a retained artifact.
3. Use `BEGIN IMMEDIATE;`.
4. Apply the minimal mutation.
5. Read back the changed rows.
6. Commit the transaction only after readback is correct.
7. Write a blocker artifact instead of guessing if any precondition is missing.

Never write production prompt/model state as part of an experiment. Experiments should replay fixtures and produce proof first.

## Safety Boundaries

- Do not attach, copy, or commit `pipeline.db`.
- Do not run broad `UPDATE` or `DELETE` without a `WHERE` clause and a prior row count.
- Do not mutate `prs`, `sources`, or contributor state from a model response alone.
- Do not treat local copied DB proof as production proof.

## Useful Queries

```sql
SELECT reviewer, reviewer_model, outcome, rejection_reason, count(*) AS n
FROM review_records
GROUP BY reviewer, reviewer_model, outcome, rejection_reason
ORDER BY n DESC;
```

```sql
SELECT event, count(*) AS n
FROM audit_log
WHERE stage = 'evaluate'
GROUP BY event
ORDER BY n DESC;
```

```sql
SELECT model, stage, calls, input_tokens, output_tokens, cost_usd
FROM costs
ORDER BY date DESC, cost_usd DESC
LIMIT 50;
```