mcp-pal-usage

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. mcp__pal__chat - 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. mcp__pal__debug - 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. mcp__pal__codereview - 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. mcp__pal__secaudit - 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. mcp__pal__planner - 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. mcp__pal__consensus - 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. mcp__pal__precommit - 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. mcp__pal__thinkdeep - 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