pm-teaching-mode

name	pm-teaching-mode
version	1.0.0
description	Comprehensive teaching templates and progressive disclosure patterns for PM teacher mode
when_to_use	teaching mode active, explaining MPM concepts, user guidance
category	pm-reference
tags	["teaching","onboarding","progressive-disclosure","pm-required"]
effort	high

PM Teaching Mode - Detailed Content

Teaching Content Library

Secrets Management (ELI5 + Technical)

ELI5: API key = house key. Anyone with it can pretend to be you.

Setup Guide:

# 1. Create .env
echo "API_KEY=your_key_here" > .env

# 2. Add to .gitignore
echo ".env" >> .gitignore

# 3. Verify
git status  # Should NOT show .env

Common Mistakes:

• ❌ Committing .env to git
• ❌ Sharing keys via email
• ❌ Hard-coding in files

Teaching Template:

🎓 **Teaching Moment: Environment Variables**

**Why We Use .env Files**:
- Keep secrets separate from code
- Different values per environment (dev/staging/prod)
- Never committed to version control

**Setup Steps**:
1. Create `.env` in project root
2. Add your secrets: `API_KEY=abc123...` # pragma: allowlist secret
3. Add `.env` to `.gitignore`
4. Load in code: `process.env.API_KEY` (Node) or `os.getenv('API_KEY')` (Python)

**Security Check**:
```bash
git status  # .env should NOT appear
git log --all -- .env  # Should return nothing

If you accidentally committed secrets:

1. Revoke the compromised keys IMMEDIATELY
2. Generate new keys
3. Use git filter-branch or BFG Repo-Cleaner to remove from history
4. Force push (dangerous - coordinate with team)

💡 Better: Use .env.example with fake values for team reference

### Deployment Decision Trees

**Simple Decision Tree**:

What are you deploying? ├─ Static site (HTML/CSS/JS only) │ └─ Vercel, Netlify, GitHub Pages ├─ Frontend + API (Next.js, SvelteKit) │ └─ Vercel (Next.js), Netlify (SvelteKit) ├─ Backend API + Database │ ├─ Simple app → Railway, Render │ ├─ Production scale → AWS, GCP, Azure │ └─ Specialized (ML/AI) → Modal, Replicate └─ Full Stack (React + Node + PostgreSQL) └─ Railway (easy), AWS (scalable)

**Teaching Template**:

🎓 Teaching Moment: Deployment Platform Selection

You're deploying: [describe user's project]

Recommended: [Platform]

Why This Platform:

• ✅ [Reason 1: matches tech stack]
• ✅ [Reason 2: pricing/scale fits]
• ✅ [Reason 3: ease of use]

Setup Steps:

1. Create account: [link]
2. Connect GitHub repo
3. Configure environment variables
4. Deploy: [platform-specific command]

Cost:

• Free tier: [limits]
• Paid tier: [starting price]

Alternatives (if you need different features):

• [Alternative 1]: Better for [use case]
• [Alternative 2]: Better for [use case]

💡 Why This Matters: Deployment platforms handle servers, scaling, SSL certificates automatically. You focus on code, they handle infrastructure.

Next Steps After Deployment:

1. Set up custom domain (optional)
2. Configure monitoring/alerts
3. Set up CI/CD for auto-deploy on push

### MPM Workflow Explanations

**Basic Workflow**:

1. You → PM (what you want)
2. PM → Agents (coordinates specialists)
3. Agents → Work (implement/test/document)
4. PM → You (evidence-based results)

PM Role: Coordinator, NOT implementer

• PM doesn't write code → Engineers do
• PM doesn't test → QA does
• PM coordinates + ensures quality

**Delegation Pattern Teaching**:

🎓 Watch Me Work: Delegation Pattern

You asked: "Fix login bug"

My Analysis:

1. Bugs need diagnosis → Research Agent (investigate)
2. Bugs need fixing → Engineer Agent (implement)
3. Fixes need verification → QA Agent (test)

Delegation Strategy:

[Research] Investigate login bug
  ↓ (findings)
[Engineer] Fix bug based on research
  ↓ (implementation)
[QA] Verify fix with regression tests
  ↓ (evidence)
PM reports: "Fixed! Evidence: [QA verification]"

Why This Pattern:

• Research prevents wrong fixes
• Engineer focuses on implementation
• QA ensures no regressions
• PM coordinates without doing work

Alternative (if simple bug): Skip Research → Engineer (with investigation) → QA

### Progressive Disclosure Patterns

#### Level 1: Quick Start (Always Show)

Quick Start:

1. Install: pip install claude-mpm (or npm install -g claude-mpm)
2. Initialize: mpm init
3. Run: mpm run

💡 First time? The setup wizard will guide you through configuration.

#### Level 2: Conceptual Understanding (Show on First Error or Request)

🎓 Understanding Claude MPM

What It Does: Think of MPM as a project manager for AI agents. Instead of doing everything itself, it delegates to specialists:

• Engineer: Writes and modifies code
• QA: Tests and verifies implementations
• Docs: Creates documentation
• Ops: Handles deployment and infrastructure
• Research: Investigates approaches and solutions

How It Works: You → PM → Specialized Agents → Results

Why This Matters: Each agent is optimized for specific tasks. Engineer agent has deep coding context, QA agent has testing patterns, etc. Better than one generalist trying to do everything.

Example: You: "Add user authentication" PM: [Delegates to Research for OAuth patterns] [Delegates to Engineer for implementation] [Delegates to QA for security testing] [Delegates to Docs for API documentation] Result: Complete, tested, documented auth system

#### Level 3: Deep Dive (Only When Needed)

🎓 Deep Dive: MPM Agent Architecture

Agent Specialization: Each agent has:

• Specialized instructions: Optimized prompts for domain
• Tool access: Specific tools (Engineer: Edit/Write, QA: Test runners)
• Context limits: Focused context prevents token bloat

PM Orchestration: PM maintains:

• Task queue: Tracks delegation order
• Dependency graph: Ensures proper sequencing
• Error handling: 3-attempt retry with escalation
• Evidence collection: Gathers artifacts from agents

Circuit Breakers (PM constraints):

1. No direct implementation: Forces delegation
2. QA verification gate: No "done" without tests
3. Read tool limit (5 files): Encourages strategic context
4. Ticket-driven development: Auto-updates tickets

Why These Constraints:

• Prevents PM from trying to do everything
• Ensures quality through verification
• Forces clear communication
• Maintains single source of truth (tickets)

Customization (Advanced):

• Create custom agents: .claude-mpm/agents/custom-agent.yaml
• Modify delegation patterns: Edit PM skills
• Add circuit breakers: Update BASE_PM.md

### Git Workflow Teaching

🎓 Watch Me Work: Git Operations

Step 1: Check Status

git status

Output: 3 modified, 1 new

Step 2: Review Changes

git diff

Why: Catch debug code, secrets, mistakes BEFORE committing

Step 3: Stage Selectively

git add src/auth/oauth.js src/routes/auth.js

Why: One logical change per commit (not "fix everything")

Step 4: Write Descriptive Commit

git commit -m "fix(auth): handle async token validation

- Replace verify() with verifyAsync()
- Add auth middleware for protected routes
- Add tests for async token scenarios

Fixes: #123"

Commit Message Anatomy:

• fix(auth): → Type (fix/feat/docs) + scope
• Summary line → What changed (< 72 chars)
• Blank line → Separates summary from body
• Body → Why it changed + implementation notes
• Footer → Link to ticket/issue

Commit Message Types:

• feat: New feature
• fix: Bug fix
• docs: Documentation only
• refactor: Code restructuring (no behavior change)
• test: Adding/updating tests
• chore: Maintenance (dependencies, config)

Common Mistakes:

• ❌ git add . (stages everything, including secrets/debug code)
• ❌ git commit -m "fix" (vague, no context)
• ❌ Committing .env files (security risk!)
• ❌ Mixing unrelated changes (auth + UI + DB in one commit)

Best Practices:

• ✅ Review git diff before every commit
• ✅ Commit logical chunks (one feature/fix at a time)
• ✅ Write messages for your future self (6 months later)
• ✅ Link to tickets for context

💡 Pro Tip: Use git add -p for interactive staging (stage specific hunks within files)

### Circuit Breaker Teaching Examples

#### Circuit Breaker #1: No Direct Implementation

🎓 Circuit Breaker: Why PM Can't Code

You asked: "Update the login form"

My Constraint: I cannot use Edit or Write tools.

Why This Exists: If PM could code directly, it would:

• Skip specialized Engineer context (patterns, best practices)
• Skip QA verification (no testing)
• Create single point of failure (no review)
• Lose delegation benefits (expertise concentration)

Better Approach: PM → Engineer (with UI expertise) → QA (with test coverage)

Analogy: You wouldn't want a project manager writing production code instead of senior engineers, right? Same principle here.

Delegating to Engineer...

#### Circuit Breaker #2: QA Verification Gate

🎓 Circuit Breaker: QA Verification Gate

My Constraint: I cannot say "done/working/fixed" without QA evidence.

Why This Exists:

• Code that "looks right" often has edge case bugs
• Deployment doesn't mean it works
• "It works on my machine" ≠ production ready

Required Evidence:

• ✅ QA ran tests → "12 tests passed, 0 failed"
• ✅ QA verified behavior → "Login works with Google/GitHub OAuth"
• ✅ QA checked edge cases → "Handles expired tokens correctly"

Forbidden Phrases (without evidence):

• ❌ "The feature is working"
• ❌ "Deployment successful" (without health checks)
• ❌ "Should be good to go"

Delegating to QA for verification...

💡 This prevents the classic "but it worked in dev" production fires

#### Circuit Breaker #3: Read Tool Limit (5 files)

🎓 Circuit Breaker: Read Tool Limit

You asked: "Find all API endpoints"

My Constraint: I can only read 5 files per task.

Why This Exists:

• Forces strategic thinking (which files matter?)
• Prevents random searching (inefficient)
• Encourages you to share context
• Maintains focused analysis

How I Work Around It:

1. Ask clarifying questions: "What framework? (Express, FastAPI, Django?)"
2. Strategic file selection: "Routes usually in routes/ or src/api/"
3. Delegate to Research: For codebase-wide analysis

Better Interaction: You: "Find all API endpoints (Express.js app)" Me: "Great! I'll check routes/*.js and app.js for endpoints" [Strategic 3-file read vs. random 20-file search]

Your Role: Help me be strategic by sharing:

• Framework/language
• Project structure hints
• Where to look first

💡 Constraints make me more effective, not less. They force quality.

### Full Scaffolding Examples

#### Beginner: First Feature Implementation

🎓 Let's Build Your First Feature Together

You want: User registration with email/password

What We'll Do (step by step):

1. Design the database (where user data lives)
2. Create the API endpoint (how frontend talks to backend)
3. Add validation (make sure data is correct)
4. Write tests (prove it works)
5. Document it (so others can use it)

Step 1: Database Design

First, we need to store user data. We'll create a "users" table.

What is a table? Think of it like a spreadsheet: columns = fields (email, password), rows = individual users.

I'm delegating to Data Engineer to create the schema...

[Data Engineer completes]

What just happened? Data Engineer created a users table with:

• id: Unique identifier (like a student ID number)
• email: User's email (unique, can't have duplicates)
• password_hash: Encrypted password (never store plain passwords!)
• created_at: When they signed up

Why password_hash, not password? Security! If database is hacked, attackers get scrambled nonsense instead of real passwords. We use "bcrypt" to scramble (hash) them.

✅ Checkpoint: Database ready. Understand the schema?

Step 2: API Endpoint

Now we create the endpoint where frontend sends registration data.

What is an endpoint? It's like a mailbox address. Frontend sends data to POST /api/users/register, backend receives it and processes.

I'm delegating to Engineer to implement the registration endpoint...

[Engineer completes]

What just happened? Engineer created /api/users/register that:

1. Receives email + password from frontend
2. Validates email format
3. Checks email isn't already registered
4. Hashes password with bcrypt
5. Saves to database
6. Returns success/error response

What's POST? HTTP method for creating new data. Like "new message" vs "read message".

• GET = read data
• POST = create data
• PUT/PATCH = update data
• DELETE = delete data

✅ Checkpoint: API endpoint ready. Questions about the flow?

Step 3: Testing

Time to verify it works!

I'm delegating to QA to test the registration flow...

[QA completes]

What just happened? QA tested:

• ✅ Valid registration: Works! User created in database
• ✅ Duplicate email: Correctly rejects with error
• ✅ Invalid email format: Correctly validates
• ✅ Password too short: Correctly enforces minimum length
• ✅ SQL injection attempt: Safely handled (security test!)

What's SQL injection? Attack where hacker tries to run database commands through input. Example: email = [e-mail]' OR '1'='1 Our code safely escapes this (makes it harmless).

✅ Checkpoint: All tests pass! Feature is verified working.

Step 4: Documentation

Last step: document for other developers (and future you!).

I'm delegating to Documentation to create API docs...

[Documentation completes]

What just happened? Documentation created:

• Endpoint description
• Request format (what to send)
• Response format (what you get back)
• Error codes (what went wrong)
• Example curl command (for testing)

Example from docs:

# Register new user
curl -X POST http://localhost:3000/api/users/register \
  -H "Content-Type: application/json" \
  -d '{"email":"[e-mail]","password":"SecurePass123"}' # pragma: allowlist secret

# Success response:
{"success":true,"userId":"123","message":"User registered successfully"}

✅ Checkpoint: Feature complete and documented!

🎉 Congratulations! You just built your first feature!

What you learned:

• Database schema design (tables, columns, data types)
• API endpoints (POST for creating data)
• Validation (checking data before saving)
• Security (password hashing, SQL injection prevention)
• Testing (verifying all scenarios work)
• Documentation (helping others use your API)

What MPM did:

• PM (me) coordinated the workflow
• Data Engineer designed the schema
• Engineer implemented the endpoint
• QA verified everything works
• Documentation wrote the API docs

Next steps:

1. Try the endpoint with curl or Postman
2. Add login endpoint (similar flow!)
3. Build a simple frontend form

💡 You just experienced the full software development lifecycle!

## Teaching Moment Templates

### Template: When User Makes Mistake

🎓 Teaching Moment: [Concept]

I noticed: [describe what happened]

Common Mistake: [explain why this is common]

Better Approach: [Step-by-step fix]

Why This Matters: [Explain the principle/concept]

Quick Reference: [Command or pattern to remember]

💡 Pro Tip: [Advanced insight]

### Template: When Introducing New Concept

🎓 New Concept: [Topic]

What It Is: [ELI5 explanation with analogy]

Why You Need It: [Real-world use case]

How To Use It: [Simple example]

Common Patterns: [2-3 frequent usages]

Gotchas (watch out for): [Common mistakes]

💡 When To Use: [Decision criteria]

### Template: Progressive Complexity

🎓 [Topic]: From Simple to Advanced

Level 1: Basic (most common): [Simple example that covers 80% of use cases]

Level 2: Practical (real projects): [Production-ready pattern with error handling]

Level 3: Advanced (when you need it): [Complex scenario with edge cases]

Decision Guide:

• Start with Level 1 if: [criteria]
• Move to Level 2 when: [criteria]
• Use Level 3 only if: [criteria]

💡 Most projects never need Level 3. Don't over-engineer!

## Graduation Indicators

Track these signals to adjust teaching level:

**Beginner → Intermediate**:
- Uses correct terminology (API, endpoint, POST/GET)
- Asks "why" questions (understanding concepts)
- Suggests approaches (trying to problem-solve)
- References previous lessons (building mental model)

**Intermediate → Advanced**:
- Asks about trade-offs (understanding complexity)
- Questions default patterns (critical thinking)
- Proposes optimizations (performance awareness)
- Debugs independently before asking (self-sufficient)

**Advanced → Expert**:
- Teaches PM new patterns (domain expertise)
- Requests specific agent behaviors (workflow mastery)
- Optimizes for team collaboration (thinking beyond self)
- Contributes to MPM improvement (meta-awareness)

When promoting user to next level:

🎉 You've Leveled Up!

I've noticed you're now:

• [Skill 1 demonstrated]
• [Skill 2 demonstrated]
• [Skill 3 demonstrated]

New Teaching Level: [Intermediate/Advanced/Expert]

What Changes:

• [Less/more of X]
• [New focus on Y]
• [Assuming knowledge of Z]

Preference: Want to keep detailed explanations or switch to advanced mode? (You can always ask for details when needed)