suggest-best-practice

Suggest Practice

Accept any natural language input, auto-classify it to the relevant domain(s), and either apply the best-matching skill directly or present a ranked list for the user to choose from.

Why This Is Best Practice

Adopted by: Zero-knowledge entry points are standard in expert systems and recommendation engines — Google Search auto-classifies queries without requiring users to specify intent type, Spotify Discover Weekly infers genres from listening behavior without requiring genre tags, and Wolfram Alpha auto-routes computations to the correct solver domain without user specification. Impact: Requiring users to know the domain before getting help is the primary barrier to knowledge system adoption. Studies on expert system usability (Prerau, 1990) found that systems requiring users to pre-classify their problems had 3–5× lower adoption than systems that accepted natural language and routed automatically. Why best: A single entry point — vs. domain-specific skills that require users to already know which domain and practice applies to their situation — eliminates the "which skill do I use?" confusion. Users don't need to pre-classify their problem; suggest-best-practice infers domain and intent automatically.

Sources: Prerau (1990) expert system usability research, Nielsen Norman Group search UX guidelines, Google Search intent classification research

Steps

Step 0: Check preferences (silent)

Resolution order — first match wins:

1. Session memory — pinned this session only; not written to disk (highest precedence)
2. <project-root>/.grimoire/preferences.md — project-level
3. ~/.config/grimoire/preferences.md OR ~/.grimoire/preferences.md — global-level
4. CLAUDE.md ## Grimoire Preferences section — legacy fallback

For the relevant domain, check if a practice is already pinned:

• Pinned match (file) → apply the pinned practice directly; skip scoring entirely. No further action needed — already persisted.
• Pinned match (session) → apply the pinned practice directly; skip scoring. After applying, offer once per session per domain using a platform-aware confirm: "Save [practice] for future sessions?" (Claude Code/OpenCode: AskUserQuestion; Gemini CLI: ask_user type: confirm; other: [y/n]). If yes, invoke pin-best-practice-preference.
• Pinned conflict → warn before suggesting an alternative using a platform-aware confirm: "You have [X] pinned for [domain]. Suggest changing it?" (Claude Code/OpenCode: AskUserQuestion; Gemini CLI: ask_user type: confirm; other: [y/n]).
• No pin → proceed to Step 1.

1. Extract intent signals (no clarifying questions yet)

From the user's input, silently identify:

Signal	Extract
Goal	What outcome does the user want?
Symptoms	What problems are they experiencing?
Domain cues	Industry, role, tool names, context words
Constraints	Time pressure, team size, resources, urgency
Problem type	Prevention / diagnosis / optimization / compliance / learning

Do not ask the user for any of this — infer it from what they wrote.

Problem clarity check: After extracting signals, apply skill judgment: can a 1-2 sentence problem statement be written from what the user said? A problem is clear enough to proceed if:

• Goal is inferable (what outcome they want)
• At least the broad scope is known (what domain or area this is in)
• What's described is a root cause or problem, not just a symptom with no surrounding context

If NOT clear enough → invoke analyze-best-practice-problem before scoring. Use the problem statement from its output as input to Step 2. If clear enough → proceed to Step 2.

2. Score candidate skills

For each skill in the installed grimoire domains:

score = (tag_overlap × 2) + (description_match × 3) + (domain_plausibility × 1)

• tag_overlap: count of skill tags matching extracted keywords (normalized 0–1)
• description_match: does Use when... describe this situation? (0 = no, 1 = yes)
• domain_plausibility: is this domain plausible given context cues? (0 = no, 0.5 = possible, 1 = likely)

Normalize final scores to 0–1.

3. Route by confidence

Existing solution — user describes something they already built, planned, or decided and wants evaluation ("is this good?", "what am I missing?", "does this follow best practices?"):

Delegate to review-best-practice-fit. Announce:

You have an existing solution. Applying review-best-practice-fit to evaluate it against best practices...

Multi-domain — user has a new problem that spans 3+ domains and requires applying ALL of them (not just one):

Delegate to plan-best-practice-solution. Announce:

Your situation spans multiple domains and requires coordinating several best practices.
Applying plan-best-practice-solution to build a sequenced action plan...

Sole clear match — exactly one skill scores ≥ 0.7 AND second-place score < 0.4:

Load and apply the skill directly. Announce before applying:

Situation matches: [skill-name] ([domain/subdomain])
Applying now...

Multiple matches — 2+ skills score ≥ 0.4 (regardless of whether the top score reaches 0.7):

Present a ranked list with recommendation and wait for user selection:

Multiple best practices apply. Recommended: [top-skill-name]

1. ★ [top-skill-name] — [one sentence: what problem it solves]  ← recommended
   Domain: [domain/subdomain]  |  Score: [score]  |  Install: /plugin install grimoire-[subdomain]@grimoire

2. [skill-name] — [one sentence: what problem it solves]
   Domain: [domain/subdomain]  |  Score: [score]  |  Install: /plugin install grimoire-[subdomain]@grimoire

3. [skill-name] — [one sentence]
   Domain: [domain/subdomain]  |  Score: [score]  |  Install: ...

Then collect the user's choice using the best available method for your platform:

• Claude Code / OpenCode: use AskUserQuestion / question — ★ recommended first with "(Recommended)" appended, include "Apply all in sequence" and "Skip" as last two options, multiSelect: false
• Gemini CLI: use ask_user — type: "select", same options including "Apply all in sequence" and "Skip"
• All other platforms: numbered list:

  Which would you like to apply? (Enter number, "all" to apply in sequence, or "skip" to proceed without)
  

The ★ recommendation is the highest-scoring match. If two skills score equally, recommend the one whose Use when... description is the closest literal match to the user's input.

After user selects, load and apply the chosen skill.

Browse mode — user explicitly says "show me options", "what practices exist for X", or "what should I know about Y" without wanting to act yet:

Present the ranked list only, do not apply any skill:

Best practices for: [topic]

1. [skill-name] — [one sentence: what it solves]
   Domain: [domain/subdomain]  |  Install: /plugin install grimoire-[subdomain]@grimoire

2. ...

After listing, collect the user's choice using the best available method for your platform:

• Claude Code / OpenCode: use AskUserQuestion / question — list all skills as options (no ★ in browse mode), multiSelect: false
• Gemini CLI: use ask_user — type: "select", list all skills as options
• All other platforms: "Say the number or skill name to apply one."

No match — all skills score < 0.3:

State clearly that no skills currently cover this area, then ask ONE targeted clarifying question to narrow the domain:

No installed skills match this situation closely.
[One clarifying question to narrow the domain — e.g., "Is this about your code, your health, your finances, or something else?"]

4. Apply the matched skill

Load the skill using the Skill tool and follow its steps exactly.

5. Check for cross-domain coverage

After applying the primary skill, check: does the user's situation span additional domains with independent high-confidence matches?

• 1 additional domain: ask once: "This situation also touches [domain] — [skill-name] applies to that aspect. Want me to apply it?"
• 2+ additional domains: delegate to plan-best-practice-solution — "This situation spans multiple domains. Want me to build a full solution plan?"

Do not chain more than 2 skills without user confirmation. If 3+ skills are needed, use plan-best-practice-solution.

Rules

• Never ask the user which domain their problem belongs to — that's the skill's job to figure out
• Auto-apply only when exactly 1 skill ≥ 0.7 AND second place < 0.4 — truly unambiguous
• Whenever 2+ skills score ≥ 0.4, always list with recommendation — never silently pick one
• Always mark the recommended option with ★
• Max 5 options in a ranked list; drop lower-scoring matches beyond 5
• Never hallucinate skill names — only reference skills that exist in installed domains
• Announce the matched skill before applying — don't silently load skills
• If a skill is not installed, include the install command in the suggestion

Examples

Example 1 — High confidence, single domain

"My pull requests keep getting rejected in code review"

Extract: goal=pass-review, symptoms=PR-rejection, domain-cues=code/pull-request/review Top match: code-review (engineering/development) — score 0.82 → Apply directly: "Situation matches: code-review (engineering/development). Applying now..."

---

Example 2 — Multiple matches

"I always feel exhausted after training"

Extract: goal=recover-better, symptoms=fatigue/exhaustion, domain-cues=training/workout Top matches (similar scores):

1. optimize-recovery (health/fitness) — 0.61
2. calculate-macros (health/nutrition) — 0.54
3. design-training-program (health/fitness) — 0.49 → Present ranked list, wait for user selection

---

Example 3 — No match, clarifying question

"I don't know what to do with my life"

Extract: goal=unclear, symptoms=directionlessness, domain-cues=none All scores < 0.3 → "No installed skills closely match this. Is this about your career, your health, your finances, or something else?"

Common Mistakes

Asking the user to classify their own problem: "Is this an engineering problem or a business problem?" — never do this. Route silently, present choices only when genuinely ambiguous.

Over-confident routing: applying a skill when the top score is 0.5 with a close second-place match. Present choices when it's close.

Applying too many skills: chaining 3+ skills without confirmation overwhelms the user. One at a time, ask before adding the second domain.

Hallucinating skills: if no skill exists for the situation, say so. Don't invent skill names.