web-sdk-ship
Skill44 starsChanged 5 months agoApache-2.0View on GitHub
Ship-ready workflow for pulse-web-otel — scope, contract, safe implementation, test ladder, regression checklist, pre-merge diff audit (P0/P1/P2), test-run-log, doc sync. (Legacy folder names: pulse-web-sdk-sanity, web-sdk-merge.)
- Reads credentials
In this repository20 other files it gives its agents.
- .claude/CLAUDE.mdCLAUDE.md
- CLAUDE.mdCLAUDE.md
- product/CLAUDE.mdCLAUDE.md
- pulse-web-otel/CLAUDE.mdCLAUDE.md
- add-ai-sub-agentSkill
- add-alert-metricSkill
- add-api-endpointSkill
- add-ui-componentSkill
- add-ui-screenSkill
- clickhouse-migrationSkill
- deploy-serviceSkill
- fatal-fiveSkill
- integrate-pulse-web-sdkSkill
- pr-reviewSkill
- pulse-prd-authorSkill
- pulse-prd-reviewSkill
- web-otel-spec-audit-orchestratorSkill
- web-otel-spec-implementation-auditSkill
- web-sdk-e2e-matrixSkill
- web-sdk-instrumentSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
21 rules. About 0 are common, 13 are distinctive, and 8 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈13
Distinctive · estimate
This author's own choices. Worth a look.
8
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 8
Use for any non-trivial change in pulse-web-otel/ before you call the package ready to ship / merge.
- Distinctive: line 26
Keep the web SDK production-safe while moving fast—one checklist from first touch to merge-ready.
- Distinctive: line 38
Check Android parity for equivalent paths and record suspected mismatches early.
- Distinctive: line 47
Prefer adapter-first refactors for lifecycle changes.
- Very specific: line 48
Keep single-owner lifecycle (install/init/shutdown).
- Distinctive: line 49
Avoid parallel code paths that initialize the same feature twice.
- Very specific: line 50
Contract hygiene: use PulseWebSemconv for keys and pulse.type values.
- Distinctive: line 56
Run focused unit tests for changed modules.
- Very specific: line 57
Run wiring/lifecycle tests (sdk + instrumentation registry paths).
- Distinctive: line 59
Run any extra targeted E2E for behavior not covered by the gate.
- Distinctive: line 60
If cross-browser binaries are missing, report Chromium result plus explicit gap.
- Very specific: line 63
If Step 5 (audit) or PR review exposes doubt, re-run yarn test:run and/or e2e:web-sdk-gates before merge.
- Distinctive: line 69
No dropped custom events unexpectedly.
- Very specific: line 70
No interaction regressions in timeout/sequence/APDEX paths.
- Distinctive: line 71
No listener/timer leaks after shutdown.
- Distinctive: line 72
No contract drift in exported attributes.
- Very specific: line 78
After Step 3 is green, walk this list on the diff (or touched modules if the change is tiny).
- Very specific: line 119
Update plan/docs/csv if test matrix or behavior changed.
- Distinctive: line 120
Keep descriptions explicit and parse-safe for CSV cells.
- Distinctive: line 122
Self-heal (instrumentation & web SDK workflow): If Step 5 or PR review surfaced a valid, repeatable gap, judge scope:
- Distinctive: line 131
When finishing work, report:
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 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.
Files
Web SDK ship checklist (web-sdk-ship)
Use for any non-trivial change in pulse-web-otel/ before you call the package ready to ship / merge. Formerly pulse-web-sdk-sanity → web-sdk-merge; same Steps 1–6.
Relationship to other tools
| Artifact | Role |
| pulse-web-sdk | Cursor agent — loads this skill + rules for substantive web SDK tasks (includes staged instrumentation entry). |
| web-sdk-instrument | Instrumentation projects — research, ADR/PLAN, gap matrix; close-out still runs this skill (Steps 3–6). |
Order before merge: Steps 1 → 2 (while coding) → 3 tests (must be green) → 4 regression bullets → 5 diff audit (P0/P1/P2 or explicit clean) → 6 docs/graph → pr-review. Do not skip Step 3 and claim Step 5 alone is enough.
Rules (read first)
.cursor/rules/pulse-web-otel.mdc.cursor/rules/web-sdk.mdc
Goal
Keep the web SDK production-safe while moving fast—one checklist from first touch to merge-ready.
Step 1: Scope and contract
- Identify touched areas: core SDK, instrumentations, exporters, interactions, demo, tests.
- List contract-sensitive items:
pulse.type- semantic attribute keys
- public API methods/signatures
- consent and feature-gate behavior
- Check Android parity for equivalent paths and record suspected mismatches early.
- Read graph context:
- source:
pulse-web-otel/graphify-out/GRAPH_REPORT.mdandpulse-web-otel/graphify-out/graph.json(if present) - cache:
pulse-web-otel/graphify-out/GRAPH_REPORT.md
- source:
Step 2: Implement safely
- Prefer adapter-first refactors for lifecycle changes.
- Keep single-owner lifecycle (install/init/shutdown).
- Avoid parallel code paths that initialize the same feature twice.
- Contract hygiene: use
PulseWebSemconvfor keys andpulse.typevalues;PulseFeature+InstrumentationKeysfor gates and registry keys;PulseAttributesfor optional attribute bags on public APIs. No single-letter aliases (K/T/B) for semconv tables — see.cursor/rules/pulse-web-otel.mdc.
Step 3: Test ladder
- Run focused unit tests for changed modules.
- Run wiring/lifecycle tests (
sdk+ instrumentation registry paths). - Required E2E gate:
yarn workspace ecommerce-demo e2e:web-sdk-gates(Chromium bundle inexamples/ecommerce-demo/package.json; stops after 5 failures via--max-failures=5for faster feedback — re-run after fixes for a full green pass). - Run any extra targeted E2E for behavior not covered by the gate.
- If cross-browser binaries are missing, report Chromium result plus explicit gap.
- Record run result in CI / PR description (optional:
pulse-web-otel/progress.txtfor local Ralph loops).
If Step 5 (audit) or PR review exposes doubt, re-run yarn test:run and/or e2e:web-sdk-gates before merge.
Step 4: Regression checklist
- No dropped custom events unexpectedly.
- No interaction regressions in timeout/sequence/APDEX paths.
- No listener/timer leaks after shutdown.
- No contract drift in exported attributes.
Step 5: Pre-merge diff review (required for substantive changes)
After Step 3 is green, walk this list on the diff (or touched modules if the change is tiny). Record each issue as P0 (block merge) / P1 / P2 with path:line and a fix hint—or one line “Step 5: no findings” if clean.
5.1 Data contract
- Grep diff/changed files for ad-hoc
"pulse.type"/ log bodies / attribute keys outsidePulseWebSemconv(and interactions semconv where applicable). - Public surface:
src/index.ts, package exports — accidental breaking changes? PulseFeature↔InstrumentationKeys↔instrumentation-registry.ts— every gated feature mapped; no orphan keys.
5.2 Lifecycle & single ownership
- New DOM /
window/documentlisteners,PerformanceObserver, timers → removed onuninstall/shutdownpath. InstrumentationRegistry: no double subscription ifinstallAllcan run twice (idempotency pattern where used).- Async init (
start/finishStart): no signals after shutdown or before_initializedwhere forbidden.
5.3 Consent & feature gates
- DENIED / PENDING consent: zero OTLP and no listener leaks (align with existing E2E patterns).
- Gate off: instrumentation not installed; no stale global providers left half-configured.
5.4 Exporters, demo, E2E
- Playwright fixture decodes JSON OTLP — confirm
examples/ecommerce-demo/.env.testkeepsVITE_PULSE_FORMAT=json(and compression story) if E2E readscapturedbodies. - New behavior covered by Vitest; user-visible flows covered by E2E or explicitly deferred with PLAN/ADR note.
e2e:web-sdk-gatesincludes new spec file if added (package.jsonscript).
5.5 Android parity (one pass)
- For each new/changed product signal, note Android equivalent behavior: match, documented divergence, or TODO.
Optional deep dives (if those areas changed)
- Interactions: focused greps in
src/interactions/for sequence/timeout/APDEX assumptions. - Graph context:
pulse-web-otel/graphify-out/GRAPH_REPORT.mdfor blast radius. - IndexedDB / disk-buffer replay: failed-export + reload E2E with zero replayed logs → read
src/persistence/indexed-db.ts(write→enforceMaxSize) andsrc/constants/disk-buffer.tsvsdocs/sdk-core/config-and-public-api/SPEC.md(~10 MiB). Durable note: web-sdk-instrument/reference.md §F + matrix D6.
Trivial doc-only edits under docs/instrumentations/ with no code: Step 5 can be N/A—state that in the close-out report.
Step 6: Documentation sync
- Update plan/docs/csv if test matrix or behavior changed.
- Keep descriptions explicit and parse-safe for CSV cells.
- Refresh graph cache summary after meaningful code changes.
- Self-heal (instrumentation & web SDK workflow): If Step 5 or PR review surfaced a valid, repeatable gap, judge scope:
- Instrumentation projects: append one atomic row to web-sdk-instrument/reference.md section F — Durable learnings (and tighten A–E matrix rows if the lesson fits a checkbox).
- Repo-wide contract / every PR: propose an edit to
.cursor/rules/pulse-web-otel.mdcorweb-sdk.mdcinstead of bloating the instrumentation reference. - Skip one-off nits and subjective style—this log is for next-run prevention, not transcripts.
Output format
When finishing work, report:
- Files changed
- Tests run (exact commands)
- Pass/fail summary
- Step 5 summary: P0/P1/P2 table or “no findings” / N/A
- Known gaps and next action
For PRs or large diffs, you may paste the structured block:
## Web SDK ship — <branch / PR>
### Findings (Step 5)
| Sev | Location | Issue | Suggested fix |
|-----|----------|-------|----------------|
| P0 | ... | ... | ... |
### Checklist
- Contract: pass / gaps
- Lifecycle: pass / gaps
- Gates/consent: pass / gaps
- Demo/E2E: pass / gaps
- Parity: ...
### Commands run
- ...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
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.

