Skip to content

Pre-Computed JSON Sidecar for O(1) Manifest Lookup

Problem

When a runtime command (e.g., /vt-c-skill-finder) needs to search or filter across 118 SKILL.md files, naive approaches either:

  1. Re-scrape at invocation — O(N) file reads and awk parsing on every call. Acceptable for N=10, painful for N=100+.
  2. Bundle into one large file — merges concerns and makes incremental updates hard.

Solution: Pre-Computed JSON Sidecar

Generate a flat JSON array at commit-time (not invocation-time) by the same script that produces the human-readable artifact. The sidecar stays in sync automatically because it's a second output of the same generator run.

Generator (bin/generate-skill-map.sh)
  → docs/skill-orchestration-map.md    (human-readable)
  → docs/skill-orchestration-map.json  (machine-readable sidecar)

The JSON uses a flat array (not nested by category) so consumers can filter/sort without knowing the category structure:

[
  {
    "name": "vt-c-activate",
    "category": "Core Workflow",
    "description": "Load specs for development...",
    "scope": "repo",
    "trigger_type": "explicit"
  },
  ...
]

Consumer lookup is O(1) via jq filter: 

jq '.[] | select(.trigger_type == "proactive")' docs/skill-orchestration-map.json

When to Apply

  • The consuming command needs to query structured metadata across many source files
  • The metadata only changes when source files are committed (not at runtime)
  • Stage A (generator) and Stage B (consumer) are developed in separate specs — the sidecar is the stable API between them

Schema Stability

Define the sidecar schema explicitly in the generating spec, including a schema_version field. Any schema changes require a SPEC-NEXT patch or a new spec — otherwise Stage B breaks silently.

{ "schema_version": "1", "generated_at": "...", "skills": [...] }

Trade-offs

Approach Latency Sync risk Complexity
Re-scrape at invocation O(N) per call None Low
Pre-computed sidecar O(1) per call Low (pre-commit reminder) Medium
Database / index O(log N) per call Requires migration High

For N≈100-200 and infrequent generator updates, the sidecar is the sweet spot.

  • SPEC-125 AD-2 (Architecture Decision Log)
  • SPEC-125 (Stage B): /vt-c-skill-finder will consume this sidecar