First-Time User: UCV-CLI

Inherits from:

_shared/first-time-user-base.md

All by following ONLY the documentation. </purpose>

<when_to_activate> Activate when:

• User says "test ucv-cli docs", "first-time cli user"
• User wants to audit UCV-CLI documentation
• User asks "can someone figure out the CLI?"
• Before/after CLI documentation changes

Trigger phrases: "test ucv-cli", "cli docs", "first-time cli", "audit cli", "test interactive cli" </when_to_activate>

1. Setup — Create persona and mock JD, output start message
2. Discovery — Search for CLI documentation using grep/ls
3. Happy Path — Attempt: launch → navigate → create → pipeline → view issues
4. Errors — Test: non-TTY, empty variants, pipeline failures
5. Report — Generate audit report, save to docs/audits/

After each phase, report findings before continuing to next phase. </instructions>

SIMULATE CONFUSION: When docs are unclear, document the confusion rather than solving it yourself.

MOCK DATA: Create realistic mock job descriptions for testing. </constraints>

<critical_note> TTY REQUIREMENT: The CLI will FAIL in non-interactive environments (CI, pipes, some IDE terminals).

• Test what happens when TTY unavailable
• Document if error message explains the limitation
• This is often the #1 blocker for new users </critical_note>

Phase 1: Setup

1.1 Create Persona

persona:
  name: "[Random realistic name]"
  role: "PM looking to apply to jobs"
  goal: "Use the CLI to manage my portfolio variants"
  context:
    - Has a job description to target
    - Never used UCV-CLI before
    - Knows basic CLI/npm
    - Wants to create and validate a variant

1.2 Create Mock Data

mock_jd: |
  Senior Product Manager - Developer Platform

  We're looking for a PM to lead our developer platform initiatives.

  Requirements:
  - 5+ years PM experience
  - Developer tools or API experience
  - Strong technical background

  Nice to have:
  - Web3/crypto experience
  - Open source contributions

mock_company: "TechCorp"
mock_role: "Senior Product Manager"

1.3 Output Start Message

Tell user: "Starting UCV-CLI first-time user simulation as [persona name]..."

Phase 2: Discovery

2.1 Search for Documentation

# What docs mention ucv-cli?
grep -r "ucv-cli" docs/ README.md --include="*.md" -l

# Check package.json for CLI commands
grep "ucv-cli" package.json

# Look for CLI guide
ls docs/guides/

2.2 Record Discovery Experience

discovery:
  found_in_readme: true|false
  found_dedicated_guide: true|false
  guide_path: "docs/guides/universal-cv-cli.md"
  clear_when_to_use: true|false
  friction: "Description of any confusion"

2.3 Documentation Locations to Check

README.md

docs/guides/universal-cv-cli.md

GETTING_STARTED_GUIDE.md

Phase 3: Happy Path

3.1 Launch CLI

npm run ucv-cli

Record:

launch:
  command_documented: true|false
  prerequisites_clear: true|false
  works_in_terminal: true|false
  tty_requirement_documented: true|false
  friction: "What was unclear?"

3.2 Navigate Dashboard

First impressions:

dashboard_ui:
  layout_intuitive: true|false
  status_icons_explained: true|false
  keyboard_controls_visible: true|false
  help_available: true|false
  friction: "What elements were confusing?"

Test navigation:

3.3 Create Variant

Press

c

creation_flow:
  how_to_start_documented: true|false
  guided_prompts_clear: true|false
  fields_validated: true|false
  friction: "What was confusing?"

Post-creation:

after_creation:
  variant_appears_in_list: true|false
  auto_synced: true|false
  next_steps_suggested: true|false

3.4 Run Pipeline

From Actions menu, test each phase:

3.5 View Issues

Test "View Issues" screen:

issues_view:
  accessible: true|false
  issues_explained: true|false
  how_to_fix_documented: true|false
  links_to_files: true|false
  friction: "Do I understand what to fix?"

Phase 4: Errors

4.1 Non-TTY Environment

echo "test" | npm run ucv-cli

Record:

non_tty:
  error_message_helpful: true|false
  suggests_alternative: true|false
  documented_limitation: true|false

4.2 No Variants

What happens with empty variants directory?

empty_variants:
  handled_gracefully: true|false
  prompts_to_create: true|false
  documented: true|false

4.3 Pipeline Failures

What happens when eval/redteam fails?

pipeline_failures:
  errors_visible: true|false
  actionable_guidance: true|false
  friction: "Do I know how to fix this?"

Phase 5: Report

5.1 Compile Audit Report

Use template from

_shared/first-time-user-base.md

Happy Path Steps for UCV-CLI:

1. Find CLI documentation
2. Understand what CLI does vs other methods
3. Launch CLI in terminal
4. Navigate dashboard UI
5. Create new variant via guided flow
6. Run sync phase
7. Run evaluate phase
8. Run red team phase
9. View issues and understand fixes
10. Understand next steps

UI/UX Assessment (CLI-specific):

5.2 Save Report

docs/audits/YYYY-MM-DD-first-time-user-ucv-cli.md

Example Output

<example_output>

Executive Summary

CLI launched successfully and guided flow was intuitive. Documentation in universal-cv-cli.md is comprehensive. Minor friction around status icon meanings.

Happy Path Journey

UI/UX Assessment

Recommendations

Priority 1 (Blocking)

• None

Priority 2 (Friction)

• Add status icon legend to dashboard or docs
• Document TTY requirement more prominently

Priority 3 (Polish)

• Add "what to do next" after variant creation </example_output>

Quality Checklist

Before completing:

• Followed ONLY documentation (no source code diving)
• Tested CLI launch in real terminal
• Tested full creation flow
• Tested all pipeline phases
• Tested error scenarios (non-TTY, empty, failures)
• Documented all friction points
• Generated prioritized recommendations
• Saved report to docs/audits/

Notes

• CLI is interactive and requires TTY — this is a common blocker
• Progress bars and spinners are part of the UX
• Keyboard shortcuts must be discoverable without reading docs
• Status meanings should be clear from context
• CLI should guide users to next actions

<skill_compositions>

Works Well With

• first-time-user — General documentation audit
• first-time-user-dashboard — Dashboard-specific audit
• technical-writer — Fix documentation issues found
• sprint-sync — Report findings in status update </skill_compositions>