refactor(create-pr): improve skill per writing-skills guidelines

plugins/me/skills/create-pr/SKILL.md

@@ -1,15 +1,13 @@
 ---
 name: create-pr
-description: Use when user requests commit, push, PR creation, merge, or git workflow. Enforces base branch verification and conflict detection before pushing.
-version: 1.0.0
-user-invocable: true
+description: Use when user asks to commit and push, create PR, or says "ready to merge"
 ---
 
 # Create PR
 
-Automates git workflow: commit → conflict check → push → PR creation.
+Complete git workflow from commit to merge-ready PR.
 
-**Core principle**: Always verify base branch and conflicts before pushing.
+**Core principle**: Verify before every transition—commit→push, push→PR, PR→merge-ready.
 
 ## When to Use
 
@@ -23,110 +21,82 @@ Do NOT use when:
 - User only wants to commit (not push)
 - Changes not ready (tests failing, WIP)
 
+## Workflow Overview
+
+```dot
+digraph create_pr {
+    rankdir=TB;
+    node [shape=box];
+
+    start [label="Start" shape=ellipse];
+    status [label="1. git status\n+ git log"];
+    add [label="2. git add (specific files)"];
+    commit [label="3. git commit"];
+    base [label="4. Determine base branch"];
+    conflict_check [label="5. Check conflicts\n(merge-tree)"];
+    has_conflict [label="Conflicts?" shape=diamond];
+    resolve [label="Resolve or ask user"];
+    push [label="6. git push -u origin HEAD"];
+    create_pr [label="7. gh pr create --base"];
+    check_status [label="8. gh pr view\n(mergeable, mergeStateStatus)"];
+    pr_status [label="Status?" shape=diamond];
+    update [label="9. Merge base + push"];
+    done [label="Merge-ready" shape=ellipse];
+
+    start -> status -> add -> commit -> base -> conflict_check -> has_conflict;
+    has_conflict -> push [label="clean"];
+    has_conflict -> resolve [label="conflicts"];
+    resolve -> conflict_check;
+    push -> create_pr -> check_status -> pr_status;
+    pr_status -> done [label="CLEAN"];
+    pr_status -> update [label="BEHIND"];
+    pr_status -> resolve [label="DIRTY"];
+    update -> check_status;
+}
+```
+
 ## Red Flags - STOP
 
 Stop if:
 - You don't know which base branch to use
-- You skipped conflict check
+- You skipped conflict check before push
 - You used `git add` without first running `git status`
+- You created PR but didn't check status afterward
+- You stopped at PR creation without verifying merge-ready
+- You said "GitHub will notify" or "CI will catch it"
+- You said "just pushed so base hasn't changed"
 
-## Quick Reference
-
-```bash
-# 1. Check status
-git status
-git log --oneline -5
-
-# 2. Add specific files
-git add path/to/file1 path/to/file2
-
-# 3. Commit
-git commit -m "type: description"
-
-# 4. Verify base branch
-gh repo view --json defaultBranchRef -q .defaultBranchRef.name
-# OR ask user if unclear
-
-# 5. Check conflicts BEFORE push
-git fetch origin <base-branch>
-git merge-tree $(git merge-base HEAD origin/<base-branch>) HEAD origin/<base-branch>
-
-# 6. Push
-git push -u origin HEAD
-
-# 7. Create PR with explicit base
-gh pr create --base <base-branch> --title "..." --body "..."
-```
-
-## Workflow
-
-### 1. Commit Changes
-
-```bash
-# Always check what will be added
-git status
-
-# Add SPECIFIC files (not -A)
-git add src/file1.ts src/file2.ts
-
-# Commit
-git commit -m "feat: add new feature"
-```
-
-**Never**: `git add -A` without reviewing `git status` first
-
-### 2. Determine Base Branch
-
-**Option A - Check repository default:**
-```bash
-gh repo view --json defaultBranchRef -q .defaultBranchRef.name
-```
-
-**Option B - Check existing PR:**
-```bash
-gh pr list --limit 1 --json baseRefName -q '.[0].baseRefName'
-```
-
-**Option C - Ask user:**
-If both fail or unclear, ask: "Which branch should this PR target? (main/develop/other)"
-
-**Never**: Assume without verification
-
-### 3. Check Conflicts Before Push
-
-```bash
-git fetch origin <base-branch>
-git merge-tree $(git merge-base HEAD origin/<base-branch>) HEAD origin/<base-branch>
-```
-
-**Exit code 0**: No conflicts, proceed
-**Exit code 1**: Conflicts detected, show user and ask how to proceed
-
-### 4. Push
-
-```bash
-git push -u origin HEAD
-```
+**All of these mean: Follow complete workflow.**
 
-### 5. Create PR
-
-```bash
-gh pr create \
-  --base <base-branch> \
-  --title "Title from commit" \
-  --body "$(cat <<'EOF'
-## Summary
-- Change 1
-- Change 2
-
-## Test plan
-- [ ] Tests pass
-- [ ] Manual verification completed
-EOF
-)"
-```
+## Quick Reference
 
-**Always use `--base` flag explicitly**
+| Step | Command | Notes |
+|------|---------|-------|
+| Status | `git status && git log --oneline -5` | Always first |
+| Add | `git add path/to/file` | Specific files only |
+| Commit | `git commit -m "type: description"` | Conventional commits |
+| Base branch | `gh repo view --json defaultBranchRef -q .defaultBranchRef.name` | Never assume |
+| Conflict check | `git fetch origin <base> && git merge-tree $(git merge-base HEAD origin/<base>) HEAD origin/<base>` | Exit 0 = clean |
+| Push | `git push -u origin HEAD` | After conflict check |
+| Create PR | `gh pr create --base <base> --title "..." --body "..."` | Always `--base` |
+| PR status | `gh pr view --json mergeable,mergeStateStatus` | CLEAN/BEHIND/DIRTY |
+| Update branch | `git merge origin/<base> --no-edit && git push` | When BEHIND |
+
+## Key Decision Points
+
+### Base Branch Detection
+1. `gh repo view --json defaultBranchRef` (primary)
+2. `gh pr list --limit 1 --json baseRefName` (existing PRs)
+3. Ask user if unclear
+
+### Conflict Resolution
+**Auto-resolve**: Whitespace, non-overlapping imports, independent additions
+**Ask user**: Logic conflicts, 3+ files, unclear which version
+
+### PR Status Actions
+- **CLEAN**: Merge-ready
+- **BEHIND**: `git merge origin/<base> --no-edit && git push`, then re-check
+- **DIRTY**: Resolve conflicts, then re-check
 
 ## PR Body Template
 
@@ -135,9 +105,8 @@ EOF
 - Bullet list of changes (from commits)
 
 ## Test plan
-- [ ] Unit tests pass
-- [ ] Integration tests pass
-- [ ] Manual testing done
+- [ ] Tests pass
+- [ ] Manual verification done
 ```
 
 ## Common Mistakes
@@ -146,12 +115,24 @@ EOF
 |---------|-----|
 | Omit `--base` flag | Always specify explicitly |
 | `git add -A` blindly | Run `git status` first |
-| Skip conflict check | Always check before push |
+| Skip conflict check before push | Always check before push |
 | Assume base branch | Verify via `gh repo view` |
+| Stop after PR creation | Check status and update branch |
+| Assume merge-ready | Verify mergeStateStatus |
+
+## Rationalization Table
+
+| Excuse | Reality |
+|--------|---------|
+| "PR created, done" | Created ≠ merge-ready. Check status. |
+| "GitHub will notify" | Be proactive. Check now. |
+| "Just pushed, base unchanged" | Base can update anytime. Always check. |
+| "CI will catch it" | CI runs after merge-ready. Verify first. |
+| "Too complex to auto-resolve" | Try auto-resolution first. Ask if fails. |
 
 ## Arguments
 
-Parse `$ARGUMENTS`:
+Supported flags (passed after `/create-pr`):
 - `--base <branch>`: Override base branch detection
 - `--draft`: Create draft PR
 - `--automerge`: Enable auto-merge after creation