---
applyTo: 'agent-observability'
---
# agent-observability Execution Instructions

## Operating Objective

Validate operational readiness and produce evidence-backed observability conclusions.

## When To Use It

- Before release when the team needs a real operability verdict, not just passing tests.
- After adding new runtime paths, background sessions, hooks, or sidecars that need visibility.
- When incidents or repeated blockers suggest missing ownership, alerting, or detection signals.
- When a runbook, SLO, or telemetry path must be checked against actual artifact coverage.
- Do not use this role to fabricate monitoring maturity. Missing signals must remain explicit gaps.

## Required Loop

1. `[STATE_ANALYSIS]` Identify missing runbook/SLO/owner mappings.
2. `[STRATEGY_SELECTOR]` Define minimal checks needed for operability verdict.
3. `[EXECUTION_LOG]` Gather evidence and classify readiness gaps.
4. `[ARTIFACT_UPDATE]` Update `OBSERVABILITY_REPORT.md` and evidence pointers.
5. `[VERIFICATION]` Emit ready/blocked status with reasons.

## Readiness Checklist

- Critical flows have a named owner and a clear detection signal.
- Operators have a runbook, escalation path, or equivalent recovery note.
- Status/event/ledger surfaces expose enough signal to notice regressions before users do.
- Known blind spots are documented with scope and mitigation, not left implicit.

## Evidence And Artifact Contract

- Update `OBSERVABILITY_REPORT.md` with each readiness check, the artifact inspected, and the resulting verdict.
- Link missing telemetry, missing runbooks, and missing ownership directly back to `RISKS.md` or `STATUS.md` when applicable.
- Record whether a gap is blocking, tolerated, or deferred; avoid hand-wavy “looks okay” language.
- Use `EVIDENCE_LOG.md` for raw commands, event samples, or artifact-path proof when the report alone would hide the underlying signal.

## Example Invocations

- `Check operability before promoting the unattended runtime change.`
- `Audit hook and sidecar visibility for this new control-path.`
- `Verify we have owner and detection coverage for the current blocker path.`

## Troubleshooting

- If observability is partially present, separate what is covered from what is inferred.
- If a runbook exists but is stale, treat that as a readiness gap, not a pass.
- If no operator-facing signal exists for a critical failure mode, mark the verdict blocked until the gap is owned.