morph-power-user

name	morph-power-user
description	Expert-level decision policy for morph_fastapply, warpgrep_codebase_search, and warpgrep_github_search with strategic tool selection and execution patterns.

Morph Power User

Expert-level decision policy for morph_fastapply, warpgrep_codebase_search, warpgrep_github_search, morph_browser_test_url, and morph_preview_test_pr.

Purpose

Guide strategic tool selection and execution patterns for Morph editing, search, and browser validation workflows. This skill focuses on what the plugin adds, when to use each Morph tool, when to fall back, and how to maximize success rate through proper preparation.

Plugin Capability Map

This plugin adds six practical Morph capabilities to Pi:

• existing-file editing through morph_fastapply
• local codebase exploration through warpgrep_codebase_search
• public GitHub source exploration through warpgrep_github_search
• browser automation for direct URLs through morph_browser_test_url
• PR-aware preview validation through morph_preview_test_pr
• session compaction through Morph compact integration

Quick Tool Selection

• Existing file, non-trivial edit -> morph_fastapply
• Existing file, tiny exact one-block replacement -> native edit
• Brand new file -> native write
• Local codebase question -> warpgrep_codebase_search
• Public GitHub source question -> warpgrep_github_search
• Direct URL or visible UI flow -> morph_browser_test_url
• PR preview with GitHub context -> morph_preview_test_pr
• Long session context reduction -> Morph compaction

When to Apply

• Multi-file refactoring or scattered edits across a codebase
• Exploratory code search in unfamiliar projects
• Public GitHub repository inspection without local cloning
• Large file edits where exact line matching is fragile
• Whitespace-sensitive merges (Python, YAML, Markdown)
• Direct URL smoke tests or visible UI flow validation
• Pull request preview validation with GitHub context

Core Principles

FastApply Decision Tree

1. Always read the target file first before choosing between edit and morph_fastapply
2. Use native edit only for:
   • Tiny exact one-block replacements
   • Simple string replacements where exact matching is clearly stable
3. Use native write for:
   • Brand new files
   • Complete file rewrites
4. Use morph_fastapply by default for non-trivial existing-file edits:
   • Files over about 80 lines
   • Block-shape changes
   • Multi-location edits
   • Refactoring that touches related functions/classes
   • When exact line matching would be brittle

Dry Run Strategy

Always use dry_run: true first when:

• Editing files you haven't fully read
• Making scattered changes across a large file
• Uncertain about anchor quality
• Working in production code paths

Skip dry run when:

• Repeating a previously previewed edit with minor adjustments
• Making trivial formatting fixes
• Time-sensitive hotfixes where you've already validated the change mentally

Anchor Quality

Good anchors:

function calculateTotal(items) {
  // ... existing code ...
}

Bad anchors:

// ... existing code ...
function calculateTotal(items) {
  // ... existing code ...
}

Rules:

• Include function/class signatures as anchors
• Keep at least 2-3 lines of unique context around changes
• Avoid generic markers like // ... existing code ... at the start
• Use distinctive variable names, comments, or structure as anchors

Anchor Quality Metrics:

Metric	Good	Fair	Poor
Uniqueness	1 match	2-3 matches	4+ matches
Context lines	3+ distinctive	2 distinctive	1 or generic
Specificity	Function signature	Variable name	Generic comment

WarpGrep Usage

Use warpgrep_codebase_search when:

• "Where is X implemented?"
• "How does this project handle Y?"
• "Find all usages of Z pattern"
• Exploring unfamiliar codebases
• Searching across multiple file types
• Answering local codebase questions about architecture, ownership, routes, handlers, imports, or where behavior lives

Use warpgrep_github_search when:

• Inspecting public repos without cloning
• Researching library implementation details
• Finding usage examples in popular projects
• Comparing approaches across different repos
• Answering public GitHub source questions about SDK internals or authoritative implementation behavior

Fall back to native tools when:

• WarpGrep times out (> 60s)
• You need exact regex matching
• The codebase is very small (< 10 files)
• You already know the exact file path

Browser Tool Usage

Use morph_browser_test_url when:

• You already have a concrete URL
• You want browser automation, smoke testing, click paths, or visible UI validation
• You do not need GitHub PR context

Use morph_preview_test_pr when:

• The task is specifically about a GitHub pull request
• You want preview deployment discovery
• You want PR-aware browser validation
• You want check-run updates or optional PR comments

Fall back to manual browser tools when:

• Morph credentials are unavailable
• The repository is not connected to the Morph GitHub App
• No usable preview deployment exists for the PR

Execution Patterns

Pattern 1: Safe Refactoring

1. warpgrep_codebase_search "find all usages of oldFunction"
2. Read each file identified
3. morph_fastapply with dry_run: true for each file
4. Review diffs
5. morph_fastapply with dry_run: false to apply
6. Run tests

Pattern 2: Exploratory Edit

1. warpgrep_codebase_search "how is authentication handled"
2. Read relevant files
3. Identify edit targets
4. morph_fastapply with dry_run: true
5. Validate approach with user if significant
6. Apply changes

Pattern 3: GitHub Research

1. warpgrep_github_search "owner/repo implementation of feature X"
2. Analyze results
3. Adapt pattern to local codebase
4. Use morph_fastapply unless the change is a tiny exact one-block replacement

Pattern 4: Multi-File Coordination

1. warpgrep_codebase_search "find all files importing module X"
2. Create change plan (list files and changes)
3. For each file:
   a. Read file
   b. morph_fastapply with dry_run: true
   c. Review diff
4. If all diffs look good:
   a. Apply all changes
   b. Run tests
5. If any diff is wrong:
   a. Adjust anchors for that file
   b. Retry from step 3

Real-World Code Examples

Example 1: Renaming Function Across Files

Scenario: Rename getUserData to fetchUserProfile across 5 files

Good approach:

// Step 1: Find all usages
warpgrep_codebase_search "getUserData function call import"

// Step 2: For each file, use FastApply with good anchors
// File: src/api/users.ts
export async function getUserData(userId: string) {
  // ... existing code ...
}

// File: src/components/Profile.tsx
import { getUserData } from '../api/users';
// ... existing code ...
const data = await getUserData(user.id);

Bad approach:

// Using generic anchors
// ... existing code ...
getUserData
// ... existing code ...

Example 2: Adding Validation to Multiple Forms

Scenario: Add email validation to 3 form components

Good approach:

// Step 1: Find all form components
warpgrep_codebase_search "form onSubmit email input"

// Step 2: Read each component to understand structure
// Step 3: Use FastApply with component-specific anchors

// ContactForm.tsx
const handleSubmit = (e: FormEvent) => {
  e.preventDefault();
  // ... existing code ...
};

// SignupForm.tsx
function SignupForm() {
  // ... existing code ...
  const onSubmit = async (data: FormData) => {
    // ... existing code ...
  };
}

Example 3: Updating API Endpoints

Scenario: Change API base URL from /api/v1 to /api/v2

Good approach:

// Step 1: Find all API calls
warpgrep_codebase_search "fetch axios /api/v1"

// Step 2: Group by file and review
// Step 3: Use FastApply with endpoint-specific anchors

// api/client.ts
const BASE_URL = '/api/v1';
// ... existing code ...

// services/users.ts
fetch('/api/v1/users')
// ... existing code ...

Troubleshooting Guide

Issue: FastApply Matches Wrong Location

Symptoms:

• Diff shows unexpected file section
• Changes applied to wrong function
• Multiple similar patterns in file

Diagnosis:

// Check anchor uniqueness
warpgrep_codebase_search "[your-anchor-pattern] [filename]"
// If multiple results, anchor is ambiguous

Solution:

1. Add more distinctive context (function name, unique variable)
2. Include line above and below the target
3. Use class/module name in anchor
4. Read file to find unique identifiers

Issue: FastApply Skips Some Changes

Symptoms:

• Diff shows fewer changes than expected
• Some locations not modified
• Partial application

Diagnosis:

• Review dry run diff carefully
• Check if anchors exist in all target locations
• Verify marker placement

Solution:

1. Ensure anchors are present in all target locations
2. Use consistent anchor patterns
3. Break into multiple FastApply calls if needed
4. Verify file content hasn't changed since reading

Issue: WarpGrep Returns Too Many Results

Symptoms:

• 50+ results returned
• Many irrelevant matches
• Hard to identify relevant code

Diagnosis:

• Query is too broad
• Missing framework/library context
• Searching for common terms

Solution:

1. Add more specific terms (function names, file paths)
2. Include framework context ("React", "Vue", "Next.js")
3. Narrow to specific file types
4. Use multiple targeted searches instead of one broad search

Issue: WarpGrep Returns No Results

Symptoms:

• Zero results
• Expected code not found
• Query seems correct

Diagnosis:

• Query is too specific
• Wrong terminology used
• Code uses different naming convention

Solution:

1. Broaden search terms
2. Try alternative terminology
3. Search for related patterns
4. Fall back to native rg with regex
5. Ask user for hints about location

Issue: FastApply Fails After File Changed

Symptoms:

• FastApply worked before, fails now
• Anchors no longer match
• File was modified externally

Diagnosis:

• File content changed since last read
• Git pull brought new changes
• Another tool modified the file

Solution:

1. Re-read the file
2. Update anchors based on current content
3. Review what changed
4. Adjust edit strategy if needed

Multi-File Refactoring Coordination

Strategy 1: Sequential (Safe)

When to use:

• Changes are independent
• Each file can be tested separately
• Low risk of conflicts

Process:

For each file:
  1. Read file
  2. FastApply with dry_run
  3. Review diff
  4. Apply if good
  5. Test
  6. Move to next file

Strategy 2: Batch (Efficient)

When to use:

• Changes are similar across files
• High confidence in approach
• Files are related

Process:

1. Read all files
2. FastApply dry_run for all
3. Review all diffs together
4. If all good, apply all
5. Run comprehensive tests
6. If any fail, rollback and use Sequential

Strategy 3: Dependency-Ordered (Complex)

When to use:

• Changes have dependencies
• Order matters (API → client)
• Breaking changes involved

Process:

1. Identify dependency order
2. Start with lowest dependency (API, types)
3. Apply and test
4. Move up dependency chain
5. Apply and test each level
6. Final integration test

Advanced Techniques

Technique 1: Anchor Validation

Before applying FastApply, validate anchors:

// Count occurrences
warpgrep_codebase_search "[anchor-pattern] [filename]"

// Expected: 1 result
// If 0: anchor doesn't exist, adjust
// If 2+: anchor is ambiguous, add more context

Technique 2: Progressive Refinement

For complex edits:

1. Start with broad WarpGrep search
2. Narrow down to relevant files
3. Read files to understand structure
4. Create detailed change plan
5. Apply changes incrementally
6. Test after each increment

Technique 3: Fallback Chaining

When Morph tools fail:

1. Try morph_fastapply
   ↓ (if fails)
2. Adjust anchors and retry
   ↓ (if still fails)
3. Fall back to native edit only for tiny exact one-block replacements
   ↓ (if fails)
4. Read file again and reassess
   ↓ (if still fails)
5. Ask user for guidance

Common Mistakes

❌ Don't

• Call morph_fastapply without reading the file first
• Use feature-level intent instead of code snippets with markers
• Skip dry run on unfamiliar or critical files
• Use morph_fastapply for brand new files
• Provide entire file content when only changing a few lines
• Use WarpGrep for exact file path lookups
• Retry the same failing FastApply call without adjusting anchors
• Apply changes to multiple files without testing incrementally

✅ Do

• Read target files before editing
• Prepare marker-wrapped snippets with good anchors
• Use dry run for scattered or large changes
• Tighten anchors once when FastApply lacks context before falling back
• Use WarpGrep for exploratory questions
• Adjust anchor context when FastApply fails
• Verify changes after applying
• Test after each file in multi-file refactoring
• Validate anchor uniqueness before applying

Fallback Strategy

When morph_fastapply fails:

1. Check if anchors are too generic or ambiguous
2. Read the file again and tighten anchor context once
3. Fall back to native edit only if the change is a tiny exact one-block replacement
4. For very large files, consider breaking into multiple smaller edits

When warpgrep_codebase_search fails:

1. Fall back to bash with rg for pattern matching
2. Use read to inspect matching files
3. Consider using GitHub search tools if it's a public repo

When warpgrep_github_search fails:

1. Use native github_search_code for exact symbol search
2. Use github_get_file_contents if you know the path
3. Use web search for documentation or examples

Configuration Awareness

This skill assumes:

• routing.editMode: "force" or "strong" for FastApply preference
• routing.codebaseSearchMode: "force" or "strong" for local WarpGrep
• routing.githubSearchMode: "force" or "strong" for GitHub WarpGrep
• routing.fallbackToNativeTools: true for automatic fallback

Adjust behavior if user has different routing modes configured.

Success Metrics

• Dry run used before applying scattered edits: ✓
• File read before FastApply decision: ✓
• Good anchor quality (distinctive context): ✓
• Appropriate tool selection (FastApply vs edit vs write): ✓
• Fallback triggered when Morph tools fail: ✓
• WarpGrep used for exploratory questions: ✓
• Native tools used for exact lookups: ✓
• Multi-file changes coordinated properly: ✓
• Anchor uniqueness validated: ✓
• Tests run after changes: ✓