Vc Context Discovery

vc-context-discovery

Output style: Follow process/development-protocols/communication-standards.md — answer-first, plain language, no unexplained jargon, TL;DR on long responses.

Discover and load all relevant context for the current task. This skill lists feature group nested files with full paths and loads process/context/ files by domain routing table. It is the canonical context-loading entrypoint for every agent session.

When To Invoke

At the start of every agent session (research, innovate, plan, validate, execute, update-process, fast-mode). Also at the start of any skill that needs repo context before operating.

Frontmatter Schemas

Document the canonical schemas for three file types used across the repo. These schemas enable frontmatter-aware routing and filtering.

Context file frontmatter schema:

name: context:{slug}
description: "one-line scope — used by vc-context-discovery for routing"
keywords: comma, separated, task, vocabulary, terms   # drives grep-first keyword routing
related: [context:{other-slug}, context:{another-slug}]  # sibling/cross-group links (optional)
date: dd-mm-yy

• keywords — strongly recommended, non-empty. Comma-separated task-vocabulary terms an agent would use to describe a task this doc serves (e.g. session, token, refresh, jwt, login). This is the match surface for discover-context.mjs --match; weak/absent keywords are why a relevant doc never gets routed to. Lint WARNS when empty (so existing projects don't break on sync) — backfill at UPDATE-PROCESS.
• related — OPTIONAL list of context:{slug} values for sibling docs that are usually needed together (the markdown-native equivalent of cross-links). Every slug listed MUST resolve to a real context: doc; dangling links fail lint. Discovery follows these after the primary match so a task touching two domains loads both.

Plan file frontmatter schema:

name: plan:{slug}
description: "one-line scope and feature"
date: dd-mm-yy
feature: {feature-folder-name}
phase: "{phase-id}"  # optional, for phase program plans only

Report file frontmatter schema:

name: report:{slug}
description: "one-line scope"
date: dd-mm-yy
metadata:
  node_type: memory
  type: report
  feature: {feature-folder-name}
  phase: {phase-id}

Invocation

Primary method — run the auto-discovery script. It lists all nested files under process/context/, process/development-protocols/, process/general-plans/active/, and (with --feature) the feature folder, extracting ONLY the leading YAML frontmatter block of each .md file (no whole-file reads):

node .claude/skills/vc-context-discovery/scripts/discover-context.mjs [--feature <name>] [--json]

The script groups output into: context files with frontmatter, protocol files, feature files by subfolder, active general plans, and files-without-frontmatter (path only). It never throws on a missing root and exits 0 unless given a bad flag. Use --json for a machine-readable object. Prefer this over manually reading each file — it is deterministic and avoids loading huge files into context.

Keyword-first routing (deterministic, not judgment). When the task vocabulary does not obviously map to a routing-table row, do not guess — let the index do the matching:

node .claude/skills/vc-context-discovery/scripts/discover-context.mjs --match "update the user ORM model"

This tokenizes the task and ranks context docs by overlap with their frontmatter keywords, then appends any related: siblings of the top hits. Read the ranked docs in order. This is the fallback that fixes "the right doc existed but the agent walked past it."

Routing-table generation (drift-proof index). The "Current Root Entry Points" and "Current Context Groups" tables in all-context.md are GENERATED from frontmatter, not hand-authored — they live between <!-- GENERATED:routing --> / <!-- /GENERATED:routing --> markers. Rebuild them after any context-org change:

node .claude/skills/vc-context-discovery/scripts/discover-context.mjs --emit-routing   # rewrites the block
node .claude/skills/vc-context-discovery/scripts/discover-context.mjs --check-routing  # lint: block in sync?

The hand-authored Task Routing Table (task-type → file) stays editorial and is NOT generated.

Per task-folder artefact colocation, the script surfaces each task's plan, spec, reports, and references INSIDE its own {slug}_{date}/ task folder; the sibling reports//references/ dirs are deprecated and only hold legacy artefacts.

Workflow (manual FALLBACK)

Use these steps only if the script above fails or is unavailable.

Step 1. Run find process/context/ -type f | sort and record all available context files.

Step 2. Run find process/development-protocols/ -type f | sort and record all protocol files.

Step 3. Read process/context/all-context.md to get the routing table and current feature list.

Step 4. If a feature name was provided as the argument, run find process/features/{feature}/ -type f | sort to list ALL artifacts across all subfolders (active/, completed/, backlog/, plus any legacy reports/, references/). Surface full file paths — not just folder names. Per task-folder artefact colocation, expect each task's plan, spec, reports, and references INSIDE its own {slug}_{date}/ task folder; the sibling reports//references/ dirs are deprecated and only hold legacy artefacts.

Step 5. If no feature name was provided, run find process/general-plans/active/ -type f | sort to surface any active plans relevant to the current task. Note: plan files are inside {slug}_{date}/ task subfolders — look one level deep for *_PLAN_*.md files.

Step 6. From the routing table in all-context.md, identify the context group files relevant to the current task domain (e.g. tests, container, infra, skills, uxui, workflows). Do NOT read every context file — only the ones the routing table says apply to this domain. If no row obviously matches, run discover-context.mjs --match "<task>" and use its ranked keyword hits instead of guessing.

Step 7. Read the domain context file(s) identified in step 6. Each all-{group}.md is a router — after reading it, follow its routing table to load the deeper domain file(s) for the task. Then load any related: siblings of the docs you read — a task spanning two domains (e.g. auth + tests) needs both, and related is how the cross-domain link is declared.

Step 8. Frontmatter extraction: For each file in the discovered set, if the file has YAML frontmatter (a --- block at top), extract the name, description, and date fields. Surface in output as "[path] (name: X — description: Y)". Files without frontmatter: surface path only (no error, do not skip them).

Step 9. Report: full file listing for the feature folder (if applicable), active context files loaded, and any open gaps in context that would block the task.