vektis-update

vektis-update is the incremental sibling of vektis-discover. It runs the same scan, but applies two filters that drop already-tracked features. The result: you only review NEW analytics calls added since your last pass.

claude /vektis-update

Same output contract as vektis-discover — it writes .vektis/discover-output.json, which vektis-instrument consumes. The two skills are interchangeable from the instrument step onwards.

When to use this skill

You’re in this situation	Use this skill
You shipped a release that added new analytics calls	`vektis-update`
Monthly maintenance pass to catch drift	`vektis-update`
First time on a codebase, or after a major restructure	`vektis-discover`
Want to install the SDK at the same time	`vektis-bootstrap`

The two delta filters in this skill would drop nothing on a fresh codebase, but the empty-output messaging is wrong for that case. On first runs, prefer vektis-discover.

What the delta filters do

The skill runs vektis-discover’s scan and candidate-builder unchanged. Then it applies two filters in sequence to drop already-tracked features:

Filter 1 — source-proximity

For every candidate, the skill examines the lines around each insertion point. If a vektis.track(...) call appears within 5 lines (above or below) of the matched SDK call, the candidate is treated as already-instrumented and dropped.

This is a fast pre-filter that catches the most common case: instrumentation that’s still adjacent to its source SDK call. It’s deliberately conservative — partial instrumentation is rare, and the next filter is the authoritative one.

Known false negative: if the vektis.track() was moved more than 5 lines away (e.g., extracted into a helper function or moved to a different file during a refactor), this filter misses it. The Dev Item filter below catches those cases.

Filter 2 — Dev Item filter

The skill fetches the list of featureId values that already have non-deleted Dev Items in your VEKTIS organization, and drops any candidate whose normalized feature_id matches.

This is the authoritative signal: if a Dev Item exists for feature_id=checkout-completed, that feature is tracked, regardless of whether the source-side vektis.track() call still sits adjacent to its original SDK call.

What it walks through

Pre-flight. Same as discover — verifies project root, refuses to run inside the VEKTIS source tree.
Existing-output prompt. If .vektis/discover-output.json already exists, the skill asks whether to overwrite it on done or cancel.
Authenticate. OAuth browser flow on first run, cached afterwards.
Run the discover sweep. Same regex coverage, same candidate-row builder. The full pre-filter list is in vektis-discover.
Apply delta filters. Source-proximity filter, then Dev Item filter.
Render the delta candidate table. Same UI as discover, with an extra header line above the table:
```
Delta scan — found N NEW features since last instrumentation.
(M features were skipped because they're already tracked in VEKTIS or instrumented in source.)
```
The M count is reassuring — it confirms the filters are doing real work.
Atomic write on done. Same as discover.

Empty-delta is a SUCCESS state

If the filters drop every candidate, the skill prints:

✓ Your codebase is fully instrumented as of last scan.

No new features detected. M existing analytics-SDK calls were already tracked in VEKTIS or instrumented in source.

Next time you ship a feature with new analytics, re-run /vektis-update to catch it.

This is not an error. It means you don’t have any drift. The skill exits cleanly, doesn’t write .vektis/discover-output.json, and doesn’t touch .gitignore.

Same output contract as `vektis-discover`

The output file is .vektis/discover-output.json with schema_version: 1. Identical shape to what vektis-discover produces. vektis-instrument consumes it without modification — it doesn’t care which skill wrote it.

Customer-control points

--paste-token — skip OAuth and paste a manual token instead. Useful on headless servers.
--scope <path> — narrow the scan to a subdirectory. Useful for monorepos.
Existing-output prompt — overwrite or cancel before any new scan starts.
Candidate review table — same approve all / reject N / edit N ... / cancel / done as discover.

Hard guarantees

Read-only. Same as vektis-discover. The only writes are .vektis/discover-output.json (on done) and an idempotent .gitignore append.
Never silently overwrites an existing .vektis/discover-output.json — always prompts.
Never throws. File-write failures degrade to printing the candidate JSON in chat.
Empty delta is success. Never re-surfaces already-tracked features.

What happens when something goes wrong

Situation	What the skill does
Project root not detected	Pre-flight exits with a hint to run from project root
Authentication fails	Exits at the auth step, no scan runs
Existing `.vektis/discover-output.json` present	Prompts before overwriting
Token expires mid-run when fetching the existing-feature list	Clears cached credentials and exits; re-run prompts re-auth
Scan exceeds 60 seconds on a large monorepo	Prints progress every 15 seconds; suggests `--scope <path>`
File-write permission denied / disk full	Prints the candidate JSON in chat with manual-save instructions
Empty delta after filtering	Prints the success message; no file written

Cadence guidance

There’s no built-in scheduler for vektis-update. Run it manually:

After every release that includes new analytics calls.
Monthly as a maintenance pass even when you’re not sure anything new shipped.
After major refactors where instrumentation might have moved further than 5 lines from the source SDK call (the source-proximity filter’s blind spot — Dev Item filter still catches these, but a fresh full scan via vektis-discover is the cleanest reset if you suspect significant drift).

What this skill does NOT do

Modify any source file (read-only — same as vektis-discover).
Insert vektis.track() calls — that’s vektis-instrument.
Create Dev Items — also vektis-instrument.
Replace vektis-discover for first-time scans.
Run on a schedule. Manual command only in v1.
Scan only files changed since last run. v1 always does a full sweep, then filters.

Skills overview
vektis-discover — full sweep, no delta filters
vektis-instrument — what consumes the output
vektis-bootstrap — first-time setup, including discover and instrument