ometere123/the-skills-bible/ai-observability-engineer

AI Observability Engineer

Purpose

Make AI behaviour diagnosable across probabilistic and deterministic components without collecting excessive sensitive data or private reasoning.

Use this skill when

• AI failures cannot be traced to model, prompt, retrieval, tool, or policy.
• Agent runs need step and cost visibility.
• Production quality and feedback need monitoring.
• AI telemetry risks leaking prompts or user data.

Do not use this skill as the primary workflow when

• The task is general infrastructure observability.
• A one-time offline evaluation is sufficient.
• The request seeks hidden surveillance.

Required inputs

• AI architecture and workflows.
• Model, prompt, retrieval, tool, and policy versions.
• Operational and quality questions.
• Privacy and retention requirements.
• Telemetry platform and cost limits.

Classify missing information as blocking, important, or optional. Inspect the actual product requirements, workflows, data, models, prompts, tools, permissions, evaluations, traces, incidents, policies, and production constraints before asking for information that can be verified directly.

Core operating principles

• Start from the decision, workflow, user outcome, or automation need rather than from a model or vendor.
• Use the simplest deterministic method that can satisfy the requirement before adding probabilistic components.
• Separate model capability, application logic, tools, memory, retrieval, policy, and human authority.
• Treat prompts, datasets, tools, schemas, model versions, policies, and evaluations as versioned production artefacts.
• Ground consequential outputs in authoritative evidence and expose uncertainty, provenance, and limitations.
• Constrain permissions, data access, actions, spending, recursion, and runtime before granting autonomy.
• Evaluate representative tasks, edge cases, adversarial inputs, failures, and affected user groups before release.
• Preserve privacy, security, accessibility, human agency, appeal, and safe failure throughout the lifecycle.
• Make model and agent behaviour observable without logging secrets, private reasoning, or unnecessary personal data.
• Design rollback, fallback, escalation, incident response, and decommissioning before production deployment.

Workflow

1. Define observability questions

• Identify what operators need to know about task success, grounding, refusals, tools, safety, latency, cost, and user impact.

2. Create trace identity

• Correlate request, session, task, agent run, model call, retrieval, tool call, approval, and release safely.

3. Capture versions

• Record model, prompt, schema, dataset or index, tool, policy, configuration, and experiment version for every outcome.

4. Instrument model calls

• Measure latency, tokens, errors, truncation, retries, response mode, and bounded input-output metadata.
• Avoid raw content by default.

5. Instrument retrieval

• Record query version, filters, sources, ranks, scores, citations, access decisions, and freshness.

6. Instrument tools and agents

• Record proposed and executed calls, policy checks, state transitions, budgets, approvals, failures, and completion.

7. Capture outcome feedback

• Use deterministic validators, user corrections, business outcomes, human review, incidents, and sampled audits.

8. Protect data

• Redact secrets and personal content, hash or tokenise identifiers, restrict trace access, and set retention by value.

9. Build diagnostics

• Create dashboards and failure bundles by task, version, tenant-safe cohort, tool, source, and release.
• Support replay where safe.

10. Validate observability

• Inject known retrieval, model, tool, policy, and agent failures and verify the telemetry identifies the layer.

Decision rules

Required outputs

• Observability questions.
• Trace identity.
• Version lineage.
• Model telemetry.
• Retrieval telemetry.
• Tool and agent telemetry.
• Outcome feedback.
• Privacy controls.
• Dashboards and diagnostics.
• Observability validation.

AI system quality gates

• Problem gate: The intended outcome and the reason to use AI are explicit.
• Data gate: Sources, rights, quality, lineage, privacy, and retention are controlled.
• Model gate: Model capability, limits, version, configuration, and fallback are documented.
• Grounding gate: Claims and actions use suitable evidence, tools, or deterministic checks.
• Authority gate: The model cannot exceed the permissions, spending, scope, or actions granted by policy.
• Evaluation gate: Representative, adversarial, failure, and subgroup evaluations meet approved thresholds.
• Human gate: High-impact, ambiguous, irreversible, or exceptional outcomes receive appropriate human review.
• Safety gate: Abuse, injection, privacy, harmful content, and unsafe action paths are tested and bounded.
• Observability gate: Inputs, outputs, tools, state, latency, cost, and outcomes are diagnosable with data minimisation.
• Lifecycle gate: Versioning, rollout, rollback, monitoring, incident response, and retirement are operational.

Evidence standard

For consequential AI conclusions, identify the exact model, model version, system prompt, tool set, retrieval index, dataset, policy, evaluation set, configuration, environment, and time window. Distinguish observed behaviour, measured estimates, supported inference, and unknowns. Do not claim capability, safety, fairness, or reliability from a few demonstrations.

Failure handling and escalation

Pause or escalate when:

• The system's intended authority, affected users, or acceptable error is unclear.
• Training, retrieval, or evaluation data lacks provenance, permission, or privacy controls.
• A model or agent may send messages, move money, change records, execute code, or access sensitive systems beyond approved scope.
• Prompt injection, tool compromise, data poisoning, identity confusion, or uncontrolled recursion is plausible.
• A high-impact outcome cannot be independently verified or appealed.
• Evaluation evidence is missing, stale, non-representative, or materially regresses.
• Residual safety, privacy, legal, financial, or operational risk exceeds delegated authority.

Report the exact blocker, verified state, affected outcome, safe options, and smallest required decision.

Common anti-patterns

• Logging all prompts forever.
• No prompt or model version in traces.
• Only token and latency metrics.
• Private chain-of-thought required for diagnosis.
• User feedback stored without context.
• Tool proposal confused with executed action.
• AI telemetry accessible to every developer.

Completion checklist

• [ ] Requests trace across AI components.
• [ ] Exact versions are recorded.
• [ ] Outcome and operational evidence connect.
• [ ] Sensitive content is minimised.
• [ ] Failures identify the responsible layer.
• [ ] Retention and access are governed.

AI implementation record

# AI Implementation Record
 
## Outcome
[Task, user need, decision, or automation result]
 
## Scope and authority
[Users, systems, data, tools, permissions, budgets, and exclusions]
 
## Architecture
[Models, prompts, retrieval, memory, tools, policies, humans, and fallback]
 
## Data and provenance
[Sources, rights, lineage, privacy, retention, and quality]
 
## Evaluation
[Tasks, datasets, metrics, thresholds, adversarial cases, and subgroup results]
 
## Safety and security
[Injection, abuse, harmful output, tool constraints, privacy, and escalation]
 
## Deployment
[Versioning, routing, rollout, rollback, compatibility, and cost]
 
## Observability
[Traces, outcomes, latency, tokens, tool calls, incidents, and redaction]
 
## Residual risk
[Known limits, owner, acceptance, expiry, and user communication]
 
## Follow-up
[Monitoring, retraining, index refresh, policy updates, and decommission triggers]

Related skills

• model-monitoring-drift-engineer
• agent-evaluation-engineer
• ai-reliability-engineer
• observability-platform-engineer

Maintenance rules

Review this skill when models, datasets, policies, tools, regulations, or workflows change; evaluations or incidents reveal a missing safeguard; the workflow becomes tied to one vendor; the file approaches 500 lines; or reusable schemas, evaluators, test sets, or guardrail policies would improve execution.