Babysitter User Documentation - Audience Personas

**Version:** 1.0 **Date:** 2026-01-25 **Author:** UX Research and Documentation Strategy **Status:** Complete **Related Document:** 01-discovery-analysis.md

---

Table of Contents

1. Overview 2. Primary User Personas - Persona 1: Sarah Chen - The Productivity-Focused Developer - Persona 2: Marcus Thompson - The Technical Lead - Persona 3: Elena Rodriguez - The DevOps Engineer - Persona 4: James Park - The Curious Newcomer 3. User Journey Maps 4. Learning Paths 5. Progressive Disclosure Strategy 6. Content Recommendations by Persona 7. Documentation Accessibility Matrix

---

Overview

This document defines four primary user personas for the Babysitter documentation, each representing a distinct segment of our target audience. These personas guide content creation, ensuring documentation meets the varied needs of our users across different experience levels and use cases.

Persona Summary Table

---

Primary User Personas

---

Persona 1: Sarah Chen - The Productivity-Focused Developer

Profile Summary

Background

Sarah is a senior full-stack developer at a growing SaaS company. She's been using Claude Code for six months and loves how it accelerates her workflow, but she's frustrated by the lack of structure when working on complex features. She often loses context when sessions end, has to manually iterate until code quality is acceptable, and spends too much time re-explaining context after interruptions.

She discovered Babysitter through a tech blog and was immediately interested in its quality convergence and session persistence features. She's comfortable with command-line tools and JavaScript but isn't interested in deep customization - she just wants tools that work out of the box.

Goals and Motivations

**Primary Goals:**

• Deliver features faster without sacrificing code quality
• Reduce time spent on repetitive iteration and context re-establishment
• Maintain consistent coding standards across her work
• Have confidence that AI-generated code meets quality thresholds

**Secondary Goals:**

• Share efficient workflows with teammates
• Reduce cognitive load by offloading iteration management
• Build a personal library of effective prompts and processes

**Success Metrics:**

• Reduce feature development time by 30%
• Achieve consistent test coverage above 80%
• Eliminate lost work from session interruptions

Pain Points and Challenges

**Emotional Frustrations:**

• "I wish Claude would just keep iterating until it gets it right"
• "Why do I have to start over every time my laptop sleeps?"
• "I don't have time to learn another complex tool"

Preferred Learning Style

**Characteristics:**

• Skims documentation, looking for relevant sections
• Uses search heavily to find specific answers
• Appreciates clear "Before/After" comparisons
• Values time-saving tips and shortcuts

Documentation Needs

**Essential Content:** 1. Quick installation guide (< 5 minutes) 2. "First feature in 15 minutes" tutorial 3. Methodology comparison chart (TDD vs GSD vs Spec-Kit) 4. Command cheat sheet for daily use 5. Session resumption guide

**Content Format Preferences:**

• Step-by-step instructions with screenshots
• Copy-paste code blocks with explanations
• Quick reference cards for common tasks
• Troubleshooting sections for each major feature

**Ideal Documentation Experience:**

"I want to find the exact command I need in under 30 seconds, copy it, and get back to work."

---

Persona 2: Marcus Thompson - The Technical Lead

Profile Summary

Background

Marcus leads a team of 12 developers at a financial services company with strict compliance requirements. He's responsible for code quality, security, and audit readiness. He was initially skeptical of AI-assisted coding due to concerns about consistency, traceability, and control.

After hearing about Babysitter's breakpoint system and event-sourced journaling, he saw potential for responsible AI adoption with the governance controls his organization requires. He needs to understand not just how to use Babysitter, but how to implement it across his team with appropriate safeguards.

Goals and Motivations

**Primary Goals:**

• Implement AI-assisted development with appropriate governance
• Ensure all AI-generated code changes have human approval for critical paths
• Maintain complete audit trails for compliance requirements
• Standardize team workflows for consistency and quality

**Secondary Goals:**

• Gradually increase team productivity without compromising security
• Create team-specific processes that encode best practices
• Demonstrate ROI of AI tools to executive stakeholders
• Reduce onboarding time for new team members

**Success Metrics:**

• 100% audit trail coverage for production-impacting changes
• Zero compliance incidents related to AI-generated code
• 25% team productivity improvement within 6 months
• Successful security and compliance audits

Pain Points and Challenges

**Emotional Frustrations:**

• "I need to know exactly what the AI decided and why"
• "I can't let unreviewed code reach production"
• "My team wants to move fast but I'm responsible if something breaks"

Preferred Learning Style

**Characteristics:**

• Reads documentation thoroughly before recommending tools
• Looks for security implications and edge cases
• Values diagrams showing data flow and control points
• Needs content he can share with compliance teams

Documentation Needs

**Essential Content:** 1. Architecture overview with security boundaries 2. Breakpoint system deep dive (approval workflows) 3. Journal system for audit compliance 4. Team rollout and governance guide 5. Access control and permission patterns

**Content Format Preferences:**

• Architecture diagrams with security annotations
• Compliance checklist templates
• Team policy templates and examples
• Risk assessment frameworks

**Ideal Documentation Experience:**

"I need to explain to our security team exactly how Babysitter handles data, who approves what, and where the audit trail lives."

---

Persona 3: Elena Rodriguez - The DevOps Engineer

Profile Summary

Background

Elena manages the CI/CD infrastructure and developer platform at a fast-moving startup. She's responsible for making developers productive while maintaining system reliability. She sees AI-assisted coding as inevitable and wants to integrate it into existing workflows rather than fighting it.

She's drawn to Babysitter's CLI-first design, deterministic execution model, and potential for CI/CD integration. She's less interested in using Babysitter interactively and more interested in automating it as part of deployment pipelines and scheduled tasks.

Goals and Motivations

**Primary Goals:**

• Integrate Babysitter into CI/CD pipelines for automated code tasks
• Create deterministic, reproducible AI-assisted workflows
• Build self-service automation that developers can trigger
• Monitor and optimize Babysitter execution at scale

**Secondary Goals:**

• Reduce manual intervention in routine coding tasks
• Create reusable process templates for common scenarios
• Integrate with existing observability and alerting systems
• Document and standardize automation patterns

**Success Metrics:**

• Fully automated code review and quality checks
• Zero manual intervention for routine PR tasks
• Sub-minute feedback on quality convergence status
• 99.9% pipeline reliability with Babysitter integration

Pain Points and Challenges

**Emotional Frustrations:**

• "I need this to be scriptable and predictable"
• "Show me the exit codes and structured output"
• "I can't have flaky AI behavior in my pipelines"

Preferred Learning Style

**Characteristics:**

• Reads documentation like code - skims for patterns
• Tests everything in isolation before production
• Values configuration over code when possible
• Needs predictable behavior above all else

Documentation Needs

**Essential Content:** 1. Complete CLI reference with all flags and options 2. Exit codes and structured output documentation 3. CI/CD integration recipes (GitHub Actions, GitLab CI, Jenkins) 4. Environment variable and configuration reference 5. Scripting patterns and automation examples

**Content Format Preferences:**

• Complete CLI reference in searchable format
• Working pipeline configuration files
• Docker images and deployment manifests
• Structured output schemas (JSON)

**Ideal Documentation Experience:**

"Give me the complete CLI spec, example GitHub Actions workflow, and tell me what exit codes mean what. I'll figure out the rest."

---

Persona 4: James Park - The Curious Newcomer

Profile Summary

Background

James recently graduated with a CS degree and has been working as a junior developer for two years. He's heard a lot about AI-assisted coding but hasn't used it systematically. His manager mentioned Babysitter as something worth exploring, and James is excited but also overwhelmed by the terminology and concepts.

He's comfortable with basic command-line tools and JavaScript but has never used Claude Code or worked with event-sourced systems. He needs documentation that doesn't assume prior knowledge and builds understanding step by step.

Goals and Motivations

**Primary Goals:**

• Understand what Babysitter is and why he should use it
• Successfully complete his first AI-assisted feature
• Build confidence with AI tools before his peers
• Impress his manager with improved productivity

**Secondary Goals:**

• Learn best practices for AI-assisted development
• Understand underlying concepts (event sourcing, quality convergence)
• Contribute to team knowledge as he learns
• Build a foundation for more advanced usage later

**Success Metrics:**

• Complete first feature with Babysitter in under 2 hours
• Understand core concepts well enough to explain to others
• Feel confident enough to use Babysitter daily
• Avoid embarrassing errors or asking too many "basic" questions

Pain Points and Challenges

**Emotional Frustrations:**

• "I don't even know what questions to ask"
• "Everyone else seems to already understand this"
• "What if I mess something up and waste everyone's time?"

Preferred Learning Style

**Characteristics:**

• Reads documentation linearly, start to finish
• Gets discouraged by errors or unexpected results
• Appreciates encouragement and "it's normal to struggle" messaging
• Likes to understand WHY before HOW

Documentation Needs

**Essential Content:** 1. "What is Babysitter?" conceptual overview (no jargon) 2. Prerequisites checklist with links to learn missing skills 3. Beginner-friendly installation with verification steps 4. "Your First Run" tutorial with expected output 5. Glossary of all terms with simple definitions

**Content Format Preferences:**

• Heavy use of screenshots and visual aids
• "Expected output" sections after each step
• "Common mistakes" callouts with solutions
• Encouragement and "this is normal" reassurance

**Ideal Documentation Experience:**

"I want to follow along step-by-step, see exactly what I should see at each point, and understand why I'm doing each thing."

---

User Journey Maps

Journey Map: Sarah Chen (Productivity-Focused Developer)

Phase 1: Discovery (Day 0)
    |
    +---> Hears about Babysitter from colleague
    |     [Emotion: Curious but skeptical]
    |
    +---> Scans README for value proposition
    |     [Need: Clear "before/after" comparison]
    |
    +---> Decides to try for next feature
          [Trigger: "Quality convergence" feature]

Phase 2: Onboarding (Day 1)
    |
    +---> Finds quick installation guide
    |     [Need: < 5 minute install, no roadblocks]
    |
    +---> Runs verification commands
    |     [Need: Clear success/failure indicators]
    |
    +---> Completes first quick win tutorial
          [Emotion: Excited by automatic iteration]

Phase 3: Adoption (Week 1-2)
    |
    +---> Uses Babysitter for real feature work
    |     [Need: Methodology selection guidance]
    |
    +---> Experiences session interruption + resume
    |     [Emotion: Relief that work wasn't lost]
    |
    +---> Configures breakpoints for code review
    |     [Need: Simple breakpoint setup guide]
    |
    +---> Adjusts quality targets based on results
          [Need: Quality tuning recommendations]

Phase 4: Proficiency (Month 1-2)
    |
    +---> Develops personal workflow preferences
    |     [Need: Tips for optimization]
    |
    +---> Shares experience with teammates
    |     [Need: Shareable "how I use it" summary]
    |
    +---> Explores advanced features (parallel exec)
          [Need: Advanced features documentation]

Phase 5: Advocacy (Month 3+)
    |
    +---> Recommends Babysitter to other teams
    |     [Need: Case study / success story template]
    |
    +---> Provides feedback for product improvement
          [Channel: GitHub issues, community forum]

Journey Map: Marcus Thompson (Technical Lead)

Phase 1: Evaluation (Week 1-2)
    |
    +---> Researches AI governance requirements
    |     [Need: Security and compliance overview]
    |
    +---> Reviews Babysitter architecture documentation
    |     [Need: Data flow diagrams, security boundaries]
    |
    +---> Evaluates breakpoint system for approval gates
    |     [Need: Detailed breakpoint workflow docs]
    |
    +---> Assesses journal system for audit compliance
          [Need: Audit trail documentation]

Phase 2: Pilot Planning (Week 3-4)
    |
    +---> Creates pilot proposal for leadership
    |     [Need: ROI calculator, risk assessment]
    |
    +---> Defines governance policies for AI usage
    |     [Need: Policy template examples]
    |
    +---> Selects pilot team members
    |     [Need: Team onboarding guide]
    |
    +---> Sets success metrics for pilot
          [Need: Metrics and measurement guidance]

Phase 3: Pilot Execution (Month 2-3)
    |
    +---> Onboards pilot team to Babysitter
    |     [Need: Team training materials]
    |
    +---> Monitors breakpoint approval compliance
    |     [Need: Dashboard / monitoring guidance]
    |
    +---> Reviews journal logs for audit readiness
    |     [Need: Journal analysis guide]
    |
    +---> Adjusts policies based on pilot learnings
          [Need: Common policy adjustments]

Phase 4: Rollout (Month 4-6)
    |
    +---> Expands to full team
    |     [Need: Scaling guidance]
    |
    +---> Creates team-specific custom processes
    |     [Need: Process development guide]
    |
    +---> Integrates with existing compliance tools
    |     [Need: Integration documentation]
    |
    +---> Reports success metrics to stakeholders
          [Need: Executive reporting template]

Journey Map: Elena Rodriguez (DevOps Engineer)

Phase 1: Technical Evaluation (Days 1-3)
    |
    +---> Reviews CLI documentation for automation potential
    |     [Need: Complete CLI reference]
    |
    +---> Examines exit codes and structured output
    |     [Need: Machine-readable output specs]
    |
    +---> Tests deterministic behavior locally
    |     [Need: Determinism verification guide]
    |
    +---> Evaluates state management approach
          [Need: State and journal architecture]

Phase 2: Proof of Concept (Week 1-2)
    |
    +---> Creates local pipeline prototype
    |     [Need: CI/CD integration examples]
    |
    +---> Tests run creation and orchestration in CI
    |     [Need: CI environment setup guide]
    |
    +---> Validates breakpoint handling in automation
    |     [Need: Automated breakpoint resolution docs]
    |
    +---> Documents learnings and constraints
          [Emotion: Satisfaction with predictability]

Phase 3: Production Integration (Week 3-4)
    |
    +---> Implements in staging CI/CD pipeline
    |     [Need: Production-ready configuration]
    |
    +---> Sets up monitoring and alerting
    |     [Need: Observability integration guide]
    |
    +---> Creates developer self-service interface
    |     [Need: API documentation]
    |
    +---> Documents operational runbooks
          [Need: Operations playbook template]

Phase 4: Optimization (Month 2+)
    |
    +---> Optimizes pipeline performance
    |     [Need: Performance tuning guide]
    |
    +---> Creates reusable process templates
    |     [Need: Process template development]
    |
    +---> Contributes to internal automation library
          [Need: Contribution guidelines]

Journey Map: James Park (Curious Newcomer)

Phase 1: Exploration (Day 1)
    |
    +---> Manager suggests exploring Babysitter
    |     [Emotion: Nervous but excited]
    |
    +---> Reads "What is Babysitter?" overview
    |     [Need: Jargon-free introduction]
    |
    +---> Reviews prerequisites checklist
    |     [Need: Clear skill requirements with learning links]
    |
    +---> Installs Claude Code (if not already)
          [Need: Claude Code setup guide link]

Phase 2: First Steps (Day 2-3)
    |
    +---> Follows installation guide carefully
    |     [Need: Step-by-step with screenshots]
    |
    +---> Verifies installation with checklist
    |     [Need: Verification commands with expected output]
    |
    +---> Completes "Hello World" equivalent tutorial
    |     [Need: Simplest possible first success]
    |
    +---> Celebrates first working run
          [Emotion: Confidence boost]

Phase 3: Building Confidence (Week 1-2)
    |
    +---> Works through beginner tutorials
    |     [Need: Progressive difficulty tutorials]
    |
    +---> Encounters first error, consults troubleshooting
    |     [Need: Beginner-friendly error guide]
    |
    +---> Asks questions in community (Slack/Discord)
    |     [Need: Community links and norms]
    |
    +---> Completes first real work task with Babysitter
          [Emotion: "I can do this!"]

Phase 4: Growing Independence (Month 1-2)
    |
    +---> Experiments with different methodologies
    |     [Need: Methodology comparison for beginners]
    |
    +---> Learns breakpoint system
    |     [Need: Beginner breakpoint guide]
    |
    +---> Starts helping other newcomers
    |     [Emotion: Pride in knowledge]
    |
    +---> Transitions to intermediate documentation
          [Need: Clear "next steps" guidance]

---

Learning Paths

Beginner Path: "Zero to First Feature"

**Target Persona:** James Park (Curious Newcomer) **Duration:** 1-2 weeks **Goal:** Complete first AI-assisted feature with confidence

Week 1: Foundations
|
+-- Day 1-2: Understanding
|   |
|   +-- What is Babysitter? (conceptual overview)
|   +-- Why use Babysitter? (value proposition)
|   +-- Key concepts glossary (terminology foundation)
|   +-- Prerequisites check (skills assessment)
|
+-- Day 3-4: Installation
|   |
|   +-- Environment setup (Node.js, Claude Code)
|   +-- Babysitter installation (step-by-step)
|   +-- Verification checklist (confirm success)
|   +-- Troubleshooting basics (common issues)
|
+-- Day 5-7: First Success
    |
    +-- Quick Win Tutorial #1: Simple TDD feature
    +-- Understanding what happened (journal review)
    +-- Quick Win Tutorial #2: Session resumption
    +-- Celebrate and reflect

Week 2: Building Skills
|
+-- Day 8-10: Core Workflows
|   |
|   +-- TDD methodology walkthrough
|   +-- Quality convergence explained
|   +-- Breakpoints introduction
|   +-- Practice: Build a small feature
|
+-- Day 11-14: Confidence Building
    |
    +-- Troubleshooting practice
    +-- Exploring methodologies (GSD, Spec-Kit overview)
    +-- First real project task
    +-- Knowledge check quiz

Milestone: Ready for Independent Use

Intermediate Path: "Daily Productivity"

**Target Persona:** Sarah Chen (Productivity-Focused Developer) **Duration:** 2-4 weeks **Goal:** Integrate Babysitter into daily workflow efficiently

Week 1-2: Workflow Mastery
|
+-- Methodology Deep Dives
|   |
|   +-- TDD Quality Convergence mastery
|   +-- GSD (Get Shit Done) for rapid prototyping
|   +-- Spec-Kit for specification-driven work
|   +-- Choosing the right methodology (decision guide)
|
|
+-- Session Management
    |
    +-- Resumption best practices
    +-- Managing multiple runs
    +-- Journal analysis for debugging

Week 3-4: Optimization
|
+-- Performance Tuning
|   |
|   +-- Quality target optimization
|   +-- Iteration limits and timing
|   +-- Parallel execution basics
|
+-- Workflow Customization
|   |
|   +-- Process parameter tuning
|   +-- Creating personal workflow templates
|   +-- Integration with existing tools
|
+-- Team Collaboration
    |
    +-- Sharing runs and artifacts
    +-- Team conventions and standards
    +-- Knowledge sharing practices

Milestone: 30%+ Productivity Improvement

Advanced Path: "Platform and Automation"

**Target Persona:** Elena Rodriguez (DevOps Engineer) **Duration:** 4-6 weeks **Goal:** Build production-ready automation and integrations

Week 1-2: CLI and Automation Mastery
|
+-- Complete CLI Reference
|   |
|   +-- All commands and subcommands
|   +-- Exit codes and error handling
|   +-- Structured output (JSON) parsing
|   +-- Environment variables and configuration
|
+-- Scripting Patterns
    |
    +-- Bash scripting with Babysitter
    +-- Node.js SDK for custom orchestration
    +-- State management across runs
    +-- Error recovery patterns

Week 3-4: CI/CD Integration
|
+-- Pipeline Integration
|   |
|   +-- GitHub Actions recipes
|   +-- GitLab CI integration
|   +-- Jenkins pipeline configuration
|   +-- Self-hosted runners and resources
|
+-- Automation Patterns
    |
    +-- Automated code review workflows
    +-- Scheduled quality checks
    +-- PR-triggered automation
    +-- Deployment gate patterns

Week 5-6: Production Operations
|
+-- Monitoring and Observability
|   |
|   +-- Metrics collection
|   +-- Alerting integration
|   +-- Dashboard creation
|   +-- Log aggregation
|
+-- Custom Process Development
    |
    +-- Process definition deep dive
    +-- Creating team-specific processes
    +-- Testing and validation
    +-- Distribution and versioning

Milestone: Production-Ready Pipeline Integration

Expert Path: "Governance and Scale"

**Target Persona:** Marcus Thompson (Technical Lead) **Duration:** 6-8 weeks **Goal:** Implement organization-wide AI governance and custom workflows

Week 1-2: Architecture Deep Dive
|
+-- System Architecture
|   |
|   +-- Event sourcing model
|   +-- Journal system internals
|   +-- State management
|   +-- Security boundaries
|
+-- Compliance Framework
    |
    +-- Audit trail requirements
    +-- Data handling and privacy
    +-- Access control patterns
    +-- Retention policies

Week 3-4: Governance Implementation
|
+-- Approval Workflows
|   |
|   +-- Breakpoint policy design
|   +-- Multi-level approval patterns
|   +-- Emergency override procedures
|   +-- Audit logging configuration
|
+-- Team Policies
    |
    +-- Usage guidelines creation
    +-- Quality standards enforcement
    +-- Process standardization
    +-- Training program development

Week 5-6: Custom Process Development
|
+-- Process Definition Mastery
|   |
|   +-- JavaScript process API
|   +-- Task type deep dives
|   +-- Quality scoring customization
|   +-- Hook development
|
+-- Enterprise Patterns
    |
    +-- Multi-team coordination
    +-- Shared process libraries
    +-- Version management
    +-- Governance reporting

Week 7-8: Organizational Rollout
|
+-- Scaling Strategies
|   |
|   +-- Phased rollout planning
|   +-- Change management
|   +-- Success metrics tracking
|   +-- Stakeholder communication
|
+-- Continuous Improvement
    |
    +-- Feedback collection
    +-- Process refinement
    +-- Community contribution
    +-- Future roadmap input

Milestone: Organization-Wide Adoption

---

Progressive Disclosure Strategy

Principle: Right Information at the Right Time

Progressive disclosure ensures users see only the complexity they need at their current skill level, reducing cognitive overload while maintaining access to advanced features.

Level 1: Essential (Beginner)

**Shown immediately to all users:**

**Hidden initially:**

• Advanced configuration
• Custom process development
• CI/CD integration
• Architecture details
• API reference

Level 2: Standard (Intermediate)

**Revealed after first success:**

**Still hidden:**

• Custom process development
• Low-level API details
• CI/CD automation
• Enterprise governance

Level 3: Advanced (Power User)

**Revealed based on usage patterns:**

**Still hidden:**

• Process definition internals
• Enterprise compliance features
• Custom methodology development

Level 4: Expert (Platform/Enterprise)

**Revealed on explicit request:**

Implementation Recommendations

Documentation Site Features:

1. **Experience Level Selector** - Prominent toggle: Beginner | Intermediate | Advanced - Persists across sessions - Filters visible content appropriately

2. **"Learn More" Expansions** - Collapsed advanced sections within pages - Click to expand for deeper detail - Clearly labeled complexity level

3. **Prerequisites Badges** - Visual indicators of required knowledge - Links to prerequisite content - "You should know X before reading this"

4. **Contextual Suggestions** - "Ready to learn more? Try: Advanced Breakpoints" - Based on current page and reading history - Never pushy, always optional

5. **Search Result Filtering** - Results tagged by complexity level - Beginner results prioritized for new users - Option to "show all levels"

Content Tagging System

Every documentation page should be tagged:

---
title: Breakpoint Configuration
level: intermediate  # beginner | intermediate | advanced | expert
prerequisites:
  - first-run-tutorial
  - basic-breakpoints
personas:
  - sarah-chen
  - marcus-thompson
estimated_time: 15 minutes
---

---

Content Recommendations by Persona

Sarah Chen (Productivity-Focused Developer)

Priority Content

Content Style Guidelines

• **Tone:** Practical, efficient, respectful of time
• **Length:** Concise; expand details in collapsed sections
• **Examples:** Real-world feature development scenarios
• **Visuals:** Before/after comparisons, timelines
• **Calls to Action:** "Try this now" practical exercises

Sample Content Structure

## Quick Win: Add Authentication with TDD

**Time:** 20 minutes | **Level:** Intermediate

### What You'll Build
A JWT authentication module with 85% quality target.

### Command

claude "/babysit:call add JWT authentication module with TDD, 85% quality target"

### What to Expect
1. Research phase (~2 min): Analyzes existing auth patterns
2. Test creation (~3 min): Writes test cases first
3. Implementation (~5 min): Builds module to pass tests
4. Quality iteration (~10 min): Refines until 85% reached

### Pro Tips
- Use `--max-iterations 5` to limit if quality seems unreachable
- Check `.a5c/runs/*/artifacts/` for generated specs

---

Marcus Thompson (Technical Lead)

Priority Content

Content Style Guidelines

• **Tone:** Authoritative, thorough, risk-aware
• **Length:** Comprehensive; detail is valued
• **Examples:** Enterprise scenarios, compliance cases
• **Visuals:** Architecture diagrams, approval flowcharts
• **Calls to Action:** Assessment checklists, policy templates

Sample Content Structure

## Implementing Approval Gates for Production Changes

**Audience:** Technical Leads | **Time:** 45 minutes

### Overview

This guide establishes breakpoint policies that ensure all production-impacting
code changes receive appropriate human review before execution.

### Compliance Considerations

| Requirement | Babysitter Feature | Implementation |
|-------------|-------------------|----------------|
| Audit trail | Journal system | All decisions logged with timestamp |
| Approval record | Breakpoint resolution | Who approved, when, context |
| Traceability | Effect IDs | Link code changes to approval |

### Architecture

[Diagram: Data flow from code change to production]

### Policy Template

production-approval-policy.yaml

breakpoint_rules: - trigger: file_pattern patterns: ["**/production/**", "**/deploy/**"] approval_required: true approvers: ["tech-lead", "security"]

### Audit Checklist

- [ ] All production changes trigger breakpoints
- [ ] Approvals logged with approver identity
- [ ] Journal retention meets compliance requirements
- [ ] Access to approval interface is controlled

---

Elena Rodriguez (DevOps Engineer)

Priority Content

Content Style Guidelines

• **Tone:** Technical, precise, no fluff
• **Length:** As long as needed for completeness
• **Examples:** Working code, copy-paste ready
• **Visuals:** Pipeline diagrams, state machines
• **Calls to Action:** "Test this locally first"

Sample Content Structure

## CLI Reference: `babysitter run:create`

### Synopsis

babysitter run:create [options]

### Options

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--process` | string | required | Process name or path |
| `--input` | string | - | JSON input or @file path |
| `--run-id` | string | auto | Custom run identifier |
| `--cwd` | string | current | Working directory |

### Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | General error |
| 2 | Invalid arguments |
| 10 | Process not found |
| 20 | Journal conflict |

### Structured Output (--json)

{ "runId": "run-20260125-143012", "status": "created", "process": "tdd-quality-convergence", "journalPath": ".a5c/runs/run-20260125-143012/journal" }

### GitHub Actions Example

run: | OUTPUT=$(babysitter run:create --process tdd --json) echo "RUN_ID=$(echo $OUTPUT | jq -r .runId)" >> $GITHUB_ENV

• name: Create Babysitter Run

---

James Park (Curious Newcomer)

Priority Content

Content Style Guidelines

• **Tone:** Encouraging, patient, never condescending
• **Length:** Thorough explanation; don't skip steps
• **Examples:** Simple, relatable scenarios
• **Visuals:** Screenshots for every step
• **Calls to Action:** Small wins, celebration points

Sample Content Structure

## Your First Babysitter Run

**Time:** 15 minutes | **Level:** Beginner | **Prerequisites:** Installation complete

### What We're Building

A simple calculator module. Don't worry - Babysitter will write the code for you!

### Step 1: Open Your Terminal

Open your terminal application. On Mac, you can find it in Applications > Utilities.

### Step 2: Navigate to Your Project

cd ~/my-project

**What you should see:** Your terminal prompt should now show your project folder name.

### Step 3: Start Babysitter

Type this command exactly as shown:

claude "/babysitter:call create a calculator module with add and subtract functions"

**What you should see:**

[babysitter] Creating run: run-20260125-143012 [babysitter] Process: tdd-quality-convergence [babysitter] Starting iteration 1...

### Congratulations!

You just ran your first Babysitter workflow! Here's what happened:

1. **Babysitter created a "run"** - think of this as a work session
2. **It analyzed your request** - understanding you want a calculator
3. **It started iterating** - writing and improving code automatically

### What's Next?

- Want to see what was created? Check the `.a5c/runs/` folder
- Ready for more? Try the [Session Resumption Tutorial](./tutorial-resume.md)
- Confused about something? Check our [Glossary](./glossary.md)

### Stuck? Common First-Run Issues

| What You See | What It Means | What To Do |
|--------------|---------------|------------|
| "command not found: claude" | Claude Code isn't installed | [Install Claude Code first](./prerequisites.md) |
| "Plugin not found" | Babysitter plugin missing | [Re-run plugin installation](./installation.md#plugin) |
| Nothing happens | Claude Code might be thinking | Wait 30 seconds, check if cursor is blinking |

---

Documentation Accessibility Matrix

Content Coverage by Persona

Reading Order Recommendations

Sarah Chen

1. Quick Start Guide 2. First Feature Tutorial 3. Methodology Comparison 4. Command Cheat Sheet 5. Quality Tuning Tips

Marcus Thompson

1. Architecture Overview 2. Security and Compliance Guide 3. Breakpoint Approval Workflows 4. Team Rollout Guide 5. Custom Process Development

Elena Rodriguez

1. CLI Reference 2. CI/CD Integration Recipes 3. Scripting Patterns 4. Monitoring Guide 5. Process Template Development

James Park

1. What is Babysitter? 2. Prerequisites and Setup 3. Detailed Installation 4. First Run Tutorial 5. Glossary and FAQ

---

Appendix: Persona Validation Checklist

Use this checklist when creating new documentation to ensure it meets persona needs:

Pre-Publication Review

• [ ] **Identified primary persona** for this content
• [ ] **Complexity level matches** persona expectations
• [ ] **Prerequisites are clear** and linked
• [ ] **Format matches** persona preferences (tutorial vs reference vs conceptual)
• [ ] **Examples are relevant** to persona's context
• [ ] **Length is appropriate** for persona's learning style
• [ ] **Next steps** guide persona to logical follow-up content

Persona-Specific Checks

For Sarah-focused content:

• [ ] Can be completed in stated time
• [ ] Copy-paste examples work as-is
• [ ] Productivity benefit is clear

For Marcus-focused content:

• [ ] Compliance implications addressed
• [ ] Security considerations documented
• [ ] Audit trail impact explained

For Elena-focused content:

• [ ] CLI commands are complete and accurate
• [ ] Exit codes and outputs documented
• [ ] Automation-friendly (scriptable)

For James-focused content:

• [ ] No assumed knowledge
• [ ] Every step has expected output
• [ ] Encouragement included at milestones

---

**Document Status:** Complete **Next Phase:** Create content following these persona guidelines **Review Date:** 2026-02-01