agentleFS
dream-horizon-orgdream-horizon-org/pulse/.agents/skills/web-sdk-ship/SKILL.md

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

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
  1. Very specific:

    Use for any non-trivial change in pulse-web-otel/ before you call the package ready to ship / merge.

    line 8
  2. Distinctive:

    Keep the web SDK production-safe while moving fast—one checklist from first touch to merge-ready.

    line 26
  3. Distinctive:

    Check Android parity for equivalent paths and record suspected mismatches early.

    line 38
  4. Distinctive:

    Prefer adapter-first refactors for lifecycle changes.

    line 47
  5. Very specific:

    Keep single-owner lifecycle (install/init/shutdown).

    line 48
  6. Distinctive:

    Avoid parallel code paths that initialize the same feature twice.

    line 49
  7. Very specific:

    Contract hygiene: use PulseWebSemconv for keys and pulse.type values.

    line 50
  8. Distinctive:

    Run focused unit tests for changed modules.

    line 56
  9. Very specific:

    Run wiring/lifecycle tests (sdk + instrumentation registry paths).

    line 57
  10. Distinctive:

    Run any extra targeted E2E for behavior not covered by the gate.

    line 59
  11. Distinctive:

    If cross-browser binaries are missing, report Chromium result plus explicit gap.

    line 60
  12. Very specific:

    If Step 5 (audit) or PR review exposes doubt, re-run yarn test:run and/or e2e:web-sdk-gates before merge.

    line 63
  13. Distinctive:

    No dropped custom events unexpectedly.

    line 69
  14. Very specific:

    No interaction regressions in timeout/sequence/APDEX paths.

    line 70
  15. Distinctive:

    No listener/timer leaks after shutdown.

    line 71
  16. Distinctive:

    No contract drift in exported attributes.

    line 72
  17. Very specific:

    After Step 3 is green, walk this list on the diff (or touched modules if the change is tiny).

    line 78
  18. Very specific:

    Update plan/docs/csv if test matrix or behavior changed.

    line 119
  19. Distinctive:

    Keep descriptions explicit and parse-safe for CSV cells.

    line 120
  20. Distinctive:

    Self-heal (instrumentation & web SDK workflow): If Step 5 or PR review surfaced a valid, repeatable gap, judge scope:

    line 122
  21. Distinctive:

    When finishing work, report:

    line 131

≈ “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.

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

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

ArtifactRole
pulse-web-sdkCursor agent — loads this skill + rules for substantive web SDK tasks (includes staged instrumentation entry).
web-sdk-instrumentInstrumentation 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

  1. Identify touched areas: core SDK, instrumentations, exporters, interactions, demo, tests.
  2. List contract-sensitive items:
    • pulse.type
    • semantic attribute keys
    • public API methods/signatures
    • consent and feature-gate behavior
  3. Check Android parity for equivalent paths and record suspected mismatches early.
  4. Read graph context:
    • source: pulse-web-otel/graphify-out/GRAPH_REPORT.md and pulse-web-otel/graphify-out/graph.json (if present)
    • cache: pulse-web-otel/graphify-out/GRAPH_REPORT.md

Step 2: Implement safely

  1. Prefer adapter-first refactors for lifecycle changes.
  2. Keep single-owner lifecycle (install/init/shutdown).
  3. Avoid parallel code paths that initialize the same feature twice.
  4. Contract hygiene: use PulseWebSemconv for keys and pulse.type values; PulseFeature + InstrumentationKeys for gates and registry keys; PulseAttributes for 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

  1. Run focused unit tests for changed modules.
  2. Run wiring/lifecycle tests (sdk + instrumentation registry paths).
  3. Required E2E gate: yarn workspace ecommerce-demo e2e:web-sdk-gates (Chromium bundle in examples/ecommerce-demo/package.json; stops after 5 failures via --max-failures=5 for faster feedback — re-run after fixes for a full green pass).
  4. Run any extra targeted E2E for behavior not covered by the gate.
  5. If cross-browser binaries are missing, report Chromium result plus explicit gap.
  6. Record run result in CI / PR description (optional: pulse-web-otel/progress.txt for 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 outside PulseWebSemconv (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 / document listeners, PerformanceObserver, timers → removed on uninstall / shutdown path.
  • InstrumentationRegistry: no double subscription if installAll can run twice (idempotency pattern where used).
  • Async init (start / finishStart): no signals after shutdown or before _initialized where 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.test keeps VITE_PULSE_FORMAT=json (and compression story) if E2E reads captured bodies.
  • New behavior covered by Vitest; user-visible flows covered by E2E or explicitly deferred with PLAN/ADR note.
  • e2e:web-sdk-gates includes new spec file if added (package.json script).

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.md for blast radius.
  • IndexedDB / disk-buffer replay: failed-export + reload E2E with zero replayed logs → read src/persistence/indexed-db.ts (write → enforceMaxSize) and src/constants/disk-buffer.ts vs docs/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

  1. Update plan/docs/csv if test matrix or behavior changed.
  2. Keep descriptions explicit and parse-safe for CSV cells.
  3. Refresh graph cache summary after meaningful code changes.
  4. 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.mdc or web-sdk.mdc instead 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:

  1. Files changed
  2. Tests run (exact commands)
  3. Pass/fail summary
  4. Step 5 summary: P0/P1/P2 table or “no findings” / N/A
  5. 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
- ...

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.