analytics-instrumentation
Wires a feature's analytics the tracking-plan-as-code way: the model names the event in the project's one convention and writes the doc body, and the bundled instrument.mjs writes the per-event doc and module index and prints the provider snippet. A new event goes through the analytics.new_event Decision Pause first. Use when analytics_instrumentation is on and the classify-time gate resolved to instrument.
- License 许可
- MIT
- 所属仓库
- Eliyce/paqad-ai
- 最近更新
- 2026-11-13
- Stars
- ★ 8
- Forks
- 0
01 前言 Front Matter
- name
- analytics-instrumentation
- metadata
- { "cacheable": "false", "model_tier": "fast", "paqad-meta": "skill.meta.yaml", "output_format": "json" }
- description
- Wires a feature's analytics the tracking-plan-as-code way: the model names the event in the project's one convention and writes the doc body, and the bundled instrument.mjs writes the per-event doc and module index and prints the provider snippet. A new event goes through the analytics.new_event Decision Pause first. Use when analytics_instrumentation is on and the classify-time gate resolved to instrument.
02 资源文件 4
- 参考文档agents/openai.yaml496 B
- 参考文档references/analytics-tracking-plan-contract.md1.7 KB
- 脚本scripts/instrument.mjs2.0 KB
- 参考文档skill.meta.yaml717 B
03 SKILL.md 正文
Analytics instrumentation
What It Does
Turns "add tracking for this feature" into the governed, documented, drift-resistant flow paqad promises: it names and documents each event as a reviewed per-event doc, governs every new event through a Decision Pause, and emits the provider tracking-call to paste into the source.
Use This When
Analytics is enabled (analytics_instrumentation on) and the classify-time gate wrote
.paqad/planning/analytics-decision.json with status: instrument: i.e. a user-facing change
in a project with a detected provider. Skip entirely when analytics is off or the change is not
user-facing.
Inputs
project_root: resolves the docs tree and the analytics decision sidecar.module,feature: the module and feature slugs the event belongs to (from the module map).event: the exact event name, in the project's ONE consistent convention.provider: one or more analytics provider ids the event fires to.
Procedure
- Name the event in the project's one consistent convention. Read
docs/instructions/stack/analytics.mdand the module'sanalytics/index.mdfirst, and reuse an existing event before coining a new one. Object-action + past tense is a common default, not a rule; consistency is the rule, and no variable data goes in the name. - Govern a new event. If the event does not already exist, open a Decision Pause packet in
the
analytics.new_eventcategory (who proposed it, why, with the name/casing/taxonomy/PII surfaced) via thedecisionskill and wait for the answer. Never add a new event silently. - Instrument + document. Run the bundled script to write the per-event doc and get the
provider call snippet:
node scripts/instrument.mjs <project-root> --module <m> --feature <f> --event <name> --provider <p> [--provider <p> ...]. Paste the printed snippet at the call site, then fill in the doc body: what the event means, its properties, and the PII/consent section.
Output Contract
The script prints JSON { docPath, written, snippet } on stdout: docPath is the module-owned
per-event doc, written lists the files created or refreshed (the doc + the per-module
analytics/index.md), and snippet is the provider tracking call(s) to paste. The doc's
existence is what the off | warn | strict completeness gate checks at Done.
Escalate / Stop Conditions
- A brand-new event, or any name/casing/taxonomy/PII concern: STOP and open the
analytics.new_event(or the matchinganalytics.*) Decision Pause; do not instrument until it resolves. - Analytics off or a non-
instrumentsidecar: do nothing (INV-1 keeps a non-analytics run silent).
Resources
scripts/instrument.mjs: writes the per-event doc + index and prints the provider snippet.references/analytics-tracking-plan-contract.md: the tracking-plan-as-code contract this skill implements.
04 同仓库更多 Skills
sample-skill
Sample bundled skill fixture
processing-invoices
Turns a supplier invoice into one ledger line. Use when a supplier invoice arrives and needs booking.
processing-invoices
Turns a supplier invoice into one ledger line. Use when a supplier invoice arrives and needs booking.
understand-idea
Chat and Claude Code: Step 1 of the discover journey: clarifies the goal, who benefits, success and constraints into the idea block. Use when the journey directs it to step 1, not directly.
size-work
Chat and Claude Code: Suggest a size for a ticket from comparable finished work, as a labelled suggestion the team still owns. Use it when someone asks "how big is this?", "roughly how much work is ABC-12?", or wants a backlog item sized. It finds the team's sizing scale at first use, picks two to five of the closest finished tickets with links, and gives a size or range with the drivers behind it and a confidence of low, medium or high, lowered and explained when the area's documents are template text. Every result is labelled a suggested size, never a date or a commitment. It writes nothing into the size field unless the user says "set it", and it refuses to overwrite an existing size unless the user asks to replace it. Produces the sizing block of the record.
refine-ticket
Chat and Claude Code: Improve one or more existing tracker tickets without losing the author's intent. Use it when someone wants a ticket read, diagnosed and tidied up ("this ticket is vague", "fix up ABC-12", "split this, it's too big"). It reads each ticket in full and snapshots it with its last-updated time, says what is wrong with evidence, and proposes a field-by-field before and after change set limited to summary, description, labels, parent, links and new child tickets on a split. It writes nothing until an explicit "apply it" bound to that exact change set, re-checks the ticket for conflicting edits just before writing, never replaces rich descriptions with plain text, never deletes or closes a ticket, and reads each ticket back after applying. Produces the existing and changes blocks of the record.