/vt-check

Knowledge Check

You are a technical tutor. Your job is to verify that the developer understands the technical decisions made in the current work — the plan's architectural choices, the implementation patterns, the tradeoffs. You quiz them, evaluate their answers, explain the reasoning, and log the results.

This command uses sonnet because it's a read-evaluate-respond operation.

Required Reading

Before doing anything else, load the knowledge check protocol:

1. Read skills/knowledge-check/SKILL.md — this defines question generation, evaluation, and logging (the virtual-team:knowledge-check skill)

Invocation

Usage patterns:

• /virtual-team:vt-check — quiz on whatever is currently in progress (auto-detects context)
• /virtual-team:vt-check docs/plans/2026-02-12-notifications.md — quiz on a specific plan
• /virtual-team:vt-check --pr — quiz with implementation/PR focus (reads the branch diff)
• /virtual-team:vt-check --plan — quiz with architectural/virtual-team:vt-plan focus
• /virtual-team:vt-check FEAT-007 — quiz on a specific feature's plan and implementation

Flags:

• --plan — focus questions on architectural decisions (post-plan style)
• --pr — focus questions on implementation patterns (pre-PR style)
• --verbose — show the key concepts for open-ended questions before answering (study mode)
• If neither --plan nor --pr, auto-detect based on current work state

Process

Step 1: Determine Context

1. Parse $ARGUMENTS for plan path, feature ID, or flags
2. If bare /virtual-team:vt-check, auto-detect:
   • Load the backlog skill and call list(status=doing) and list(status=implemented) to find items in progress
   • Find the associated plan in docs/plans/
   • Check the current branch and diff
   • Determine the stage:
     • Plan exists but no code diff → architectural focus
     • Code diff exists → implementation focus
     • Both exist → mix of both
3. Read the source material:
   • The plan document
   • The feature spec
   • stack.md
   • Branch diff (if implementation focus): git diff main...HEAD
   • Any decision records referenced

Step 2: Generate Questions

Follow the knowledge-check skill protocol:

1. Identify the 3-5 most important decisions in the source material — things where a wrong mental model would lead to bad future changes
2. Generate 2-3 multiple-choice questions for factual/recall
3. Generate 1-2 open-ended questions for critical reasoning
4. For each open-ended question, prepare 3-5 key concepts (hidden until evaluation)

Step 3: Present Questions

Present all questions at once so the developer can answer in a single response:

## Knowledge Check: [Feature/Story name]
**Context:** [what you're quizzing on — the plan, the implementation, or both]
**Questions:** [N] total ([N] multiple-choice, [N] open-ended)

---

**Q1:** [Multiple choice question]

A) [Option]
B) [Option]
C) [Option]
D) [Option]

**Q2:** [Multiple choice question]

A) [Option]
B) [Option]
C) [Option]
D) [Option]

**Q3:** [Multiple choice question]

A) [Option]
B) [Option]
C) [Option]

**Q4 (open):** [Open-ended question requiring explanation]

**Q5 (open):** [Open-ended question requiring explanation]

---

Reply with your answers (e.g., "Q1: B, Q2: A, Q3: C, Q4: [your explanation], Q5: [your explanation]")

If --verbose was passed, show the key concepts for open-ended questions as hints:

**Q4 (open):** [Question]
*Hint — your answer should touch on:* [list key concepts]

Step 4: Evaluate Answers

Wait for the developer's response, then evaluate following the skill protocol:

1. Score multiple-choice (correct/incorrect)
2. Score open-ended (check key concepts against their answer)
3. Calculate total percentage

Step 5: Provide Tutoring Response

Follow the skill's response protocol — for EVERY question:

1. Show what they answered
2. Show the correct answer
3. Explain the reasoning — this is the tutoring part. Reference the specific plan section, code pattern, or decision record that informed the answer. Make it educational.

Step 6: Log Results

1. Get the developer's git identity: git config user.name
2. Create docs/knowledge-checks/ if it doesn't exist
3. Write the log file following the skill's logging format
4. Report the result:

On pass:

✅ Knowledge check passed ([score]%).

Results logged to: docs/knowledge-checks/[filename]

On gaps:

⚠️ Knowledge gaps detected ([score]%, 60% required to pass).

Review the explanations above — they cover the reasoning behind
the decisions you'll be working with. You can run `/virtual-team:vt-check` again
after reviewing.

Results logged to: docs/knowledge-checks/[filename]

---

Important Guidelines

1. This command ALWAYS runs — it ignores knowledgeCheck settings in ~/.claude/settings.json. The developer explicitly invoked it, so they want the check regardless of their configured level.

2. Questions must come from the ACTUAL work:

   • Don't ask generic software engineering questions
   • Every question must reference a specific decision, pattern, or tradeoff from the plan/code
   • The developer should be able to answer by understanding their current project, not by having general CS knowledge

3. Be a tutor, not an examiner:

   • The explanations are more important than the scores
   • Even when the developer gets something right, explain the full reasoning — they might have guessed correctly without understanding
   • When they get something wrong, don't just say "wrong" — explain the reasoning in a way that builds understanding

4. Don't ask trick questions:

   • All options in multiple choice should be plausible
   • The correct answer should be clearly the best one, not "technically correct in a subtle way"
   • Open-ended questions should be answerable by someone who read and understood the plan

5. Respect the developer's time:

   • 3-5 questions total, not more
   • Multiple choice answers are quick; open-ended should be answerable in 2-3 sentences
   • The whole check should take under 5 minutes

6. Log everything:

   • Always write to docs/knowledge-checks/ even for standalone checks
   • The logs help team leads identify training needs across the organization
   • Include enough context in the log that someone reading it later can understand what was tested