teleo-infrastructure/.agents/skills/teleo-db-operator/SKILL.md

name	description
teleo-db-operator	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

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;

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

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