observability_driven_development

Design span trees before coding and validate traces against a narrative spec.

20|6|Updated Jan 16, 2026

Search Tags:#narrative #validation #observability #instrumentation #telemetry #otel #loop

Ready to run

npx skills add https://github.com/adrielp/ai-engineering-harness --skill observability-driven-development

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: observability_driven_development
Source: https://github.com/adrielp/ai-engineering-harness/tree/main/gemini/skills/observability_driven_development
Command: npx skills add https://github.com/adrielp/ai-engineering-harness --skill observability-driven-development

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Observability Driven Development (ODD) treats tracing as a design artifact. You define the span tree before coding and run locally against a local OTel stack so every change yields a readable trace that guides decisions.

Core Features & Use Cases

Narrative-first design: write a telemetry narrative before implementation to guide instrumentation.
Local observability loop: stand up the Aspire dashboard and a local OTel stack to observe traces in real time.
Validation-driven delivery: verify behaviour against the narrative using the /validate_telemetry workflow and iterate until the trace matches the spec.

Quick Start

Write the narrative spec before the implementation, stand up the local OTel stack, instrument the feature, and validate telemetry with /validate_telemetry workflow.

Frequently Asked Questions about observability_driven_development

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

What is observability driven development and how does it guide feature implementation?▼

Observability driven development treats tracing as a design artifact where you define the span tree before coding, then run locally against an OpenTelemetry stack so every change yields a readable trace that guides implementation decisions.

How do I design OpenTelemetry traces before writing code for features crossing async boundaries?▼

Design OpenTelemetry traces before coding by writing a narrative spec that guides instrumentation, then defining proper span design and attributes to ensure end-to-end observability across async boundaries and external API calls.

How do I validate telemetry against a narrative spec during development?▼

Validate telemetry against a narrative spec by running the /validate_telemetry workflow, which compares observed traces from your local OTel stack against the spec and iterates until the trace matches the defined behavior.

Do I need a local OpenTelemetry stack to use observability driven development?▼

Yes, a local OpenTelemetry stack is required. You need to stand up the Aspire dashboard and local OTel collector to observe traces in real time and validate instrument behavior against your narrative specification.

When should I use observability driven development instead of adding tracing after implementation?▼

Use observability driven development for features that cross async boundaries or external API calls, where designing the trace first ensures proper instrumentation and validation rather than retroactively adding telemetry to existing code.

What does a telemetry narrative spec contain for trace-driven feature development?▼

A telemetry narrative spec contains the expected span tree structure, span attributes, and behavioral flow that guides instrument design and serves as the validation target for comparing observed traces during the development loop.