| 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
- Always read the target file first before choosing between
edit and morph_fastapply
- Use native
edit only for:
- Tiny exact one-block replacements
- Simple string replacements where exact matching is clearly stable
- Use native
write for:
- Brand new files
- Complete file rewrites
- 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) {
}
Bad anchors:
function calculateTotal(items) {
}
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:
warpgrep_codebase_search "getUserData function call import"
export async function getUserData(userId: string) {
}
import { getUserData } from '../api/users';
const data = await getUserData(user.id);
Bad approach:
getUserData
Example 2: Adding Validation to Multiple Forms
Scenario: Add email validation to 3 form components
Good approach:
warpgrep_codebase_search "form onSubmit email input"
const handleSubmit = (e: FormEvent) => {
e.preventDefault();
};
function SignupForm() {
const onSubmit = async (data: FormData) => {
};
}
Example 3: Updating API Endpoints
Scenario: Change API base URL from /api/v1 to /api/v2
Good approach:
warpgrep_codebase_search "fetch axios /api/v1"
const BASE_URL = '/api/v1';
fetch('/api/v1/users')
Troubleshooting Guide
Issue: FastApply Matches Wrong Location
Symptoms:
- Diff shows unexpected file section
- Changes applied to wrong function
- Multiple similar patterns in file
Diagnosis:
warpgrep_codebase_search "[your-anchor-pattern] [filename]"
Solution:
- Add more distinctive context (function name, unique variable)
- Include line above and below the target
- Use class/module name in anchor
- 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:
- Ensure anchors are present in all target locations
- Use consistent anchor patterns
- Break into multiple FastApply calls if needed
- 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:
- Add more specific terms (function names, file paths)
- Include framework context ("React", "Vue", "Next.js")
- Narrow to specific file types
- 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:
- Broaden search terms
- Try alternative terminology
- Search for related patterns
- Fall back to native
rg with regex
- 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:
- Re-read the file
- Update anchors based on current content
- Review what changed
- 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:
warpgrep_codebase_search "[anchor-pattern] [filename]"
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:
- Check if anchors are too generic or ambiguous
- Read the file again and tighten anchor context once
- Fall back to native
edit only if the change is a tiny exact one-block replacement
- For very large files, consider breaking into multiple smaller edits
When warpgrep_codebase_search fails:
- Fall back to
bash with rg for pattern matching
- Use
read to inspect matching files
- Consider using GitHub search tools if it's a public repo
When warpgrep_github_search fails:
- Use native
github_search_code for exact symbol search
- Use
github_get_file_contents if you know the path
- 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: ✓