RAG pipelines: runbook as code

By Michael Samuel Naeem · March 22, 2026 · 6 min read

RAG pipelines: runbook as code means you improve retrieval precision for runbook as code — with a named owner, a measurable signal, and a rollback a tired on-call can run. I reach for this when on-call already feels weekly pain here; that is also when shortcuts like treating rag runbook as code as a pure library problem start paging people.

This write-up is specific to rag-runbook-as-code in a rag context, using pgvector, OpenSearch, OpenTelemetry for the mechanics while keeping ownership human.

Fitting RAG pipelines: runbook as code into an existing system

Teams usually discover RAG pipelines: runbook as code after a quiet failure — wrong data, slow pages, or a bill spike. Design for on-call already feels weekly pain here.

With pgvector, OpenSearch, OpenTelemetry, the mechanics are straightforward; the hard part is invariants. The anti-pattern I still see is treating rag runbook as code as a pure library problem.

Document what 'success' and 'undo' mean in product language. Future reviewers will not share your context on rag runbook as code.

Slug-specific note (rag-runbook-as-code): prioritize code behavior under load and verify with a fixture named rag-runbook-as-code-smoke.

Contracts and ownership boundaries

RAG quality is mostly retrieval and chunking; the generator cannot invent missing evidence. For rag runbook as code, that means making failure visible early.

With pgvector, OpenSearch, OpenTelemetry, the mechanics are straightforward; the hard part is invariants. The anti-pattern I still see is treating rag runbook as code as a pure library problem.

Ship behind a flag, canary by cohort, and write the rollback in the PR description. RAG pipelines: runbook as code that needs a hero is not done.

Concretely, being able to improve retrieval precision for runbook as code forces explicit choices: source of truth, timeout budgets, and which errors users see versus operators.

Slug-specific note (rag-runbook-as-code): prioritize code behavior under load and verify with a fixture named rag-runbook-as-code-smoke.

# RAG pipelines: runbook as code
from dataclasses import dataclass

@dataclass(frozen=True)
class RagRunbookAsCodeRequest:
    tenant_id: str
    idempotency_key: str

async def run_rag_runbook_as_code(req, deps) -> None:
    if await deps.store.seen(req.idempotency_key):
        return
    with deps.tracer.start_as_current_span("rag-runbook-as-code"):
        await deps.client.execute(req, timeout=2.0)
    await deps.store.mark(req.idempotency_key)

State, storage, and retention

RAG quality is mostly retrieval and chunking; the generator cannot invent missing evidence. For rag runbook as code, that means making failure visible early.

Put a metric on the user-visible effect of rag runbook as code before you optimize internals. If on-call already feels weekly pain here, you need that graph on day one.

Ship behind a flag, canary by cohort, and write the rollback in the PR description. RAG pipelines: runbook as code that needs a hero is not done.

My never-again list for rag runbook as code: treating rag runbook as code as a pure library problem; shipping without a kill switch; and alerting only on infrastructure CPU.

Slug-specific note (rag-runbook-as-code): prioritize code behavior under load and verify with a fixture named rag-runbook-as-code-smoke.

Security defaults that are non-negotiable

Teams usually discover RAG pipelines: runbook as code after a quiet failure — wrong data, slow pages, or a bill spike. Design for on-call already feels weekly pain here.

Keep side effects at the edges and make every write idempotent. RAG pipelines: runbook as code without retry semantics is a future incident write-up.

Acceptance check: an on-call engineer can explain system state for rag runbook as code from one dashboard and one runbook page.

Review prompts I use: what happens twice, what happens never, what happens partially? If RAG pipelines: runbook as code cannot answer, it is not production-ready.

Slug-specific note (rag-runbook-as-code): prioritize code behavior under load and verify with a fixture named rag-runbook-as-code-smoke.

SLOs and dashboards

I treat RAG pipelines: runbook as code as an operations problem first. The goal is to improve retrieval precision for runbook as code, not to collect frameworks.

Put a metric on the user-visible effect of rag runbook as code before you optimize internals. If on-call already feels weekly pain here, you need that graph on day one.

Ship behind a flag, canary by cohort, and write the rollback in the PR description. RAG pipelines: runbook as code that needs a hero is not done.

Slug-specific note (rag-runbook-as-code): prioritize code behavior under load and verify with a fixture named rag-runbook-as-code-smoke.

Related reading:

• idempotency distributed systems
• saga pattern distributed transactions
• designing for observability slos

First-week validation plan

Teams usually discover RAG pipelines: runbook as code after a quiet failure — wrong data, slow pages, or a bill spike. Design for on-call already feels weekly pain here.

Put a metric on the user-visible effect of rag runbook as code before you optimize internals. If on-call already feels weekly pain here, you need that graph on day one.

Document what 'success' and 'undo' mean in product language. Future reviewers will not share your context on rag runbook as code.

Slug-specific note (rag-runbook-as-code): prioritize code behavior under load and verify with a fixture named rag-runbook-as-code-smoke.

Practical defaults for RAG pipelines: runbook as code

I treat RAG pipelines: runbook as code as an operations problem first. The goal is to improve retrieval precision for runbook as code, not to collect frameworks.

With pgvector, OpenSearch, OpenTelemetry, the mechanics are straightforward; the hard part is invariants. The anti-pattern I still see is treating rag runbook as code as a pure library problem.

Acceptance check: an on-call engineer can explain system state for rag runbook as code from one dashboard and one runbook page.

Slug-specific note (rag-runbook-as-code): prioritize code behavior under load and verify with a fixture named rag-runbook-as-code-smoke.

Default deny, explicit timeouts, and one dashboard row for rag runbook as code. Expand only when the metric demands it.

Review questions before merging rag runbook as code work

RAG quality is mostly retrieval and chunking; the generator cannot invent missing evidence. For rag runbook as code, that means making failure visible early.

Keep side effects at the edges and make every write idempotent. RAG pipelines: runbook as code without retry semantics is a future incident write-up.

Document what 'success' and 'undo' mean in product language. Future reviewers will not share your context on rag runbook as code.

Slug-specific note (rag-runbook-as-code): prioritize code behavior under load and verify with a fixture named rag-runbook-as-code-smoke.

In review, require a short failure note covering retry, partial deploy, and treating rag runbook as code as a pure library problem. Missing that note blocks merge.

Field notes after thirty days of rag runbook as code

I treat RAG pipelines: runbook as code as an operations problem first. The goal is to improve retrieval precision for runbook as code, not to collect frameworks.

Put a metric on the user-visible effect of rag runbook as code before you optimize internals. If on-call already feels weekly pain here, you need that graph on day one.

Ship behind a flag, canary by cohort, and write the rollback in the PR description. RAG pipelines: runbook as code that needs a hero is not done.

Slug-specific note (rag-runbook-as-code): prioritize code behavior under load and verify with a fixture named rag-runbook-as-code-smoke.

In review, require a short failure note covering retry, partial deploy, and treating rag runbook as code as a pure library problem. Missing that note blocks merge.

Resources

• Internal runbook seed: rag-runbook-as-code
• https://12factor.net/
• https://martinfowler.com/