agentleFS
Sign inStart free
dream-horizon-orgdream-horizon-org/pulse/.agents/skills/web-otel-spec-implementation-audit/SKILL.md

web-otel-spec-implementation-audit

Skill44 starsChanged 5 months agoApache-2.0View on GitHub

Audits pulse-web-otel docs/instrumentations/*/SPEC.md against src for format compliance (including mandatory Mermaid HLD, LD, and edge-case flow diagrams) and spec–code parity with a positive/negative/edge test matrix. Uses audit-index.json for dimension checklist and path mapping. Use when editing pulse-web-otel SPECs or instrumentations, after queue hooks fire, or when the user asks for SPEC vs implementation alignment.

The file

We split this skill into the rules it gives an agent

2 rules. About 0 are common, 0 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Read audit-index.json for dimensions (audit checklist) and instrumentations (one row per primary SPEC.md path).

    line 12
  2. Very specific:

    If .cursor/pulse-web-otel-spec-audit-queue.jsonl exists, read recent lines with matching instrumentation_id to prioritize files the editor …

    line 41

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Web SDK — SPEC implementation audit

Preconditions

  • Repo root is the Pulse monorepo; primary paths are under pulse-web-otel/.
  • Read audit-index.json for dimensions (audit checklist) and instrumentations (one row per primary SPEC.md path). sdk-core splits topics under docs/sdk-core/<topic>/SPEC.md (parallel to instrumentations). session is docs/instrumentations/session/SPEC.md.

What to audit (dimensions)

For the target instrumentation row, verify every dimension id in default_dimension_ids (see audit-index.json), or the subset the user asked for:

Dimension idWhat “pass” means
spec_structureSPEC has clear goal, assumptions, requirements, non-functional notes, and an implementation index listing authoritative src/ paths.
mermaid_hldAt least one Mermaid diagram showing high-level components, registry/exporter boundaries, and who calls whom (not sequence-level).
mermaid_ldAt least one Mermaid diagram for internal modules, key types/functions, and data flow between units.
mermaid_flows_edge_casesAt least one Mermaid flowchart or stateDiagram covering the happy path and explicit branches for each documented edge (SSR / no window, feature off, consent, uninstall, dedupe windows, cross-origin, empty payloads, etc.).
requirements_testableNumbered requirements are concrete and falsifiable.
attribute_contract_tableTables for spans/logs/metrics align with src/semconv.ts and actual attribute keys emitted in code.
implementation_pathsEvery path listed under implementation / touchpoints exists and is still the right owner file.
test_matrix_positive_negative_edgeA dedicated section or table with positive, negative, and edge scenarios (Given / When / Then); each row cites a test file path or is marked missing.
spec_code_paritySPEC claims match behavior in pulse-web-otel/src/. Default: treat code as truth and propose SPEC updates unless an ADR explicitly makes the SPEC normative.
traceability_req_to_testsEach requirement maps to at least one matrix row or has an explicit gap callout.

Procedure

  1. Pick instrumentation — From user input or from .cursor/pulse-web-otel-spec-audit-queue.jsonl tail, resolve instrumentation_id. Load spec_path and related_src_globs from audit-index.json → instrumentations[].
  2. Read SPEC — Check Mermaid fences are well-formed (opening and closing triple-backtick fences with mermaid language tag); flag missing HLD/LD/flow.
  3. Read implementation — Open registry (instrumentation-registry.ts), primary instrumentation files, integrations referenced in the SPEC, and Vitest/E2E tests that cover the feature.
  4. Matrix pass — For each scenario row, mark covered / drift / missing test.
  5. Report — Use the output template below. Severities: Critical (wrong contract or misleading operators), Major (drift or missing safety/edge in diagrams or matrix), Minor (wording, ordering).

Queue file (optional context)

If .cursor/pulse-web-otel-spec-audit-queue.jsonl exists, read recent lines with matching instrumentation_id to prioritize files the editor just touched. Clearing the queue is manual after the user confirms audits are done.

Output template

## SPEC audit: <instrumentation_id>

### Summary
- …

### Dimension results
| Dimension | Status | Notes |
|-----------|--------|-------|

### Findings (by severity)
#### Critical
- …

#### Major
- …

#### Minor
- …

### Suggested changes
- SPEC: …
- Code: … (only if ADR-normative SPEC)

Additional reference

For report examples or long tables, add reference.md later; keep this SKILL lean.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free