pi-orchestrator-config 4.1.5

package/skills/conflict-resolver/SKILL.md

@@ -0,0 +1,213 @@
+---
+name: conflict-resolver
+description: "Resolve git merge/rebase conflicts by analyzing git history, commit intent, and code context. Use when merge or rebase produces conflicts."
+---
+
+# Git Conflict Resolver
+
+Resolve merge and rebase conflicts by understanding WHY both sides made their changes,
+then choosing the right resolution based on intent — not just line-by-line diffing.
+
+## When to Use
+
+- `git merge` / `git rebase` / `git cherry-pick` produced conflicts
+- PR can't merge due to conflicts
+- Worktree rebase has conflicts after `git rebase origin/main`
+
+## Phase 1: Understand the Conflict
+
+Before touching any file, gather context:
+
+```bash
+# List all conflicted files
+git diff --name-only --diff-filter=U
+
+# Show ALL conflict types (UU=both modified, AA=both added, etc.)
+git status --porcelain | grep "^[UAD][UAD]"
+```
+
+### Detect the operation type
+
+```bash
+# What caused the conflict? (worktree-safe — no .git/ path assumptions)
+if git rev-parse --verify -q MERGE_HEAD >/dev/null 2>&1; then
+  echo "MERGE — ours=HEAD, theirs=MERGE_HEAD"
+  THEIRS="MERGE_HEAD"
+elif git rev-parse --verify -q REBASE_HEAD >/dev/null 2>&1; then
+  echo "REBASE — ours=upstream (HEAD), theirs=your commits (REBASE_HEAD) — swapped!"
+  THEIRS="REBASE_HEAD"
+elif git rev-parse --verify -q CHERRY_PICK_HEAD >/dev/null 2>&1; then
+  echo "CHERRY-PICK — ours=HEAD, theirs=CHERRY_PICK_HEAD"
+  THEIRS="CHERRY_PICK_HEAD"
+fi
+
+# For EACH conflicted file — see what each side changed
+git log --oneline $THEIRS..HEAD -- <file>    # our commits
+git log --oneline HEAD..$THEIRS -- <file>    # their commits
+
+# Get blame for context
+git blame HEAD -- <file> | head -30
+git blame $THEIRS -- <file> | head -30
+
+# View the actual conflict markers
+grep -n "<<<<<<\|======\|>>>>>>" <file>
+```
+
+**⚠️ During rebase, `--ours` and `--theirs` are SWAPPED:**
+
+- `git merge`: `--ours` = your branch, `--theirs` = incoming
+- `git rebase`: `--ours` = upstream (the branch you're rebasing onto), `--theirs` = your commits
+
+**Iron Law: understand BOTH sides before resolving. Never blindly accept one side.**
+
+## Phase 2: Classify the Conflict
+
+Classify each side's changes by intent:
+
+| Type | Indicators | Resolution Priority |
+|------|-----------|---------------------|
+| Security fix | "security", "vuln", "CVE" in commit message | Highest — always keep |
+| Bug fix | "fix", "bug", "patch" in commit message; small targeted change | Highest — always keep |
+| Refactor | "refactor", "cleanup", "rename"; no behavior change | Medium — preserve both if compatible |
+| Feature | "feat", "add", "implement"; new functionality | Medium — merge carefully |
+| Style | "style", "format", "lint"; whitespace/formatting only | Lowest — accept either side |
+
+## Phase 3: Resolve
+
+### Decision Framework
+
+1. **Same intent, compatible changes** → merge both (most common)
+2. **Bug fix vs feature** → bug fix wins, integrate feature around it
+3. **Conflicting logic** → prefer the more recent or more tested change
+4. **Style/format conflicts** → accept either, prefer consistency with surrounding code
+5. **Deletions vs modifications** → investigate why deleted; deletion is usually intentional
+6. **Lock files** (`package-lock.json`, `uv.lock`, `yarn.lock`, `pnpm-lock.yaml`) → NEVER merge manually.
+   Resolve the **manifest first** (`package.json`, `pyproject.toml`, etc.), then regenerate:
+
+```bash
+# Step 1: Resolve the manifest file (package.json, pyproject.toml) normally
+# Step 2: Delete the conflicted lock file and regenerate
+
+# For uv.lock
+rm -f uv.lock
+uv lock
+
+# For package-lock.json
+rm -f package-lock.json
+npm install
+
+# For yarn.lock
+rm -f yarn.lock
+yarn install
+```
+
+The manifest defines WHAT you want. The lock file is generated FROM the manifest. Never pick a side for the lock file — just regenerate it.
+
+### Resolution Commands
+
+```bash
+# Accept theirs entirely (incoming changes)
+git checkout --theirs <file>
+git add <file>
+
+# Accept ours entirely (current branch changes)
+git checkout --ours <file>
+git add <file>
+```
+
+**⚠️ During rebase, `--ours`/`--theirs` are swapped.** If unsure, use `git diff :2:<file> :3:<file>` to compare stage 2 (ours) vs stage 3 (theirs) directly.
+
+```bash
+# Manual resolution
+# 1. Open file, read conflict markers
+# 2. Remove <<<<<<< ======= >>>>>>> markers
+# 3. Combine changes based on intent analysis
+# 4. Verify syntax
+git add <file>
+```
+
+### For Manual Resolution
+
+1. Read the ENTIRE conflict block — not just the markers
+2. Check what comes BEFORE and AFTER the conflict — context matters
+3. If both sides add imports → keep both (deduplicate)
+4. If both sides modify the same function → merge logic carefully, test
+5. If one side deletes code the other modifies → check git log to understand why
+
+## Phase 4: Verify
+
+```bash
+# No remaining conflict markers
+grep -rn "<<<<<<\|======\|>>>>>>" <resolved-files>
+
+# No unresolved files
+git diff --name-only --diff-filter=U
+
+# Syntax check (language-dependent)
+# Python
+uv run python -c "import ast; ast.parse(open('<file>').read())"
+# TypeScript/JavaScript
+npx tsc --noEmit
+# Go
+go build ./...
+
+# Run tests
+uv run pytest -q    # or npm test, go test, etc.
+```
+
+## Phase 5: Complete
+
+```bash
+# For merge
+git add <all-resolved-files>
+git commit  # uses merge commit message
+
+# For rebase
+git add <all-resolved-files>
+git rebase --continue
+```
+
+## Common Patterns
+
+### Import Conflicts
+
+Both sides added different imports → keep all, deduplicate:
+
+```python
+# OURS
+from module import foo, bar
+
+# THEIRS
+from module import foo, baz
+
+# RESOLVED
+from module import bar, baz, foo
+```
+
+### Function Modification Conflicts
+
+Both sides changed the same function → merge logic:
+
+1. Read both versions completely
+2. Identify what each change does
+3. If independent changes → combine both
+4. If conflicting behavior → pick the one that matches current requirements
+
+### Config/YAML Conflicts
+
+Both sides added different config entries → merge sections:
+
+```yaml
+# Usually safe to keep both additions
+# Watch for duplicate keys — last one wins in YAML
+```
+
+## Anti-Patterns
+
+| Don't | Why | Instead |
+|-------|-----|---------|
+| `git checkout --ours .` | Discards ALL incoming changes | Resolve file by file |
+| Manually edit lock files | Corrupts dependency resolution | Regenerate from scratch |
+| Skip git blame | Wrong intent, wrong resolution | Always check commit history |
+| Resolve without understanding | Creates subtle bugs | Read both sides first |
+| Accept AI's first suggestion blindly | AI often picks one side | Verify the merge makes sense |

package/skills/skill-creator/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: skill-creator
+description: "Save successful workflows as reusable pi skills. Use when a workflow worked well and should be preserved for future use."
+---
+
+# Create Skills from Experience
+
+## When to Use
+
+After completing a task that involved a non-obvious workflow:
+
+- Multi-step debugging process that worked
+- Build/deploy procedure that required specific steps
+- Integration pattern that took multiple attempts to get right
+- Any workflow where you think "I should remember how to do this"
+
+## How to Create a Skill
+
+1. **Identify the workflow** — what steps did you follow? What worked?
+2. **Write the SKILL.md** — save to `~/.agents/skills/<name>/SKILL.md`
+3. **Keep it specific and actionable** — steps, commands, verification
+
+## SKILL.md Format
+
+```markdown
+---
+name: skill-name
+description: "One-line description of what this skill does and when to use it."
+---
+
+# Skill Title
+
+## When to Use
+
+- Trigger condition 1
+- Trigger condition 2
+
+## Steps
+
+1. Step one with exact commands
+2. Step two
+3. Verification step
+
+## Pitfalls
+
+- Common mistake and how to avoid it
+```
+
+## Rules
+
+- **name**: lowercase, hyphenated, max 64 chars
+- **description**: one line, max 1024 chars, explains WHEN to use it
+- **Body**: concrete steps, exact commands, verification
+- **No fluff**: skip background, motivation, history — just the procedure
+- **Include pitfalls**: what goes wrong and how to avoid it
+- **Include verification**: how to confirm it worked
+
+## Where to Save
+
+```bash
+mkdir -p ~/.agents/skills/<skill-name>
+# Write SKILL.md there
+```
+
+Skills in `~/.agents/skills/` are user-local and automatically discovered by pi.
+
+## Good vs Bad Skills
+
+**Good skill:** Specific procedure with exact commands
+
+```text
+## Steps
+1. Run `uv run pytest tests/ -q` to get baseline
+2. Check for `FAILED` in output
+3. If failures, run `uv run pytest tests/test_specific.py -v` for details
+```
+
+**Bad skill:** Vague advice
+
+```text
+## Steps
+1. Run tests
+2. Check results
+3. Fix issues
+```

package/skills/systematic-debugging/SKILL.md

@@ -0,0 +1,353 @@
+---
+name: systematic-debugging
+description: "4-phase root cause debugging: understand bugs before fixing."
+---
+
+# Systematic Debugging
+
+## Overview
+
+Random fixes waste time and create new bugs. Quick patches mask underlying issues.
+
+**Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure.
+
+**Violating the letter of this process is violating the spirit of debugging.**
+
+## The Iron Law
+
+```text
+NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
+```
+
+If you haven't completed Phase 1, you cannot propose fixes.
+
+## When to Use
+
+Use for ANY technical issue:
+
+- Test failures
+- Bugs in production
+- Unexpected behavior
+- Performance problems
+- Build failures
+- Integration issues
+
+**Use this ESPECIALLY when:**
+
+- Under time pressure (emergencies make guessing tempting)
+- "Just one quick fix" seems obvious
+- You've already tried multiple fixes
+- Previous fix didn't work
+- You don't fully understand the issue
+
+**Don't skip when:**
+
+- Issue seems simple (simple bugs have root causes too)
+- You're in a hurry (rushing guarantees rework)
+- Someone wants it fixed NOW (systematic is faster than thrashing)
+
+## The Four Phases
+
+You MUST complete each phase before proceeding to the next.
+
+---
+
+## Phase 1: Root Cause Investigation
+
+**BEFORE attempting ANY fix:**
+
+### 1. Read Error Messages Carefully
+
+- Don't skip past errors or warnings
+- They often contain the exact solution
+- Read stack traces completely
+- Note line numbers, file paths, error codes
+
+**Action:** Use `read` on the relevant source files. Use `bash` with `grep -rn` to find the error string in the codebase.
+
+### 2. Reproduce Consistently
+
+- Can you trigger it reliably?
+- What are the exact steps?
+- Does it happen every time?
+- If not reproducible → gather more data, don't guess
+
+**Action:** Use `bash` to run the failing test or trigger the bug:
+
+```bash
+# Run specific failing test
+uv run pytest tests/test_module.py::test_name -v
+
+# Run with verbose output
+uv run pytest tests/test_module.py -v --tb=long
+```
+
+### 3. Check Recent Changes
+
+- What changed that could cause this?
+- Git diff, recent commits
+- New dependencies, config changes
+
+**Action:**
+
+```bash
+# Recent commits
+git log --oneline -10
+
+# Uncommitted changes
+git diff
+
+# Changes in specific file
+git log -p --follow src/problematic_file.py | head -100
+```
+
+### 4. Gather Evidence in Multi-Component Systems
+
+**WHEN system has multiple components (API → service → database, CI → build → deploy):**
+
+**BEFORE proposing fixes, add diagnostic instrumentation:**
+
+For EACH component boundary:
+
+- Log what data enters the component
+- Log what data exits the component
+- Verify environment/config propagation
+- Check state at each layer
+
+Run once to gather evidence showing WHERE it breaks.
+THEN analyze evidence to identify the failing component.
+THEN investigate that specific component.
+
+### 5. Trace Data Flow
+
+**WHEN error is deep in the call stack:**
+
+- Where does the bad value originate?
+- What called this function with the bad value?
+- Keep tracing upstream until you find the source
+- Fix at the source, not at the symptom
+
+**Action:** Use `bash` with `grep` to trace references:
+
+```bash
+# Find where the function is called
+grep -rn "function_name(" src/ --include="*.py"
+
+# Find where the variable is set
+grep -rn "variable_name\s*=" src/ --include="*.py"
+```
+
+### Phase 1 Completion Checklist
+
+- [ ] Error messages fully read and understood
+- [ ] Issue reproduced consistently
+- [ ] Recent changes identified and reviewed
+- [ ] Evidence gathered (logs, state, data flow)
+- [ ] Problem isolated to specific component/code
+- [ ] Root cause hypothesis formed
+
+**STOP:** Do not proceed to Phase 2 until you understand WHY it's happening.
+
+---
+
+## Phase 2: Pattern Analysis
+
+**Find the pattern before fixing:**
+
+### 1. Find Working Examples
+
+- Locate similar working code in the same codebase
+- What works that's similar to what's broken?
+
+**Action:** Use `bash` with `grep` to find comparable patterns:
+
+```bash
+grep -rn "similar_pattern" src/ --include="*.py"
+```
+
+### 2. Compare Against References
+
+- If implementing a pattern, read the reference implementation COMPLETELY
+- Don't skim — read every line
+- Understand the pattern fully before applying
+
+### 3. Identify Differences
+
+- What's different between working and broken?
+- List every difference, however small
+- Don't assume "that can't matter"
+
+### 4. Understand Dependencies
+
+- What other components does this need?
+- What settings, config, environment?
+- What assumptions does it make?
+
+---
+
+## Phase 3: Hypothesis and Testing
+
+**Scientific method:**
+
+### 1. Form a Single Hypothesis
+
+- State clearly: "I think X is the root cause because Y"
+- Write it down
+- Be specific, not vague
+
+### 2. Test Minimally
+
+- Make the SMALLEST possible change to test the hypothesis
+- One variable at a time
+- Don't fix multiple things at once
+
+### 3. Verify Before Continuing
+
+- Did it work? → Phase 4
+- Didn't work? → Form NEW hypothesis
+- DON'T add more fixes on top
+
+### 4. When You Don't Know
+
+- Say "I don't understand X"
+- Don't pretend to know
+- Ask the user for help
+- Research more
+
+---
+
+## Phase 4: Implementation
+
+**Fix the root cause, not the symptom:**
+
+### 1. Create Failing Test Case
+
+- Simplest possible reproduction
+- Automated test if possible
+- MUST have before fixing
+- Use the `test-driven-development` skill
+
+### 2. Implement Single Fix
+
+- Address the root cause identified
+- ONE change at a time
+- No "while I'm here" improvements
+- No bundled refactoring
+
+### 3. Verify Fix
+
+```bash
+# Run the specific regression test
+uv run pytest tests/test_module.py::test_regression -v
+
+# Run full suite — no regressions
+uv run pytest tests/ -q
+```
+
+### 4. If Fix Doesn't Work — The Rule of Three
+
+- **STOP.**
+- Count: How many fixes have you tried?
+- If < 3: Return to Phase 1, re-analyze with new information
+- **If ≥ 3: STOP and question the architecture (step 5 below)**
+- DON'T attempt Fix #4 without architectural discussion
+
+### 5. If 3+ Fixes Failed: Question Architecture
+
+**Pattern indicating an architectural problem:**
+
+- Each fix reveals new shared state/coupling in a different place
+- Fixes require "massive refactoring" to implement
+- Each fix creates new symptoms elsewhere
+
+**STOP and question fundamentals:**
+
+- Is this pattern fundamentally sound?
+- Are we "sticking with it through sheer inertia"?
+- Should we refactor the architecture vs. continue fixing symptoms?
+
+**Discuss with the user before attempting more fixes.**
+
+This is NOT a failed hypothesis — this is a wrong architecture.
+
+---
+
+## Red Flags — STOP and Follow Process
+
+If you catch yourself thinking:
+
+- "Quick fix for now, investigate later"
+- "Just try changing X and see if it works"
+- "Add multiple changes, run tests"
+- "Skip the test, I'll manually verify"
+- "It's probably X, let me fix that"
+- "I don't fully understand but this might work"
+- "Pattern says X but I'll adapt it differently"
+- "Here are the main problems: [lists fixes without investigation]"
+- Proposing solutions before tracing data flow
+- **"One more fix attempt" (when already tried 2+)**
+- **Each fix reveals a new problem in a different place**
+
+**ALL of these mean: STOP. Return to Phase 1.**
+
+**If 3+ fixes failed:** Question the architecture (Phase 4 step 5).
+
+## Common Rationalizations
+
+| Excuse | Reality |
+| ------ | ------- |
+| "Issue is simple, don't need process" | Simple issues have root causes too. Process is fast for simple bugs. |
+| "Emergency, no time for process" | Systematic debugging is FASTER than guess-and-check thrashing. |
+| "Just try this first, then investigate" | First fix sets the pattern. Do it right from the start. |
+| "I'll write test after confirming fix works" | Untested fixes don't stick. Test first proves it. |
+| "Multiple fixes at once saves time" | Can't isolate what worked. Causes new bugs. |
+| "Reference too long, I'll adapt the pattern" | Partial understanding guarantees bugs. Read it completely. |
+| "I see the problem, let me fix it" | Seeing symptoms ≠ understanding root cause. |
+| "One more fix attempt" (after 2+ failures) | 3+ failures = architectural problem. Question the pattern, don't fix again. |
+
+## Quick Reference
+
+| Phase | Key Activities | Success Criteria |
+| ----- | -------------- | ---------------- |
+| **1. Root Cause** | Read errors, reproduce, check changes, gather evidence, trace data flow | Understand WHAT and WHY |
+| **2. Pattern** | Find working examples, compare, identify differences | Know what's different |
+| **3. Hypothesis** | Form theory, test minimally, one variable at a time | Confirmed or new hypothesis |
+| **4. Implementation** | Create regression test, fix root cause, verify | Bug resolved, all tests pass |
+
+## Pi Agent Integration
+
+### Investigation Tools
+
+Use these pi tools during Phase 1:
+
+- **`bash`** (grep, find, rg) — Find error strings, trace function calls, locate patterns
+- **`read`** — Read source code for precise analysis
+- **`bash`** — Run tests, check git history, reproduce bugs
+- **`web_search`** — Research error messages, library docs
+
+### With subagent
+
+For complex multi-component debugging, the orchestrator dispatches the debugger agent:
+
+The debugger diagnoses only — it does not modify files.
+The orchestrator delegates the actual fix to the appropriate language specialist.
+
+### With test-driven-development
+
+When fixing bugs:
+
+1. Write a test that reproduces the bug (RED)
+2. Debug systematically to find root cause
+3. Fix the root cause (GREEN)
+4. The test proves the fix and prevents regression
+
+## Real-World Impact
+
+From debugging sessions:
+
+- Systematic approach: 15-30 minutes to fix
+- Random fixes approach: 2-3 hours of thrashing
+- First-time fix rate: 95% vs 40%
+- New bugs introduced: Near zero vs common
+
+**No shortcuts. No guessing. Systematic always wins.**