name	mcp-pal-usage
description	Ensures proper use of PAL MCP tools (thinkdeep, debug, codereview, consensus, planner) for complex tasks requiring deep analysis, multi-model collaboration, or systematic investigation. Auto-activates when: - User requests debugging, code review, or planning assistance - Complex problems require systematic investigation - Multi-model consensus needed for architectural decisions - Deep thinking required for root cause analysis Provides guidance on: - When to use each PAL MCP tool - Proper continuation_id management - Model selection strategies - Workflow orchestration patterns
allowed-tools	Read, Grep, mcp__pal__chat, mcp__pal__thinkdeep, mcp__pal__debug, mcp__pal__codereview, mcp__pal__consensus, mcp__pal__planner, mcp__pal__secaudit, mcp__pal__precommit, mcp__pal__listmodels, mcp__pal__analyze, mcp__pal__refactor, mcp__pal__tracer, mcp__pal__testgen, mcp__pal__docgen, mcp__pal__clink

PAL MCP Usage Skill

This skill provides guidance on using PAL MCP tools effectively for complex software engineering tasks.

Available PAL MCP Tools

1. `mcppalchat` - General Collaboration

Use for:

Brainstorming and ideation
Getting second opinions
Quick consultations
Validation of approaches

Example:

mcp__pal__chat({
  model: "haiku",  // Fast for simple tasks
  prompt: "Review this approach for implementing dark mode",
  absolute_file_paths: ["/path/to/ThemeManager.swift"],
  working_directory_absolute_path: "/path/to/project"
})

When NOT to use:

Systematic debugging → use debug instead
Code review → use codereview instead
Strategic planning → use planner instead

2. `mcppaldebug` - Systematic Debugging

Use for:

Complex bugs with unclear root cause
Race conditions and concurrency issues
Memory leaks and performance problems
Mysterious crashes

Example:

mcp__pal__debug({
  model: "gemini-2.5-pro",  // Deep analysis capability
  step: "Investigate SwiftData relationship crash in LibraryView",
  step_number: 1,
  total_steps: 3,
  next_step_required: true,
  findings: "App crashes when accessing book.author.name. Suspect SwiftData fault issue.",
  hypothesis: "Accessing unfaulted relationship on background thread",
  relevant_files: ["/path/to/LibraryView.swift", "/path/to/Work.swift"],
  files_checked: ["/path/to/LibraryView.swift"],
  confidence: "medium"
})

Confidence levels:

exploring - Just starting investigation
low - Early hypothesis
medium - Some evidence gathered
high - Strong evidence
very_high - Very confident
almost_certain - Nearly proven
certain - 100% confirmed locally (skips external validation)

Critical: Always reuse continuation_id for multi-step debugging!

3. `mcppalcodereview` - Systematic Code Review

Use for:

Comprehensive quality assessment
Security vulnerability scanning
Architecture validation
Performance analysis

Review types:

full - Complete review (quality, security, performance, architecture)
security - Security-focused audit
performance - Performance bottleneck analysis
quick - Fast high-level review

Example:

mcp__pal__codereview({
  model: "grok-code-fast-1",  // Expert review capability
  step: "Review EnrichmentService for security and performance",
  step_number: 1,
  total_steps: 2,
  next_step_required: true,
  findings: "Starting comprehensive review...",
  relevant_files: ["/path/to/EnrichmentService.swift"],
  review_type: "full",
  confidence: "medium"
})

Validation types:

external (default) - Expert model validation after your review
internal - Local-only review (faster, less thorough)

4. `mcppalsecaudit` - Security Audit

Use for:

OWASP Top 10 vulnerability scanning
Security compliance validation
Pre-deployment security checks
Sensitive code path review

Audit focus:

owasp - OWASP Top 10 vulnerabilities
compliance - Regulatory compliance (GDPR, SOC2, etc.)
infrastructure - Infrastructure security (API keys, secrets)
dependencies - Third-party dependency vulnerabilities
comprehensive - All of the above

Example:

mcp__pal__secaudit({
  model: "grok-code-fast-1",  // Security expertise
  step: "Audit AuthenticationService for OWASP vulnerabilities",
  step_number: 1,
  total_steps: 2,
  next_step_required: true,
  findings: "Analyzing API key handling and session management...",
  relevant_files: ["/path/to/AuthenticationService.swift"],
  audit_focus: "owasp",
  threat_level: "high",
  confidence: "medium"
})

Threat levels:

low - Internal tools, non-production
medium - Production app with limited exposure
high - Public-facing production service
critical - Handles sensitive PII or financial data

5. `mcppalplanner` - Interactive Planning

Use for:

Complex project planning
Multi-phase migrations
Architectural design sessions
Strategic refactoring plans

Features:

Step-by-step planning with revision capability
Branch exploration for alternative approaches
Expert model validation of plans

Example:

mcp__pal__planner({
  model: "gemini-2.5-pro",  // Strategic thinking
  step: "Plan migration from KV storage to D1 database",
  step_number: 1,
  total_steps: 5,
  next_step_required: true
})

// Later: Branch to explore alternative approach
mcp__pal__planner({
  continuation_id: "abc123",  // REUSE ID!
  model: "gemini-2.5-pro",
  step: "Explore zero-downtime migration using dual-write pattern",
  step_number: 3,
  total_steps: 5,
  next_step_required: true,
  is_branch_point: true,
  branch_id: "zero-downtime-approach",
  branch_from_step: 2
})

6. `mcppalconsensus` - Multi-Model Consensus

Use for:

Critical architectural decisions
Technology selection
Complex trade-off analysis
Design pattern selection

Example:

mcp__pal__consensus({
  step: "Evaluate: Should we use SwiftData or Core Data for BooksTrack v4?",
  step_number: 1,
  total_steps: 4,  // 3 models + synthesis
  next_step_required: true,
  findings: "Initial analysis: SwiftData offers modern API, Core Data more mature",
  models: [
    {model: "gemini-2.5-pro", stance: "for"},      // Pro-SwiftData
    {model: "grok-code-fast-1", stance: "against"}, // Pro-Core Data
    {model: "claude-opus-4", stance: "neutral"}     // Unbiased analysis
  ],
  relevant_files: ["/path/to/Work.swift", "/path/to/Author.swift"]
})

Stances:

for - Argue in favor of proposal
against - Argue against proposal
neutral - Unbiased analysis

7. `mcppalprecommit` - Pre-Commit Validation

Use for:

Validating git changes before commit
Multi-repository change validation
Impact assessment
Completeness verification

Example:

mcp__pal__precommit({
  model: "grok-code-fast-1",
  step: "Validate staged changes for completeness and security",
  path: "/path/to/repo",
  step_number: 1,
  total_steps: 3,
  next_step_required: true,
  findings: "Analyzing git diff and impact...",
  include_staged: true,
  include_unstaged: true,
  confidence: "medium"
})

Validation options:

Compare to specific branch: compare_to: "main"
Focus on specific concerns: focus_on: "security"
Filter by severity: severity_filter: "high"

8. `mcppalthinkdeep` - Deep Thinking

Use for:

Complex problem analysis
Architecture decisions requiring deep reasoning
Performance challenges
Multi-stage investigation

Similar to debug but more general-purpose.

Example:

mcp__pal__thinkdeep({
  model: "gemini-2.5-pro",
  step: "Analyze the architectural implications of real-time sync",
  step_number: 1,
  total_steps: 3,
  next_step_required: true,
  findings: "Exploring WebSocket vs SSE vs polling trade-offs...",
  hypothesis: "SSE provides best balance of simplicity and reliability",
  focus_areas: ["architecture", "performance", "reliability"],
  confidence: "medium"
})

Model Selection Guide

Use listmodels to see all available models:

mcp__pal__listmodels()

Top Models (as of v2.0.60):

grok-code-fast-1 (256K context, code specialist, 70.8% SWE-Bench)
- Best for: Code review, security audits, architecture validation
- Score: 100
gemini-2.5-pro (1M context, thinking mode, code generation)
- Best for: Deep analysis, debugging, strategic planning
- Score: 100
gemini-3-pro-preview (1M context, thinking mode, latest)
- Best for: Cutting-edge analysis, complex reasoning
- Score: 100
grok-4-1-fast-non-reasoning (2M context)
- Best for: Large codebase analysis, massive context requirements
- Score: 100
haiku (fast, efficient)
- Best for: Quick consultations, simple implementations
- Auto-uses Sonnet in plan mode

Critical Continuation Pattern

ALWAYS reuse continuation_id for multi-turn conversations:

// First call
const step1 = await mcp__pal__debug({
  model: "gemini-2.5-pro",
  step: "Investigate crash",
  // ...
});
// Returns: continuation_id: "xyz789"

// Follow-up (CRITICAL: REUSE ID!)
const step2 = await mcp__pal__debug({
  continuation_id: "xyz789",  // ← MUST REUSE!
  model: "gemini-2.5-pro",
  step: "Continue investigation with new findings",
  // ...
});

Why this matters:

Preserves full conversation context
Maintains investigation state
Enables seamless resumption
Prevents redundant work

Workflow Decision Tree

User request
  ├─ "Debug this crash/bug/issue"
  │    → Use mcp__pal__debug
  │
  ├─ "Review this code"
  │    → Use mcp__pal__codereview
  │
  ├─ "Audit for security issues"
  │    → Use mcp__pal__secaudit
  │
  ├─ "Plan this migration/feature"
  │    → Use mcp__pal__planner
  │
  ├─ "Should we use X or Y?"
  │    → Use mcp__pal__consensus
  │
  ├─ "Validate my changes before commit"
  │    → Use mcp__pal__precommit
  │
  ├─ "Analyze this complex problem"
  │    → Use mcp__pal__thinkdeep
  │
  └─ "Quick question about approach"
       → Use mcp__pal__chat

Integration with Claude Code Agents

This skill works alongside:

cloudflare-specialist - Cloudflare-specific architecture
code-review-grok - Wraps mcp__pal__codereview with project context
security-auditor - Wraps mcp__pal__secaudit with project context
performance-analyzer - Wraps mcp__pal__thinkdeep for performance

Skill activates proactively to ensure:

Correct tool selection
Proper continuation_id management
Appropriate model selection
Complete workflow execution

Common Anti-Patterns

❌ Don't: Forget continuation_id

// First call - gets continuation_id
mcp__pal__debug({ step: "Step 1", ... });

// Second call - WRONG! No continuation_id
mcp__pal__debug({ step: "Step 2", ... });

✅ Do: Always reuse continuation_id

// First call
const result1 = mcp__pal__debug({ step: "Step 1", ... });
const contId = result1.continuation_id;

// Second call - CORRECT!
mcp__pal__debug({ continuation_id: contId, step: "Step 2", ... });

❌ Don't: Use wrong tool for task

// Debugging a crash with chat tool (too shallow)
mcp__pal__chat({ prompt: "Why does this crash?" });

✅ Do: Use systematic debugging tool

// Proper systematic investigation
mcp__pal__debug({
  step: "Investigate crash in LibraryView",
  hypothesis: "SwiftData concurrency issue",
  // ...
});

❌ Don't: Skip model selection

// No model specified - uses default
mcp__pal__codereview({ step: "Review code", ... });

✅ Do: Choose appropriate model

// Explicit model selection for security expertise
mcp__pal__codereview({
  model: "grok-code-fast-1",  // Security specialist
  step: "Review for OWASP vulnerabilities",
  // ...
});

Quick Reference Card

Task	Tool	Model	Why
Debug crash	`debug`	gemini-2.5-pro	Deep analysis, 1M context
Review code	`codereview`	grok-code-fast-1	Code specialist, security focus
Security audit	`secaudit`	grok-code-fast-1	OWASP expertise
Plan migration	`planner`	gemini-2.5-pro	Strategic thinking
Tech decision	`consensus`	3+ models	Multiple perspectives
Validate commit	`precommit`	grok-code-fast-1	Quality assurance
Analyze problem	`thinkdeep`	gemini-2.5-pro	Deep reasoning
Quick question	`chat`	haiku	Fast, efficient

Async PAL MCP Usage (v2.0.64)

Long-running PAL analyses can run in background:

// Launch comprehensive debug session in background
Task({
  subagent_type: "pal",
  prompt: "Deep investigation of memory leak in LibraryView",
  run_in_background: true
})

// Continue with other work...

// Retrieve results when ready
TaskOutput({
  task_id: "agent_xyz123",
  block: true,
  timeout: 180000  // 3 minutes for deep analysis
})

Background-friendly operations:

mcp__pal__debug - Complex multi-step debugging
mcp__pal__codereview with review_type: "full"
mcp__pal__secaudit with audit_focus: "comprehensive"
mcp__pal__consensus - Multi-model deliberation

Keep synchronous:

mcp__pal__chat - Quick consultations
mcp__pal__codereview with review_type: "quick"
mcp__pal__challenge - Immediate critical thinking

Named Sessions (v2.0.64)

For long debugging/review sessions, name your session:

/rename debug-memory-leak

Resume later from terminal:

claude --resume debug-memory-leak

Recommended Options (v2.0.62)

When presenting choices, add "(Recommended)" to preferred option:

AskUserQuestion({
  questions: [{
    question: "Which analysis depth?",
    header: "Analysis",
    options: [
      {label: "Quick review (Recommended)", description: "Fast, single-file"},
      {label: "Full analysis", description: "Comprehensive, multi-file"},
      {label: "Deep investigation", description: "Maximum depth, longest time"}
    ]
  }]
})

Last Updated: December 11, 2025 (v2.0.65) Maintained by: BooksTrack Project Related Skills: cloudflare-api-orchestration Related Agents: code-review-grok, security-auditor, performance-analyzer

mcp-pal-usage

Install Skill

SKILL.md

PAL MCP Usage Skill

Available PAL MCP Tools

1. `mcppalchat` - General Collaboration

2. `mcppaldebug` - Systematic Debugging

3. `mcppalcodereview` - Systematic Code Review

4. `mcppalsecaudit` - Security Audit

5. `mcppalplanner` - Interactive Planning

6. `mcppalconsensus` - Multi-Model Consensus

7. `mcppalprecommit` - Pre-Commit Validation

8. `mcppalthinkdeep` - Deep Thinking

Model Selection Guide

Critical Continuation Pattern

Workflow Decision Tree

Integration with Claude Code Agents

Common Anti-Patterns

❌ Don't: Forget continuation_id

✅ Do: Always reuse continuation_id

❌ Don't: Use wrong tool for task

✅ Do: Use systematic debugging tool

❌ Don't: Skip model selection

✅ Do: Choose appropriate model

Quick Reference Card

Async PAL MCP Usage (v2.0.64)

Named Sessions (v2.0.64)

Recommended Options (v2.0.62)

Install Skill

SKILL.md

PAL MCP Usage Skill

Available PAL MCP Tools

1. mcp__pal__chat - General Collaboration

2. mcp__pal__debug - Systematic Debugging

3. mcp__pal__codereview - Systematic Code Review

4. mcp__pal__secaudit - Security Audit

5. mcp__pal__planner - Interactive Planning

6. mcp__pal__consensus - Multi-Model Consensus

7. mcp__pal__precommit - Pre-Commit Validation

8. mcp__pal__thinkdeep - Deep Thinking

Model Selection Guide

Critical Continuation Pattern

Workflow Decision Tree

Integration with Claude Code Agents

Common Anti-Patterns

❌ Don't: Forget continuation_id

✅ Do: Always reuse continuation_id

❌ Don't: Use wrong tool for task

✅ Do: Use systematic debugging tool

❌ Don't: Skip model selection

✅ Do: Choose appropriate model

Quick Reference Card

Async PAL MCP Usage (v2.0.64)

Named Sessions (v2.0.64)

Recommended Options (v2.0.62)

1. `mcppalchat` - General Collaboration

2. `mcppaldebug` - Systematic Debugging

3. `mcppalcodereview` - Systematic Code Review

4. `mcppalsecaudit` - Security Audit

5. `mcppalplanner` - Interactive Planning

6. `mcppalconsensus` - Multi-Model Consensus

7. `mcppalprecommit` - Pre-Commit Validation

8. `mcppalthinkdeep` - Deep Thinking