Troubleshooting

Quick fixes for the most common issues.

Setup Issues

"command not found: claude" (Terminal users)

Your terminal doesn't know where Claude Code is installed.

Fix:

1. Close and reopen your terminal
2. Or run: source ~/.zshrc (Mac) / source ~/.bashrc (Linux)
3. If still broken, reinstall: npm install -g @anthropic-ai/claude-code

Claude doesn't see my files

Make sure you opened the second-pm-os folder (not a file inside it).

• Claude Desktop: Click the folder icon, select the whole folder
• Claude Code Desktop: File → Open Folder → select second-pm-os
• Terminal: Navigate to the folder with cd, then run claude

Skills aren't working / Claude doesn't know commands

Skills live in .claude/skills/. If Claude can't find them:

1. Make sure you unzipped the Product Management OS (don't work from inside the ZIP)
2. Check that .claude/skills/ folder exists and has files
3. Start a new Claude session (skills are loaded at session start)

Context Issues

Claude doesn't know my company name

Your context files might be empty or still have placeholders.

Fix:

1. Open context/company.md
2. Replace [Your company name] with your actual company name
3. Save the file

Claude reads context files fresh each time, so changes take effect immediately.

Outputs are generic and don't sound like my product

Your context needs more detail. The more specific your context, the more tailored the outputs.

Fix:

1. Run /welcome to see what Claude currently knows
2. Open your context files and add specific details
3. Or drop internal docs in context/inputs/ and run /enhance-context

See How It All Works for tips on writing good context.

Claude used old/wrong information

Context files might be out of date.

Fix:

1. Open the relevant context file (company.md, product.md, etc.)
2. Update the outdated information
3. Save — changes take effect immediately

Output Issues

I can't find the file Claude created

Outputs are saved to the relevant outputs/ folder:

The output is too long / too short / wrong format

Tell Claude what to change. You can say:

• "Make it shorter — just the highlights"
• "Add more detail to the risks section"
• "Format this as bullet points instead of paragraphs"
• "Make the tone more urgent"

Claude will revise. Keep iterating until it's right.

Claude asked me a question I don't understand

Just answer in plain English. If you're genuinely not sure:

• Say "I'm not sure — use your best judgment"
• Or ask Claude to clarify: "What do you mean by that?"

Claude will proceed with reasonable defaults or explain what it needs.

Workflow Issues

Workflow says "no files found"

Make sure your input files are in the right folder:

• Batch Interview Analysis: workflows/batch-interview-analysis/inputs/
• Problem to PRD: workflows/problem-to-prd/inputs/

Supported formats: .txt, .md, plain text files

Workflow is taking a long time

Large files or many files = longer processing. This is normal.

For batch interview analysis with 10 interviews, expect 10-15 minutes.

Advanced Troubleshooting

Agent Team Failures

Problem: Agent team starts but produces poor quality

Symptoms:

• Generic outputs with no context references
• Missing sections or incomplete analysis
• Superficial insights

Causes:

1. Incomplete context files
2. Insufficient input provided
3. Context files too large (over 2000 words each)

Solutions:

1. Check context file completeness:

• company.md has mission, team, priorities
• product.md has features, users, metrics
• personas.md has 2-3 rich personas
• competitors.md has 3-5 competitors

2. Provide full inputs:

• Don't paste partial PRDs
• Include all research files
• Give complete instructions

3. Optimize context size:

• See Context Optimization
• Remove unnecessary details
• Keep files focused on decision-relevant info

Problem: Agent team fails to start

Error: "Agent teams not available"

Solutions:

1. Check Claude subscription:

   • Requires Claude Pro ($20/mo) or API access
   • Free tier doesn't support agent teams

2. Verify Claude Code version:

   • Agent teams require Claude Code Desktop v0.2.0+
   • Update if needed

3. Check agent team setting:

   • Claude Code → Settings → Features
   • "Agent Teams" should be enabled

Context Loading Issues

Problem: Skill doesn't use my context files

Symptoms:

• Output is generic
• Doesn't mention my company/product
• Asks for info that's in context files

Solutions:

1. Verify context file location:

   context/
   ├── company.md
   ├── product.md
   ├── personas.md
   └── competitors.md
   

2. Check file names (must be exact):

   • ✅ company.md
   • ❌ Company.md
   • ❌ company-info.md

3. Verify Claude Code can read files:

   • Files must be in workspace folder
   • Check file permissions (readable)

4. Check context file format:

   • Must be valid Markdown
   • No binary/corrupted files

Token Limit Errors

Problem: "Context too large" error

Cause: Combined context + skill prompt + input exceeds token limit

Solutions:

1. Trim context files:

   • Remove unnecessary details
   • See Context Optimization

2. Split large inputs:

   • Instead of 20 interviews at once, do 10+10
   • Use batch processing skills

3. Use extended thinking selectively:

   • Adds thinking tokens to limit
   • Only use for complex tasks

Skill Not Showing Up

Problem: Skill doesn't appear in the / menu

Solutions:

1. Restart Claude Code — Quit and reopen the app
2. Check skill location — Skills should be in .claude/skills/ inside your Product Management OS folder
3. Re-download your Product Management OS — If skills are missing, download a fresh copy from your purchase email

Skills Running Slowly

Problem: Responses take a long time

Solutions:

1. Trim your context files — Shorter context = faster responses. See Context Optimization
2. Check your internet connection — Claude requires an active connection
3. Restart Claude Code — Sometimes a fresh session helps

Still Stuck?

1. Run /welcome — Claude can often diagnose issues itself
2. Restart your session — Close Claude and reopen the folder
3. Check your subscription — Make sure Claude Pro/Max is active
4. Email support — ron@mysecond.ai

Related Guides

• Using Agent Teams
• Context Optimization
• Terminology