vektis-instrument

vektis-instrument consumes the output of vektis-discover (or vektis-update), creates one Dev Item per approved candidate in your VEKTIS organization, and inserts vektis.track() calls in your source code. You approve a single unified diff covering every file change.

claude /vektis-instrument

For a 30-candidate codebase, the whole process is one browser click (authentication) plus one typed approval (approve all).

When to use this skill

You’re in this situation	Use this skill
You’ve run `vektis-discover` (or `vektis-update`) and approved a candidate list	`vektis-instrument`
You want everything in one command	`vektis-bootstrap`

Prerequisites

.vektis/discover-output.json exists. This is the contract. If the file is missing, the skill exits with a hint to run vektis-discover first.
Working tree is clean. The skill refuses to run on a dirty working tree so its diff doesn’t overlap with unrelated work in progress. Stash or commit your changes first.
You’re an admin in your VEKTIS organization. Bulk-creating Dev Items requires admin role. The auth step catches this before any code is written.

What it walks through

Read .vektis/discover-output.json. Validates the schema version. If generated_at is older than 7 days, the skill warns you that your codebase may have changed since the scan and asks if you want to continue or re-run discover.
Git status preflight. Aborts if anything is uncommitted or untracked.
Authenticate. OAuth browser flow on first run, cached afterwards. The skill confirms your role is admin before proceeding — non-admin users see “Ask your admin…” and the skill exits without writing anything.
Bulk-create Dev Items. Calls VEKTIS once with the full candidate list. For codebases with more than 100 candidates, the skill batches into multiple sequential calls and prints progress. The response tells you how many Dev Items were newly created and how many were skipped because they already exist for that feature_id.
Build the insertion plan. For every candidate (created or skipped — both still need their source instrumented), the skill computes the exact vektis.track() call to insert and the file/line where it goes. See What gets written below.
Drift guard. Before writing, the skill re-reads each target file and verifies the line still contains the expected SDK call signature. If the line has drifted (e.g., a refactor moved or removed the call), the file is skipped with a warning row.

Show the unified diff. The skill prints a summary:

Instrumentation plan:

  18 files will be modified
  32 vektis.track() calls will be inserted
  3 imports will be added (files that don't yet import @vektis-io/tracker)
  2 candidates skipped (currency value type — manual entry only)
  1 file skipped (drift detected at src/components/Old.tsx:42)

You drive it with these commands:

Command	What it does
`approve all`	Apply every change
`show diff`	Print the full unified diff
`show diff <N>`	Diff for a single file
`approve <N>`	Approve only one file
`cancel`	Exit without writing

Atomic writes. On approve all, every file is written via temp-file-then-rename, so a mid-write failure can’t leave a half-edited file on disk.
Final message. The skill prints a gh pr create command. If gh is authenticated, it offers to open the PR for you. Otherwise it just prints the command and exits.

What gets written

Per-file changes

For each instrumented file:

Add an import — if the file doesn’t already import @vektis-io/tracker:
```
import { vektis } from '@vektis-io/tracker';
```
Insert vektis.track() — on a new line immediately after the matched SDK call, preserving indentation. For example, after a mixpanel.track('Checkout Completed', {...}), you’ll see a new line:
```
vektis.track('feature.used', { feature_id: 'checkout-completed' });
```

The skill adds vektis.track() alongside your existing analytics calls. It does not remove or replace Mixpanel, Segment, Amplitude, PostHog, or GA4 calls — that’s a deliberate separate decision you make later.

What `vektis.track()` call gets inserted, by value type

Value type	Role	Inserted call
`count`	`action`	`vektis.track('feature.used', { feature_id })`
`percentage`	`numerator_action`	`vektis.track('feature.used', { feature_id })`
`percentage`	`denominator_action`	`vektis.track('feature.engagement', { feature_id, action })`
`duration`	`start_action`	`vektis.track('feature.engagement', { feature_id, action })`
`duration`	`end_action`	`vektis.track('feature.engagement', { feature_id, action })`
`activity`	`action`	`vektis.track('feature.engagement', { feature_id, action })`
`currency`	(any)	Not auto-instrumented — currency requires manual entry. Skipped with a warning row.

For percentage and duration candidates, the skill inserts at two distinct lines because those value types need both a start/numerator and an end/denominator event.

Dev Items created

Each candidate in .vektis/discover-output.json becomes a Dev Item with:

featureId — the feature_id from the candidate row
valueType — the value type heuristically chosen during discover (or whatever you edited it to)
metricConfig — the per-value-type configuration ({ action }, { numerator_action, denominator_action }, etc.)
title — the human-readable rendering of the event name
The existing_sdk_call is recorded as a hint, not a hard reference — your Mixpanel/Segment/etc. setup is independent.

You set baseline metrics on each Dev Item separately, in the dashboard. The skill doesn’t pre-populate baselines — that’s a deliberate user step.

Input: `discover-output.json`

The skill reads this contract:

{
  schema_version: 1;
  generated_at: string; // ISO8601 UTC
  candidates: Array<{
    feature_id: string;
    value_type: "count" | "percentage" | "duration" | "activity" | "currency";
    metric_config:
      | { action: string }
      | { numerator_action: string; denominator_action: string }
      | { start_action: string; end_action: string }
      | null;
    title: string;
    description: string;
    confidence: "high" | "medium" | "low";
    existing_sdk_call: { sdk: string; event_name: string } | null;
    insertion_points: Array<{
      file: string;     // repo-relative
      line: number;
      role: string;     // matches a key in metric_config
    }>;
  }>;
}

You don’t write this file by hand. vektis-discover and vektis-update produce it for you.

Hard guarantees

Bulk endpoint is called BEFORE any file write. If creating Dev Items fails, no source code is touched.
No file is written without an explicit diff approval (per file or approve all).
Atomic writes — temp file plus rename. Mid-write failures discard the partial file.
Existing analytics calls are preserved. v1 ADDS vektis.track(); it never removes Mixpanel/Segment/etc.
The skill never opens a PR for you — it prints the gh pr create command and offers to run it if gh is authenticated.

What happens when something goes wrong

Situation	What the skill does
`discover-output.json` missing	Exits with a hint to run `vektis-discover` first
`discover-output.json` is older than 7 days	Warns and asks if you want to continue or re-scan
Working tree is dirty	Refuses; tells you to stash or commit
Authentication fails	Exits at the auth step. No bulk-create call is made.
Bulk-create returns a 4xx	Prints the response body (it has validation details). No files are touched. Fix the discover output and re-run.
Bulk-create returns a 5xx	Prints the body and suggests re-running. The bulk endpoint is best-effort idempotent — re-running resumes cleanly.
All candidates already exist as Dev Items	Skill prints “All N candidates already exist; proceeding to instrumentation.” and continues to the source-code phase.
All target files have drifted since discover	Skill prints “Re-run `vektis-discover`” and exits without writing.
You type `cancel` at the diff prompt	Exit cleanly. The Dev Items are still in your VEKTIS dashboard — soft-delete them in `/dev` if you don’t want them.
Mid-write file permission error	Atomic write means partial state is impossible — the half-written file is discarded. Fix the permission and re-run.

Currency-only candidates

The skill never auto-instruments currency value types. Revenue events typically carry the dollar amount in their event payload, and the right vektis.track() call shape depends on how your code packages that amount — too project-specific to template safely.

If your discover output had currency candidates:

The skill prints a warning row in the summary listing them.
Other candidates instrument normally.
After running, manually wire those currency Dev Items in your VEKTIS dashboard (via the Configure Tracking dialog) so VEKTIS knows what shape of event to expect.

Flags

--paste-token — skip OAuth and use a manually-pasted CLI token. Useful on headless / SSH / locked-down environments.

Skills overview
vektis-discover — produces the input file
vektis-bootstrap — runs this skill as part of an end-to-end setup
vektis-update — periodic re-scan that produces the same input file shape
feature_id reference — what the feature_id field means and how it connects SDK events to Dev Items
Creating and Managing Dev Items — what to do in the dashboard after instrumentation