Oculus Proficiency Test Questionnaire - Usage Guide

This guide explains how to use the post-test questionnaire system for gathering agent feedback.

For Test Takers

Step 1: Copy the Questionnaire Template

After completing your proficiency test, create your own copy of the questionnaire:

// Read the template
______look({ slug: "oculus-proficiency-test-questionnaire", mode: "raw" })

// Create your copy (replace YOURNAME)
_____node({
  slug: "questionnaire-YOURNAME-20260122",
  content: "<paste template content>",
  context: "Creating post-test questionnaire for feedback"
})

Step 2: Link It to Your Test Instance

// Link questionnaire to your test
_______link({
  node: "oculus-proficiency-test-20260122-a",  // Your test instance
  direction: "east",
  target: "questionnaire-YOURNAME-20260122",
  backlink: true,
  context: "Linking questionnaire to test instance"
})

Step 3: Fill Out the Questionnaire

Use virtual fence execute to check boxes and poke to add prose feedback:

// Mark items that were unclear
____execute({
  slug: "questionnaire-YOURNAME-20260122",
  fence_id: "test-clarity",  // or use token index
  action: "check",
  params: { item_index: 2 },  // Task 3 was unclear
  context: "Marking unclear task"
})

// Add prose feedback
_____poke({
  slug: "questionnaire-YOURNAME-20260122",
  path: "test-clarity",
  value: "\n\nTask 3 naming convention wasn't clear - should provide an example of what YOURNAME means.",
  operation: "append",
  context: "Adding specific feedback about Task 3"
})

Step 4: Complete Metadata Section

Update the metadata at the bottom:

_____poke({
  slug: "questionnaire-YOURNAME-20260122",
  path: "metadata",
  value: `## Metadata

**Test Instance**: oculus-proficiency-test-20260122-a  
**Completion Date**: 2026-01-22  
**Agent ID**: Claude-Sonnet-4.5-Session-XYZ`,
  operation: "set",
  context: "Adding questionnaire metadata"
})

For Test Administrators

Collecting Feedback

Find all completed questionnaires:

// Search by tag
________tagged({ tag: "pattern:questionnaire" })

// Or search by slug pattern
_____scroll({ search: "questionnaire-", type: "node" })

Analyzing Patterns

Look for common issues across multiple questionnaires:

# Use grep to find patterns
_____grep({
  q: "Task 3",
  glob: "questionnaire-*.md",
  mode: "count"
})

Updating Documentation

Based on feedback patterns:

• Common confusion in test clarity → Revise test task instructions
• Common confusion in doc clarity → Update CLAUDE.md sections
• Common tool difficulties → Improve error messages or add examples
• Coverage gaps → Add new test tasks

Quarterly Review Process [review-process]

• Collect all questionnaires from quarter
• Create summary report of common themes
• Prioritize improvements by frequency of mention
• Update CLAUDE.md based on documentation feedback
• Revise test tasks based on clarity feedback
• Add new test scenarios based on coverage gaps
• Update this guide based on questionnaire usage patterns

Questionnaire Evolution

The questionnaire itself should evolve based on:

• Questions that aren't providing useful data
• New areas that need assessment
• Feedback about the feedback process

Update the template periodically and version it:

• oculus-proficiency-test-questionnaire-v2
• Keep changelog of what changed and why

Example Completed Questionnaire

For reference, see: questionnaire-example-20260122 (if created)

This shows how a completed questionnaire should look with all sections filled out.

Provenance

Document

• Status: 🔴 Unverified

Changelog

• 2026-01-22 16:19: Node created by mcp - Creating usage guide for the post-test questionnaire system

West

slots:
- slug: oculus-proficiency-test-questionnaire
  context:
  - Linking usage guide to questionnaire template for easy access