moicle 2.0.0 → 2.1.0

package/assets/skills/research/web/SKILL.md

@@ -6,18 +6,18 @@ args: "[TOPIC]"
 
 # Research Solutions
 
-Research solutions on the internet for a specific problem — from an explicit topic argument or by analyzing the current conversation context. **Research and propose only — do NOT implement.**
+Research solutions on the web for a specific problem. Output: a written recommendation with sources. **Never implement** — wait for user approval, then hand off to `/feature:new` / `/research:spike`.
 
-**ARGUMENTS:** (optional) Topic or question to research. If omitted, analyze the current conversation (recent messages, IDE selection, task at hand) to determine what to research.
+**ARGUMENTS:** (optional) topic to research. If omitted, infer from current conversation context.
 
 ## When to use this skill
 
 - ✅ You don't know the right solution / library / pattern yet
 - ✅ Need to compare multiple approaches before committing
-- ✅ Stack / framework changed and best practices may have shifted
-- ❌ You already know the approach → use `/feature:new` or `/fix:hotfix`
-- ❌ You want to validate the approach by building → use `/research:spike`
-- ❌ Debugging a known bug → use `/fix:root-cause`
+- ✅ Stack / framework changed, best practices may have shifted
+- ❌ You already know the approach → `/feature:new` or `/fix:hotfix`
+- ❌ Want to validate by building → `/research:spike`
+- ❌ Debugging a known bug → `/fix:root-cause`
 
 ---
 
@@ -29,117 +29,159 @@ IDENTIFY → DETECT STACK → SEARCH → SYNTHESIZE → PROPOSE
 
 ---
 
-## Step 1: Identify what to research
+## Step 1: IDENTIFY
 
-### Mode 1 — Argument provided
-- Use the argument directly as the topic
-- If too broad, narrow it down using project context (stack, architecture, current task) BEFORE searching
+### Mode 1 — argument provided
+- Use the argument as the topic
+- If too broad, narrow using project context **before** any search
 
-### Mode 2 — No argument
-- Analyze the current conversation: recent messages, IDE file selection, active task
-- Identify: what is the user doing, what problem they hit, what solution they need
-- **Summarize the problem back to the user and get confirmation** before burning search budget
+### Mode 2 — no argument
+- Analyze conversation: recent messages, open file, current task
+- **Summarize the problem back to user, get confirmation** before burning search budget
+
+### Research budget guide
+
+| Scope | Budget | When to stop |
+|-------|--------|--------------|
+| Quick lookup (API behavior, error meaning) | 2-3 queries | First authoritative source confirms |
+| Solution comparison (2-3 options) | 5-8 queries | Each option has ≥2 independent sources |
+| Deep dive (new pattern, unfamiliar domain) | 10-15 queries | Recommendation is defensible |
+
+**Hard cap:** if you hit 15 queries without converging → stop, report what's found + ask user to narrow.
 
 ### Gate
-- [ ] Problem statement clear and confirmed (Mode 2)
-- [ ] Scope narrow enough to research in <10 queries
+- [ ] Problem statement confirmed (Mode 2)
+- [ ] Scope narrow enough to fit in budget
+- [ ] Budget agreed (default: 5-8 queries)
 
 ---
 
-## Step 2: Detect project context
+## Step 2: DETECT STACK
 
-Detect the project's tech stack so results can be filtered for relevance.
+Use `~/.claude/architecture/_shared/stack-detection.md` for canonical detection rules.
 
-| File | Stack |
-|------|-------|
-| `go.mod` | Go (note version from `go` directive) |
-| `package.json` | Node.js — inspect dependencies to pick framework (NestJS / Vite+React / Remix / etc.) |
-| `pubspec.yaml` | Flutter / Dart |
-| `composer.json` | PHP / Laravel |
-| `Cargo.toml` | Rust |
-| `pyproject.toml` / `requirements.txt` | Python |
-
-Also check `.claude/architecture/` for the architecture doc in use — this shapes which patterns are idiomatic for the project.
+Capture for filter use:
+- Language + version (e.g., `Go 1.22`, `Node 20`, `Dart 3.4`)
+- Framework + version (e.g., `NestJS 10`, `Vite 5`, `Laravel 11`)
+- Architecture pattern (DDD / hexagonal / etc. — from project's architecture doc)
+- Hard constraints (license, runtime, infra — e.g., "must run on Cloudflare Workers")
 
 ### Gate
 - [ ] Stack + version identified
-- [ ] Architecture context noted (if any)
+- [ ] Architecture context noted
+- [ ] Hard constraints captured
 
 ---
 
-## Step 3: Search the internet
-
-Use **WebSearch** and **WebFetch**.
+## Step 3: SEARCH
 
-### Search strategy
-1. **Broad first** — overview, best practices, common approaches
-2. **Deep dive** — official docs, GitHub issues, Stack Overflow, authoritative blogs
-3. **Compare** — if multiple solutions exist, list pros / cons of each
+### Strategy
+1. **Broad first** — overview, common approaches, "X vs Y" comparisons
+2. **Deep dive** — official docs, GitHub issues, release notes, authoritative blogs
+3. **Counter-search** — actively look for criticism / failure stories of the leading option
 
 ### Source priority
-1. Official documentation
-2. GitHub issues / release notes (quirks, known bugs)
-3. Stack Overflow (accepted answers with high scores)
-4. Authoritative blogs (Anthropic, framework authors, well-known engineers)
-5. Recent > old — prefer last 2 years unless evergreen
+
+| Priority | Source | Weight |
+|----------|--------|--------|
+| 1 | Official docs (current version) | Highest |
+| 2 | GitHub issues / release notes (project itself) | High — for quirks + known bugs |
+| 3 | Stack Overflow accepted answers (high score, recent) | Medium-high |
+| 4 | Authoritative blogs (framework authors, well-known engineers) | Medium |
+| 5 | Tutorials, course material | Low — risk of outdated patterns |
+| 6 | AI-generated content | Skip unless you can verify against #1-#4 |
 
 ### Search tips
-- **Prefer English queries** — richer, more recent results
-- Include library + version when version-sensitive (e.g., `nestjs 10 typeorm migrations`)
-- Cross-validate across at least 2–3 independent sources
-- When sources conflict, prefer most recent + most authoritative; note the conflict
+- **Prefer English queries** — richer index; supplement with framework's primary docs language (e.g., Vietnamese for niche local libs)
+- Include library + version when version-sensitive: `nestjs 10 typeorm migrations`
+- Quote exact error messages
+- Cross-validate ≥2 independent sources before concluding
+
+### When sources conflict
+
+Decision tree:
+1. **Different versions?** → trust the one matching project version
+2. **One is official docs?** → trust official
+3. **Different dates, same authority?** → trust newest, note the change
+4. **Same date, different authority?** → trust higher-authority source per priority table
+5. **Cannot resolve?** → present both, recommend the lower-risk option, explain trade-off
+
+Always **note the conflict** in the report — don't silently pick one side.
 
 ### Gate
-- [ ] At least 2 independent sources for the recommendation
-- [ ] Sources are < 2 years old (or "evergreen" justified)
+- [ ] ≥2 independent sources per option
+- [ ] Sources <2 years old (or evergreen explicitly justified)
+- [ ] Counter-search done for the leading option
 
 ---
 
-## Step 4: Synthesize results
+## Step 4: SYNTHESIZE
 
-Present findings in this format:
+### Comparison matrix (when ≥2 options)
 
 ```markdown
-## Problem
-{Short summary of the problem, with project context — stack, constraints, goal}
+| Criterion | Option A | Option B | Option C |
+|-----------|----------|----------|----------|
+| Maintenance status | active (releases 2025) | last release 2023 | active |
+| License | MIT | Apache-2.0 | BSL (commercial) |
+| Stack fit ({your stack}) | native support | adapter required | native |
+| Performance (cite source) | 8k rps (link) | 5k rps | 12k rps |
+| Operational complexity | low | medium | high |
+| Community size | 25k stars | 8k stars | 2k stars |
+| Known issues | #1234 (workaround exists) | #56 (no fix) | none |
+| Migration cost from current | low | medium | high |
+```
 
-## Solutions Found
+### Report template
 
-### Solution 1: {Name}
-- **Description:** {How it works}
-- **Pros:** {...}
-- **Cons:** {...}
-- **Fit for this project:** {High / Medium / Low — why}
-- **Source:** {link}
+```markdown
+## Problem
+{One paragraph: what we're solving, stack, constraints, goal}
 
-### Solution 2: {Name} (if applicable)
-- ...
+## Options Considered
+{Brief: A, B, C — one line each on what they are}
+
+## Comparison
+{matrix above}
 
 ## Recommendation
-{Which solution fits best and why — reference architecture doc / stack conventions}
+**{Option X}** because {1-2 strongest reasons backed by sources}.
+
+Trade-off: {what we give up by picking X over the runner-up}.
+
+## Pseudo-code (not for direct implementation)
+{Minimal sketch showing how X fits the project — adapt before shipping}
 
-## Code Example (if applicable)
-{Minimal snippet showing the recommended approach, adapted to the project's stack}
+## Caveats
+- {gotcha 1 with source link}
+- {gotcha 2}
 
-## Caveats / Known Issues
-- {Gotcha 1}
-- {Gotcha 2}
+## Conflicts in sources
+- {if any — what disagreed, how it was resolved}
 
 ## References
-- {link 1} — {what this source gave us}
-- {link 2} — {...}
+- {url} — {what this gave us}
+- ...
 ```
 
+### Gate
+- [ ] Recommendation is explicit (don't say "both are fine")
+- [ ] Trade-off named (what's lost by picking the winner)
+- [ ] Every non-trivial claim has a source link
+- [ ] Pseudo-code clearly marked as **not** for direct copy-paste
+
 ---
 
 ## Hard Rules
 
-- **Research and propose — do NOT implement.** Wait for user confirmation before touching code
-- **Consider project context:** stack, architecture, conventions. A solution idiomatic in one project can be wrong in another
-- **Narrow scope when too broad:** if the topic is too wide (e.g., "how to do auth"), ask the user to narrow it
-- **Flag stale answers:** if top answers are 3+ years old and the library has had major versions since, mention it and check release notes
-- **No hallucinated APIs:** if uncertain whether a method / option exists, verify in official docs before recommending
-- **Cite sources:** every non-trivial claim should have a link
+- **Research and propose — do NOT implement.** Wait for user confirmation
+- **Stack context matters** — idiomatic in one project, wrong in another
+- **Narrow when too broad** — "how to do auth" → "JWT refresh flow with NestJS + Passport"
+- **Flag stale answers** — if top result is 3+ years old and lib has major versions since, check release notes
+- **No hallucinated APIs** — verify method / option exists in official docs
+- **Cite every non-trivial claim**
+- **Note conflicts** between sources, don't silently pick
+- **Honor the budget** — 15 queries is the hard cap
 
 ---
 
@@ -147,17 +189,16 @@ Present findings in this format:
 
 | When | Use |
 |------|-----|
-| You want to prototype the chosen approach | `/research:spike` |
-| You already know the approach and want to implement | `/feature:new` / `/fix:hotfix` |
-| You're debugging a known bug (not researching options) | `/fix:root-cause` |
-| You want to write the research up as a design doc | `/docs:write` |
-
----
+| Want to validate the chosen approach by prototyping | `/research:spike` |
+| Already know the approach, ready to build | `/feature:new` / `/fix:hotfix` |
+| Debugging a known bug | `/fix:root-cause` |
+| Write up the research as a design doc / ADR | `/docs:write` |
 
 ## Recommended Agents
 
 | Phase | Agent | Purpose |
 |-------|-------|---------|
-| Search | `@docs-writer` | Frame the research output as a design note |
-| Synthesize | `@api-designer` | If researching API patterns |
-| Synthesize | `@security-audit` | If researching anything auth / crypto / data handling |
+| Search | `@docs-writer` | Frame output as design note |
+| Synthesize (API topics) | `@api-designer` | API pattern depth |
+| Synthesize (auth / crypto / data) | `@security-audit` | Security implications |
+| Synthesize (perf-sensitive) | `@perf-optimizer` | Benchmark interpretation |