Plugin Help — Interactive Command Advisor
Helps users find the right command, skill, or agent for their situation.
Usage
$phx-help # Analyze context, suggest commands
$phx-help how do I debug this? # Route to $phx-investigate
$phx-help add a new feature # Route to $phx-plan -> $phx-work
Arguments
$ARGUMENTS — optional description of what the user wants to do- Empty = analyze current context (git status, existing plans, file patterns)
Execution Flow
Step 1: Gather Context
If $ARGUMENTS is non-empty, use it as primary signal.
Always gather ambient context (run in parallel):
- Check for existing plans: use Glob on
.claude/plans/*/plan.md — active work in progress?
- Check git status: uncommitted changes? which files?
- Check for solution docs: use Glob on
.claude/solutions/**/*.md — prior knowledge?
Step 2: Classify Intent
Read references/tool-catalog.md for the full routing table.
Map the user's situation to one of these categories:
| Category |
Signals |
Primary Commands |
| Starting out |
No plans, new to plugin |
$phx-intro |
| Ideation |
"explore", "brainstorm", "not sure", "how to approach", "vague idea" |
$phx-brainstorm |
| New feature |
"add", "build", "implement", multi-file |
$phx-plan → $phx-work |
| Quick change |
Single file, <50 lines, "fix typo" |
$phx-quick |
| Bug |
Error, stack trace, "broken", "failing" |
$phx-investigate |
| Review |
"check", "review", PR ready |
$phx-review |
| Performance |
"slow", "N+1", "memory" |
$phx-perf, $ecto-n1-check, $lv-assigns |
| Research |
"how to", "best practice", "evaluate lib" |
$phx-research |
| Resume work |
Existing plan with unchecked tasks |
$phx-work --continue |
| Post-fix |
"that worked", solved a hard bug |
$phx-compound |
| Full cycle |
Large feature, new domain area |
$phx-full |
| Project health |
"audit", "tech debt", "overall quality" |
$phx-audit, $phx-techdebt |
| Dep update audit |
"audit deps", "supply chain", "post-mix deps.update", "review mix.lock PR" |
$phx-deps-audit |
| Manual dep vetting |
"vet this package", "approve dep", "trust ledger", "after $phx-deps-audit findings" |
$phx-deps-vet |
| Deployment |
"deploy", "release", "production" |
$phx-verify then deploy skill |
| Permissions |
"too many prompts", "allow", "permission fatigue" |
$phx-permissions |
| Returning after time off |
"what did I miss", "back from vacation", "catch up", "what changed while I was out" |
/catchup (companion plugin, separate install) |
Step 3: Respond or Clarify
If high confidence (clear match to one category):
Present the recommendation with:
- The command to run (with exact syntax)
- One-line explanation of what it does
- What artifacts it creates (if any)
- Suggested next step after it completes
If medium confidence (2-3 possible matches):
Use AskUserQuestion with the top options, each with a one-line explanation.
If low confidence (vague or no signal):
Ask ONE focused clarifying question. Examples:
- "Are you starting something new or continuing existing work?"
- "Is this a bug fix or a new feature?"
- "How many files do you expect to change?"
Then recommend based on the answer.
Step 4: Offer Follow-up
After recommending, always add:
- "Run
$phx-help anytime to get routing advice"
- If they seem new: "Try
$phx-intro for a full plugin walkthrough"
Iron Laws
- ONE recommendation — don't dump the full catalog, pick the best match
- MAX ONE clarifying question — don't interrogate, make your best guess
- Show exact syntax —
$phx-plan Add user notifications not just "use the plan command"
- Context over keywords — existing plans + git state matter more than word matching
- NEVER block — if user already knows what they want, DO NOT redirect
Integration
- Complements
intent-detection (auto-trigger) with explicit invocation
- References same routing logic but adds interactive clarification
- Can recommend
$phx-intro for onboarding
1---2name: phx-help3description: Recommend the right $phx-* command for planning, review, debug, deploy, or test tasks. Use when "which command", "what should I use", or "how do I". NOT for /help.4---5
6# Plugin Help — Interactive Command Advisor
7
8Helps users find the right command, skill, or agent for their situation.
9
10## Usage
11
12```
13$phx-help # Analyze context, suggest commands
14$phx-help how do I debug this? # Route to $phx-investigate
15$phx-help add a new feature # Route to $phx-plan -> $phx-work
16```
17
18## Arguments
19
20- `$ARGUMENTS` — optional description of what the user wants to do
21- Empty = analyze current context (git status, existing plans, file patterns)
22
23## Execution Flow
24
25### Step 1: Gather Context
26
27If `$ARGUMENTS` is non-empty, use it as primary signal.
28
29Always gather ambient context (run in parallel):
30
311. Check for existing plans: use Glob on `.claude/plans/*/plan.md` — active work in progress?
322. Check git status: uncommitted changes? which files?
333. Check for solution docs: use Glob on `.claude/solutions/**/*.md` — prior knowledge?
34
35### Step 2: Classify Intent
36
37Read `references/tool-catalog.md` for the full routing table.
38
39Map the user's situation to one of these categories:
40
41| Category | Signals | Primary Commands |
42|----------|---------|-----------------|
43| **Starting out** | No plans, new to plugin | `$phx-intro` |
44| **Ideation** | "explore", "brainstorm", "not sure", "how to approach", "vague idea" | `$phx-brainstorm` |
45| **New feature** | "add", "build", "implement", multi-file | `$phx-plan` → `$phx-work` |
46| **Quick change** | Single file, <50 lines, "fix typo" | `$phx-quick` |
47| **Bug** | Error, stack trace, "broken", "failing" | `$phx-investigate` |
48| **Review** | "check", "review", PR ready | `$phx-review` |
49| **Performance** | "slow", "N+1", "memory" | `$phx-perf`, `$ecto-n1-check`, `$lv-assigns` |
50| **Research** | "how to", "best practice", "evaluate lib" | `$phx-research` |
51| **Resume work** | Existing plan with unchecked tasks | `$phx-work --continue` |
52| **Post-fix** | "that worked", solved a hard bug | `$phx-compound` |
53| **Full cycle** | Large feature, new domain area | `$phx-full` |
54| **Project health** | "audit", "tech debt", "overall quality" | `$phx-audit`, `$phx-techdebt` |
55| **Dep update audit** | "audit deps", "supply chain", "post-`mix deps.update`", "review mix.lock PR" | `$phx-deps-audit` |
56| **Manual dep vetting** | "vet this package", "approve dep", "trust ledger", "after $phx-deps-audit findings" | `$phx-deps-vet` |
57| **Deployment** | "deploy", "release", "production" | `$phx-verify` then deploy skill |
58| **Permissions** | "too many prompts", "allow", "permission fatigue" | `$phx-permissions` |
59| **Returning after time off** | "what did I miss", "back from vacation", "catch up", "what changed while I was out" | `/catchup` (companion plugin, separate install) |
60
61### Step 3: Respond or Clarify
62
63**If high confidence** (clear match to one category):
64Present the recommendation with:
65
66- The command to run (with exact syntax)
67- One-line explanation of what it does
68- What artifacts it creates (if any)
69- Suggested next step after it completes
70
71**If medium confidence** (2-3 possible matches):
72Use `AskUserQuestion` with the top options, each with a one-line explanation.
73
74**If low confidence** (vague or no signal):
75Ask ONE focused clarifying question. Examples:
76
77- "Are you starting something new or continuing existing work?"
78- "Is this a bug fix or a new feature?"
79- "How many files do you expect to change?"
80
81Then recommend based on the answer.
82
83### Step 4: Offer Follow-up
84
85After recommending, always add:
86
87- "Run `$phx-help` anytime to get routing advice"
88- If they seem new: "Try `$phx-intro` for a full plugin walkthrough"
89
90## Iron Laws
91
921. **ONE recommendation** — don't dump the full catalog, pick the best match
932. **MAX ONE clarifying question** — don't interrogate, make your best guess
943. **Show exact syntax** — `$phx-plan Add user notifications` not just "use the plan command"
954. **Context over keywords** — existing plans + git state matter more than word matching
965. **NEVER block** — if user already knows what they want, DO NOT redirect
97
98## Integration
99
100- Complements `intent-detection` (auto-trigger) with explicit invocation
101- References same routing logic but adds interactive clarification
102- Can recommend `$phx-intro` for onboarding
majiayu000