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"
date: dd-mm-yy
```

**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.

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.

**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.

**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.

## Output Format

```
Context file paths with frontmatter:
  process/context/skills/skill-apps.md (context:skill-apps — Skill app runtime, vite architecture, ctx-gateway, deployment)
  process/context/tests/all-tests.md (context:all-tests — Test routing, runner split, debugging procedures)

Plan files with frontmatter:
  process/features/{feature}/completed/{slug}_{date}/{slug}_PLAN_{date}.md (plan:{plan-name} — short description...)

Files without frontmatter (path only):
  process/context/ui/design.md
```

## Context Envelope

At session start, every inner-loop agent (research / plan / execute / update-process) emits a
**Context Envelope** — a 10-field table capturing the orientation an agent needs to act. All 10
fields are required (use best-effort values; `TBD — [reason]` when not yet determinable). The fields
MUST appear in the EXACT canonical C-2 order below — identical order in this SKILL and in all four
inner-loop agents:

| # | Field | Value |
|---|---|---|
| 1 | `feature` | feature folder name (or `TBD`) |
| 2 | `phase` | current RIPER phase (`RESEARCH` / `INNOVATE` / `PLAN` / `PVL` / `EXECUTE` / `EVL` / `UPDATE-PROCESS`) |
| 3 | `session-goal` | one-line goal from the `/goal` block |
| 4 | `branch` | current git branch |
| 5 | `worktree` | worktree path (or `main`) |
| 6 | `context-group` | relevant `process/context/` group (or `none`) |
| 7 | `