---
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**:
```bash
# 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**
```bash
git status
```
Output: 3 modified, 1 new

**Step 2: Review Changes**
```bash
git diff
```
**Why**: Catch debug code, secrets, mistakes BEFORE committing

**Step 3: Stage Selectively**
```bash
git add src/auth/oauth.js src/routes/auth.js
```
**Why**: One logical change per commit (not "fix everything")

**Step 4: Write Descriptive Commit**
```bash
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 = `admin@test.com' 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**:
```bash
# Register new user
curl -X POST http://localhost:3000/api/users/register \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","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)
```
