.sureops/runbooks/. The Diagnosis Specialist, Incident Commander, Resolution Specialist, and Verification Specialist automatically retrieve and read the most relevant runbooks for each incident — you don’t need to explicitly point agents at a runbook. sureops uses hybrid search to find the best match based on the incident’s symptoms, alerts, and affected services.
How agents use runbooks
During diagnosis, the agent:- Generates a query based on the incident’s alert labels, affected services, and current symptoms
- Runs a hybrid search (semantic + keyword) across all runbooks in your knowledge base
- Retrieves the top-matching runbooks and includes them as grounding context in its analysis
Naming conventions
Runbooks live in.sureops/runbooks/ and use the filename as a searchable identifier. Recommended naming patterns:
services.yaml via the runbook field for browsing/documentation purposes, but retrieval itself doesn’t use that link — it works off the runbook’s own services: frontmatter (see the field reference below). Pattern-based runbooks (high-error-rate.md, connection-pool-exhaustion.md, etc.) are found the same way, through hybrid search — but only if their services: frontmatter lists every service the pattern could apply to. A pattern-based runbook with no services: list is excluded from retrieval for any incident where the affected service is known — it will never surface at diagnosis time, no matter how well its content matches.
Frontmatter schema
Frontmatter fields help the retrieval layer rank and filter results. All are technically optional, butservices is effectively mandatory: when an incident’s affected service is known, retrieval excludes any runbook whose services: list doesn’t include it (see the field reference below). title is genuinely optional but also meaningfully improves retrieval accuracy.
severity is not a recognized frontmatter field — nothing reads it today, so it won’t filter or boost anything. Leave it out.
Content best practices
Use the canonical section structure
Structure your runbooks as: Summary, Symptoms, Diagnosis, Remediation, Rollback, References (Rollback and References are optional; the rest are expected). Match this structure across your own runbooks rather than inventing your own headings per file — a consistent shape makes your knowledge base easier to scan and keep current. The scaffold sureops generates via Generate starter contract follows this same structure.
Set frontmatter summary: explicitly rather than relying on a ## Summary heading — the mechanism is: an explicit frontmatter summary: always wins if present; only when it’s absent does sureops fall back to the first non-empty paragraph anywhere in the body (not specifically one under a ## Summary heading), truncated to 500 characters. So a ## Summary heading is a good authoring convention for humans, but it isn’t what sureops actually reads — a runbook whose first paragraph happens to sit under a different heading (or no heading at all) gets that paragraph as its summary regardless. Whichever way the summary is derived, keep it tight — a sentence or two — since it’s stored as its own field on the runbook row and feeds the keyword side of retrieval (title + summary + full content are combined into the search index used for keyword matching). The semantic side embeds the full cleaned content only — title and summary aren’t separately embedded. Either way, a vague or missing summary weakens the keyword-search half of retrieval.
Be action-oriented
Agents are better at following specific instructions than at interpreting vague guidance. Prefer:Include service-specific error patterns
Agents benefit from knowing what errors your service typically surfaces during failures — fold these into your## Symptoms section:
Link to dashboards
When you reference a dashboard, include the URL directly. Agents can include it in their output so responders can navigate there without searching:Include remediation steps with commands
For procedures you want the Resolution Specialist to be able to propose, put them under## Remediation. Because this example itself contains a fenced shell command, wrap the outer example in four backticks so the inner triple-backtick fence doesn’t close it early:
The knowledge base
The knowledge base is the collection of all your runbooks, indexed and stored as vector embeddings. Every time you push a change to.sureops/runbooks/, sureops re-indexes the affected files.
Verifying retrieval
During the diagnosis stage of an incident, check for the “Customer Runbooks Referenced” card: it lists each matched runbook by title with a relevance-score badge, linking to the source file. This card renders only when there’s a match — there’s no “no matching runbook found” message, so if the card is absent, treat that as “nothing matched” and consider whether a runbook should exist for this pattern (or whether an existing one’s content/frontmatter needs tightening so it matches next time).Keeping runbooks fresh
Stale runbooks can mislead agents. A runbook that describes an old architecture or outdated procedures is worse than no runbook at all. Recommended practices:- Set the
last_validatedfrontmatter field as your own team’s convention and review runbooks that haven’t been touched in 90+ days — sureops shows it on the citation but doesn’t flag staleness itself, so reviewing for it is a process you run, not one sureops runs for you - After a major incident where the runbook was inaccurate, update it as part of closure
- After a successful postmortem, consider whether the postmortem learnings should be folded back into the runbook