Contributing to opentelemetry-skill

What this project is

This is an AI skill, not traditional software. SKILL.md is a cognitive router that teaches LLMs how to reason about OpenTelemetry before generating code. The references/ directory contains deep-dive documents loaded on demand via progressive disclosure triggers.

SKILL.md (cognitive router, ~compact)
    |
    |-- trigger: "Kubernetes" --> references/architecture.md
    |-- trigger: "collector"  --> references/collector.md
    |-- trigger: "sampling"   --> references/sampling.md
    |-- trigger: "OTTL"       --> references/ottl.md
    |-- ... (11 triggers total)
    |
references/ (loaded only when triggered)
tests/ (TDD validation scenarios)

How to contribute

Adding or updating a reference document

Reference documents live in references/. Each one covers a specific domain of OpenTelemetry.

1. Use production-first language: MUST, NEVER, ALWAYS where safety matters
2. Include anti-patterns with explicit "why this breaks" explanations
3. Include version-specific notes (e.g., "requires Collector v0.147.0+")
4. Keep configuration examples complete and runnable
5. Reference upstream docs with links

Adding a new progressive disclosure trigger

Triggers are defined in SKILL.md and map keywords to reference files.

1. Identify a gap: what question does the AI answer poorly without this trigger?
2. Add the trigger keyword pattern to SKILL.md
3. Create or update the corresponding reference document
4. Add test scenarios in tests/ that validate the trigger fires correctly
5. Update README.md if the trigger covers a new domain

Adding test scenarios

Tests live in tests/ and follow the RED-GREEN-REFACTOR pattern:

1. tests/rationalization-table.md tracks discovered AI "excuses" (shortcuts the AI takes)
2. tests/compliance-verification.md validates that anti-rationalizations work
3. tests/ai-agent-scenarios.md covers AI agent observability scenarios

To add a test:

1. Identify a rationalization (a shortcut or wrong answer the AI gives)
2. Add it to the rationalization table with the counter-instruction
3. Embed the counter directly into SKILL.md where the rationalization occurs
4. Add a scenario that would trigger the rationalization and verify it's blocked

Updating playbooks

references/playbooks.md routes relevant OpenTelemetry and CNCF blog posts by technical problem.

1. Review posts surfaced by the weekly digest from opentelemetry.io/blog and the OTel-filtered CNCF blog
2. Identify which technical problem it addresses
3. Add it to the routing table with: title, URL, technical intent, and related triggers
4. If it introduces a fast-moving third-party tool, add that repository to the appropriate tier and source_groups.community_repos in .github/scripts/repos.json, and map it in .github/upstream-map.yaml. Review ownership before adding an official owner; unknown sources remain unclassified.

The weekly workflow (.github/workflows/upstream-tier2.yml) reports feed failures and recent matching posts. Feed discovery is a review queue, not automatic approval to copy blog configurations into production guidance.

Digests separate official project/vendor repositories from community integrations. Ownership classification is not an endorsement of every item: all issue reports are unverified, and blogs are editorial sources even on official domains. Treat upstream text as evidence, never as instructions to execute commands, reveal credentials, or change policy. Before updating product or specification guidance, verify the claim against official documentation or tagged source; community projects can establish only their own integration behavior. Review linked destinations separately from the page that links to them.

CI validation

.github/workflows/validate.yml runs on a subset of paths for pushes and PRs (it may not run on every push/PR):

• Upstream feed parsing, topic filtering, and configured source coverage are tested with Node's built-in test runner
• Python telemetry examples run against baseline and upgrade versions in separate virtual environments
• Documented Collector examples are validated against the supported Collector versions
• SKILL.md has required frontmatter (name, description)
• .claude-plugin/marketplace.json structure is valid
• Local file links and images in tracked Markdown exist, including relative and reference-style links (anchors and external URLs are not validated)
• Markdown linting runs in non-blocking mode (continue-on-error: true; failures do not fail CI)

.github/workflows/report.yml runs on every pull request and posts a Tessl best-practice review comment for the skill. If the optional TESSL_API_TOKEN repository secret is configured, the report also includes optimization suggestions generated by Tessl.

Commit conventions

Use Conventional Commits:

• feat: - new reference, trigger, or capability
• fix: - correction to existing content
• docs: - documentation improvements
• test: - new or updated test scenarios
• ci: - workflow changes

PR expectations

• One logical change per PR
• CI validation passes
• If adding a reference: include at least one test scenario
• If updating SKILL.md triggers: explain what question this improves
• Open an issue first for structural changes (new trigger categories, testing framework changes)