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.
1---2name: web-otel-spec-implementation-audit3description: 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.4---56# Web SDK — SPEC implementation audit78## Preconditions910- Repo root is the Pulse monorepo; primary paths are under `pulse-web-otel/`.11- Read [audit-index.json](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`.1213## What to audit (dimensions)1415For the target instrumentation row, verify every dimension id in `default_dimension_ids` (see `audit-index.json`), or the subset the user asked for:1617| Dimension id | What “pass” means |18|--------------|-------------------|19| `spec_structure` | SPEC has clear goal, assumptions, requirements, non-functional notes, and an implementation index listing authoritative `src/` paths. |20| `mermaid_hld` | At least one **Mermaid** diagram showing high-level components, registry/exporter boundaries, and who calls whom (not sequence-level). |21| `mermaid_ld` | At least one **Mermaid** diagram for internal modules, key types/functions, and data flow between units. |22| `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.). |23| `requirements_testable` | Numbered requirements are concrete and falsifiable. |24| `attribute_contract_table` | Tables for spans/logs/metrics align with `src/semconv.ts` and actual attribute keys emitted in code. |25| `implementation_paths` | Every path listed under implementation / touchpoints exists and is still the right owner file. |26| `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**. |27| `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. |28| `traceability_req_to_tests` | Each requirement maps to at least one matrix row or has an explicit **gap** callout. |2930## Procedure31321. **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[]`.332. **Read SPEC** — Check Mermaid fences are well-formed (opening and closing triple-backtick fences with `mermaid` language tag); flag missing HLD/LD/flow.343. **Read implementation** — Open registry (`instrumentation-registry.ts`), primary instrumentation files, integrations referenced in the SPEC, and Vitest/E2E tests that cover the feature.354. **Matrix pass** — For each scenario row, mark **covered** / **drift** / **missing test**.365. **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).3738## Queue file (optional context)3940If `.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.4142## Output template4344```markdown45## SPEC audit: <instrumentation_id>4647### Summary48- …4950### Dimension results51| Dimension | Status | Notes |52|-----------|--------|-------|5354### Findings (by severity)55#### Critical56- …5758#### Major59- …6061#### Minor62- …6364### Suggested changes65- SPEC: …66- Code: … (only if ADR-normative SPEC)67```6869## Additional reference7071For report examples or long tables, add [reference.md](reference.md) later; keep this SKILL lean.7273---74> Source: [dream-horizon-org/pulse](https://github.com/dream-horizon-org/pulse) — distributed by [TomeVault](https://tomevault.io).75<!-- tomevault:4.0:skill_md:2026-07-05 -->
tomevault-io