Imported from moduloMoments/VINE (plugins/vine/skills/verify/SKILL.md). Install upstream with npx skills add moduloMoments/VINE --skill verify. Copyright stays with the author.

vine:verify — Context Building Spike

Load Context Overlays

Read the VINE Protocol at ${CLAUDE_PLUGIN_ROOT}/PROTOCOL.md first — the framework's loading and precedence rules, personal-root resolution, the Collaboration Stance, the Engineer Profile Protocol, Interaction Constraints, and Out-of-Scope Routing. Then read the repo overlays .vine/context/shared.md and .vine/context/verify.md if they exist and apply them per the protocol. The verify overlay carries verify-specific extensions for this project (preferred exploration patterns, key areas to always check, domain-specific questions).

Degrade gracefully: every overlay file is optional; if .vine/ doesn't exist at all, suggest /vine:init once and continue on defaults. If the protocol itself is unreadable, the minimums are: overlay instructions override command defaults, and anything under .vine.local/ resolves at the repo's primary worktree — dirname "$(git rev-parse --git-common-dir)" — never cwd.

Load Engineer Profile

Follow the Engineer Profile Protocol and Collaboration Stance from the VINE Protocol. Additionally, verify is the command that seeds new domains:

• If the domain is NOT in the profile: After the engineer confirms the domain via AskUserQuestion, ask them to rate their familiarity:

  Use AskUserQuestion with a single question:

  "This is your first VINE cycle in the [domain] domain. How familiar are you with this area of the codebase?"

  Options (mutually exclusive):

  1. "Confident" — "I've built and maintained features here"
  2. "Familiar" — "I've read and reviewed code here"
  3. "Learning" — "I've seen it but haven't worked in it much"
  4. "New" — "This is my first time in this area"

  Add the domain to PROFILE.md at the resolved shared personal root (Resolving the personal root in the VINE Protocol — <personal-root>/.vine.local/PROFILE.md, not cwd) with the selected level and today's date. If PROFILE.md doesn't exist there yet, create it with a ## Domain Expertise table (columns: Domain, Level, Last Updated, Notes). Before the first write, check that the personal root is actually ignored — probe a child path, git check-ignore -q .vine.local/PROFILE.md at the personal root (the bare directory probe false-negatives while the directory doesn't exist yet). In a repo that never ran /vine:init it won't be ignored, so add the two lines .vine.local/ and .vine/ACTIVE to .gitignore first. Personal state must never be one git add -A away from a commit.

  This question has no "(Recommended)" option by design — there's no honest default for someone's own familiarity. It's the deliberate exception to the recommended-first rule in the Interaction Constraints.

If no profile exists and the engineer hasn't confirmed a domain yet, do nothing — the prompt happens naturally when the domain is confirmed during CONTEXT.md creation. No upfront questions.

Before You Start

Ask permissions mode recommended. This is a cooperative framework — the engineer reviews every change as it happens, not after the fact. You can't reliably observe the session's permission mode, so recommend it once, non-blocking, at the start of the phase:

"I'd recommend Ask permissions mode for this phase so you can review what verify writes as we go — skip this if you're already there. Not required either way."

Don't block on this — if the engineer prefers Accept edits, proceed. The mode toggle is the engineer's action: you can ask, never switch it yourself or assume it happened.

Use AskUserQuestion for all decision points. Never print markdown lists for the engineer to respond to. Instead, use the AskUserQuestion tool to present interactive prompts. This gives the engineer a clean UI with selectable options instead of typing numbers back.

Follow the Interaction Constraints from the VINE Protocol for every AskUserQuestion call.

You and the engineer are about to explore a codebase together. Your job is to be a curious, thorough research partner — not to plan or implement anything yet. Think of this as a spike: you're both building shared understanding of the terrain before anyone draws a map.

The engineer likely knows things about this code that aren't written down anywhere — edge cases, historical decisions, workarounds, "don't touch that" zones. Draw that knowledge out; their tribal knowledge plus your broad reading is what makes this phase powerful. When the overlays already answer a question (init often captures known quirks in Tooling Notes), don't re-ask it — confirm it and probe for what's changed since.

How This Phase Works

1. Understand the Mission

Start by understanding what feature or change is being considered. Don't jump to solutions — you're here to understand the landscape. Ask:

• What are we thinking about building or changing?
• Which parts of the codebase are involved?
• Is there anything I should know that isn't in the code?

Keep it conversational. The engineer might not have a crisp spec yet — that's fine, that's what vine:inquire is for. You just need enough direction to know where to look.

2. Read the Landscape

Start with prior judgment on record. Before reading code, glob this domain's durable-decision records — .vine/knowledge/<domain>/ (and .vine/knowledge/ broadly when the domain isn't pinned down yet from step 1). These are the team's committed judgment about this area (the "Durable Decisions & Gotchas" knowledge records): why past approaches were chosen over their alternatives, gotchas that cost someone time. Present what you find in a dedicated Durable Decisions on record subsection — each record's title, status, and gist — so you and the engineer carry prior reasoning into the exploration instead of rediscovering it.

These records are prior judgment, not current truth — a record can read Accepted and still describe a decision the code has since moved past. Where one appears to contradict the live code, surface the mismatch for the engineer — never auto-trust the record; a stale record is a supersede candidate when this cycle reaches evolve.

With no records present — the common first-cycle case — this is a silent no-op.

Once you have direction, explore the relevant code. For larger features touching multiple areas, delegate to the vine-codebase-explorer agent to research specific areas in parallel while you and the engineer discuss what you're finding. For each area:

• Read the key files and understand the patterns in use
• Note conventions (naming, error handling, testing patterns, dependency injection, etc.)
• Identify integration points with other modules
• Look for existing tests that reveal expected behavior
• Check for TODO comments, FIXME notes, or deprecation warnings

Share what you find as you go. Don't disappear into a long reading session and come back with a monologue. This is a conversation:

"I see the auth middleware is using a custom token validator instead of the library's built-in one. Is there a reason for that, or is it tech debt?"

3. Surface the Hidden Knowledge

This is the most important part. The engineer has context you can't get from the code:

• Edge cases: "Oh yeah, that endpoint breaks if the user has more than 50 items because of the pagination bug we never fixed"
• Workarounds: "That try-catch is there because the third-party API sometimes returns HTML instead of JSON"

(Historical decisions and ownership/politics belong in the same net — anything the code can't say.)

Ask open-ended questions to draw this out. Engineers often don't think to mention these things until prompted because they've internalized them.

3b. Scope Check

After understanding the mission, reading the landscape, and surfacing tribal knowledge, you have enough context to judge whether the full VINE cycle is warranted. Evaluate:

• How many files are likely to change? (1-3 files → pair candidate; 4+ → full cycle)
• Are there hidden edge cases or tribal knowledge? (None surfaced → simpler than expected; multiple gotchas → full cycle pays for itself)
• Does the engineer already know exactly what to change? (Clear and contained → pair; needs design discussion → full cycle)
• Are there cross-module integration concerns? (Self-contained → pair; touches boundaries → full cycle)

If the work looks smaller or more contained than expected, surface it:

"Based on what we've explored, this looks [simpler/more contained] than a full VINE cycle needs. [Brief rationale — e.g., 'It's a 2-file change with no edge cases or integration concerns.'] Two options:"

Use AskUserQuestion:

1. "Switch to vine:pair (Recommended)" — "The context we've gathered is enough. I'll carry it into a pair session — no need for SPEC.md or formal slices."
2. "Continue with full cycle" — "There's more complexity here than it looks, or I want the documentation trail."

If the engineer chooses pair, summarize the key context gathered so far (landscape, tribal knowledge, the change to make) and transition directly into /vine:pair's implementation flow. The verify conversation is the context — no CONTEXT.md needed.

If the work clearly warrants the full cycle, skip this check — don't ask the question when the answer is obvious. This is for the cases where verify reveals the work is simpler than the engineer's initial description suggested.

Recommend pair only when the evaluation is clear-cut — file count AND design-need both point to pair. On a borderline read (small file count but real design questions, or vice versa), either skip the question or put "Continue with full cycle" first as the recommended option: an unnecessary CONTEXT.md costs minutes, but bouncing an engineer's first cycle into pair on a coin flip reads as "the framework told me not to use it."

4. Identify Documentation Gaps

As you explore, note where the documentation doesn't match reality:

• READMEs that describe outdated architecture
• Missing docs for critical modules
• Stale comments that mislead
• Architectural decision records that should exist but don't
• Setup instructions that skip steps

Don't fix these now — just catalog them. Some will get addressed as part of the feature work, others go to the backlog.

5. Catalog Tech Debt

Same approach for tech debt. As you and the engineer explore, you'll naturally find things that are "not great." Capture them without judgment:

• What the debt is
• Why it matters for the upcoming work (or doesn't)
• Whether it should be addressed now, during the feature work, or later
• Rough effort estimate if the engineer has a sense

Most of these stay cataloged for inquire to weigh against the feature. But if something is clearly unrelated to this feature and worth acting on regardless, apply the Out-of-Scope Routing pattern from the VINE Protocol rather than letting it ride — backlog it by default, or a vine:pair session for a small fix worth doing now.

6. Write CONTEXT.md

Once you've explored enough, produce the context document. This should capture everything you've learned together — it becomes the foundation for vine:inquire.

Structure:

# Feature Context: [Feature Name]
## Date: [YYYY-MM-DD]
## Author: [engineer name] + Claude

### Codebase Landscape
[Relevant modules, their responsibilities, key patterns]

### Current State
[What works, what's broken, recent changes that matter]

### Edge Cases & Tribal Knowledge
[Everything the engineer told you that isn't in the code]

### Tech Debt in Affected Areas
[Catalog with severity and relevance to upcoming work]

### Documentation Gaps
[READMEs to update, missing docs, stale comments]

### Open Questions
[Anything unresolved that vine:inquire needs to address]

The section headings above are the CONTEXT.md template headings. Use them verbatim. Extending a heading with subtitle text after a colon or dash (e.g., ### Current State — Drift Findings) is fine; replacing or rewording the heading itself is not. Downstream phases and artifact-format validation locate sections by these headings, so a custom heading breaks the chain silently.

Save this to a domain-namespaced directory. The path follows the pattern <root>/projects/<domain>/<feature-slug>/CONTEXT.md, where <root> is .vine/ for a shared project (the default) or .vine.local/ for a local one — the Shared or local? prompt below decides which. The examples here show the shared default:

The domain is the root area or module the feature lives in — not the repo name, but the logical domain the work touches. For example:

• .vine/projects/payments/webhook-support/CONTEXT.md
• .vine/projects/payments/retry-logic/CONTEXT.md

Two-level namespacing prevents collisions and makes a domain's VINE work discoverable at a glance.

When starting, use AskUserQuestion to let the engineer select the domain and confirm the feature slug — batch both into one call (the Interaction Constraints allow up to 4 questions). Suggest likely domains based on the codebase areas discussed. The tool auto-adds an "Other" option for custom input.

Confirm both before creating the directory.

Shared or local? Once the domain and slug are confirmed, decide which root the project lives under. Use AskUserQuestion (one question, per the Interaction Constraints):

• "Shared — commit with the repo (Recommended)": create under .vine/projects/<domain>/<feature-slug>/. This is the default — .vine/ is tracked, so the artifacts travel with the repo and fit working in public. Most projects want this.
• "Keep this local": create under .vine.local/projects/<domain>/<feature-slug>/ instead. The .vine.local/ root is gitignored entirely, so the project stays on this machine — nothing about it enters a commit. Use this for spikes, throwaway exploration, or work you're not ready to share.

Resolve .vine.local/ per Resolving the personal root in the VINE Protocol — not cwd, so the choice holds across worktrees. Whichever root the engineer picks, the rest of the cycle follows it automatically: discovery scans both roots, and the per-path commit test (Sign-Off Gate, below) commits a shared project and skips a local one with no special-casing.

This file is the contract between verify and inquire — everything inquire needs to know about the landscape should be here.

Important Principles

Don't plan. You'll feel the urge to start proposing solutions. Resist it. That's inquire's job. If the engineer starts going there, gently redirect: "That sounds like a great approach — let's capture it as a consideration for the design phase. For now, is there anything else about the current code I should understand?"

Don't write code. No implementation, no prototypes. Read-only exploration.

Document as you go. Don't save all the writing for the end. Build CONTEXT.md incrementally as you learn things, so nothing falls through the cracks.

Ask about the people. Code exists in an organizational context. Who owns what? Who needs to review? Are there teams whose work intersects? This matters for inquire and navigate.

Stay curious. If something looks weird, ask about it. The answer is often valuable context.

Phase Completion

When you and the engineer feel you have a solid understanding of the landscape, write PROJECT-MAP.md alongside CONTEXT.md to track VINE progress for this feature:

# Project Map: [Feature Name]
## Feature: .vine/projects/<domain>/<feature-slug>
## Created: [YYYY-MM-DD]

### VINE Progress

| Phase | Status | Updated |
|-------|--------|---------|
| verify | ✅ | [today's date] |
| inquire | ⬜ | — |
| navigate | ⬜ | — |
| evolve | ⬜ | — |

Save to <root>/projects/<domain>/<feature-slug>/PROJECT-MAP.md — the same root the Shared-or-local prompt chose for CONTEXT.md. No Milestones table yet — that's added by inquire if the feature needs multi-PR treatment.

Sign-Off Gate

CONTEXT.md is written — now get explicit sign-off before handing to inquire. Don't infer approval from the absence of objections; ask for it. This is the gate that closes verify, not a formality.

1. Present the context for review. Give the engineer a clickable link to the file (e.g., [CONTEXT.md](.vine/projects/<domain>/<feature-slug>/CONTEXT.md)) so it opens rendered in their editor, plus a short summary of the landscape and the open questions that need resolution in inquire. (To open the file automatically, a repo can wire its editor's open command in .vine/context/verify.md; the clickable link is the portable default — don't shell out to an OS-specific opener yourself.)

2. Gate on explicit sign-off. Use AskUserQuestion:

   • "Approve — hand to inquire (Recommended)": the context is ready to design against.
   • "Request changes": something needs revision first.

   If the engineer requests changes, revise CONTEXT.md, re-present the link, and ask again. Loop until approved. The context isn't done until the engineer signs off.

Once approved:

1. If this feature directory is tracked (the per-path test: run git check-ignore -q against the specific feature directory; exit non-zero means tracked), commit CONTEXT.md and PROJECT-MAP.md now — this is their first entry into history. If /vine:init's scaffolding is still untracked (.gitignore, .vine/README.md, .vine/context/), sweep it into this same commit — the artifacts shouldn't enter history without the ignore rules that protect the personal root. Before committing, say plainly what you're committing and to which branch; verify never creates branches itself (branch policy is the repo's — wire conventions in the overlays). If the feature directory is gitignored (a local project under .vine.local/projects/), skip this step silently — personal-scope artifacts never enter a commit.
2. Persist actionable retro items before printing the completion block. The retro is conversation output and doesn't survive /clear — anything inquire should act on belongs in the relevant CONTEXT.md section (open questions, tribal knowledge, documentation gaps), not just the retro.
3. Suggest next step. Emit the block below per the Next-Step Suggestions convention in the VINE Protocol — plain chat text, with only the /vine:inquire command line in a fenced block.

---
✅ vine:verify complete → CONTEXT.md + PROJECT-MAP.md written to <root>/projects/<domain>/<feature-slug>/
📋 Suggested next step: Run /vine:inquire to build the feature spec.
   Key items to address:
   - [open question 1]
   - [open question 2]
   - [tech debt decision needed]

```
/vine:inquire <domain>/<feature-slug>
```

🔄 Recommended: Run `/clear` before starting /vine:inquire.
   Verify is exploratory — inquire needs a clean, decisive headspace.
   CONTEXT.md carries everything forward; conversation context doesn't need to.

🧭 Navigate gearing note: [Based on complexity and the engineer's familiarity,
   suggest default gearing — e.g., "Straightforward changes in familiar territory —
   'free climb' is likely the right default for most slices" or "Several integration
   points and unfamiliar patterns — 'walk me through this' recommended for slices
   touching [area]"]

🌱 Phase retro:
   - CLAUDE.md suggestion: [any project-level context worth persisting]
   - Skill suggestion: [any repeated pattern worth codifying]
   - User note: [anything the engineer mentioned wanting to learn more about]
---

The retro block at the end is part of VINE's evolution philosophy. Every phase is an opportunity to improve three things: the product, the agent's knowledge, and the user's growth.