| name | web-otel-spec-implementation-audit |
| description | 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. Use when this capability is needed. |
| metadata | {"author":"dream-horizon-org"} |
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 id | What “pass” means |
|---|
spec_structure | SPEC has clear goal, assumptions, requirements, non-functional notes, and an implementation index listing authoritative src/ paths. |
mermaid_hld | At least one Mermaid diagram showing high-level components, registry/exporter boundaries, and who calls whom (not sequence-level). |
mermaid_ld | At least one Mermaid diagram for internal modules, key types/functions, and data flow between units. |
mermaid_flows_edge_cases | At 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_testable | Numbered requirements are concrete and falsifiable. |
attribute_contract_table | Tables for spans/logs/metrics align with src/semconv.ts and actual attribute keys emitted in code. |
implementation_paths | Every path listed under implementation / touchpoints exists and is still the right owner file. |
test_matrix_positive_negative_edge | A 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_parity | SPEC 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_tests | Each requirement maps to at least one matrix row or has an explicit gap callout. |
Procedure
- 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[].
- Read SPEC — Check Mermaid fences are well-formed (opening and closing triple-backtick fences with
mermaid language tag); flag missing HLD/LD/flow.
- Read implementation — Open registry (
instrumentation-registry.ts), primary instrumentation files, integrations referenced in the SPEC, and Vitest/E2E tests that cover the feature.
- Matrix pass — For each scenario row, mark covered / drift / missing test.
- 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.
Source: dream-horizon-org/pulse — distributed by TomeVault.
