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:**
```yaml
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:**
```yaml
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:**
```yaml
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):

```bash
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:

```bash
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:

```bash
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