best-practices · diff
git:20260916.99bc966 to git:20260923.16c363b
12 added, 12 removed. Audit A to A.
---
name: best-practices
description: Use when about to choose, configure, or refine a tool, library, config format, API pattern, or project setup, or before proposing a design of your own — research current guidance, pitfalls, and prior art first; already knowing an approach, or assuming no prior art exists, is not an exemption. Also use when the user asks about best practices, gotchas, or recommended patterns
user-invocable: true
allowed-tools:
- WebSearch
- WebFetch
- Bash(ctx7:*)
- Bash(npx ctx7:*)
- Bash(npx ctx7@latest:*)
---
# Best Practices
Answer two questions from current sources: **what's the recommended way**, and **what bites people** (the gotchas and pitfalls around it). A how-to without its pitfalls is half an answer.
## Two-Phase Rule
- **Phase 1: Research.** Dispatch `find-docs` and/or web search queries.
- **Phase 2: Synthesize and act.** Starts only after Phase 1 results arrive.
The user's argument may be a question or an imperative. Imperatives ("refine X", "set up Y") determine what Phase 2 does, not whether Phase 1 happens. Phase 1 always runs.
**Rationalizations that precede skipped research:**
| Thought | Reality |
| ------------------------- | -------------------------------------------------------------------------------------- |
| "I already know this" | Training data goes stale. Config keys get renamed, APIs get deprecated. |
| "The user said to act" | The imperative scopes Phase 2, it does not eliminate Phase 1. |
| "This is a simple lookup" | A 30-second search costs nothing. A wrong recommendation costs a debugging round-trip. |
## Workflow
### 1. Identify Research Targets
Break the topic into 2-4 specific queries. Dedicate at least one query to pitfalls ("common mistakes with X", "X gotchas in production"): pitfalls live in issue threads, migration guides, and post-mortems, not in getting-started docs, so a how-to query won't surface them. For design prior-art (the "before proposing a design of your own" trigger), dedicate queries to how existing open source projects implement it — concrete implementations and comparisons, not just advice posts. For single-library lookups, call `find-docs` or web search directly without subagents.
### 2. Parallel Research
Dispatch one subagent per query in a single message so they run in parallel, passing `model: sonnet` on each Agent call so the bulk research stays cheap while orchestration and synthesis keep the session model. Each uses `find-docs` (Context7) and web search. Be concrete in each subagent prompt: pass library names, version constraints, and the user's specific context. Vague prompts produce vague results.
<subagent_prompt_template>
<context>
The user wants to [user's task]. We need the latest, authoritative guidance on [specific aspect].
</context>
<task>
Research best practices for: [specific query]
Use the `find-docs` skill to look up [library/tool] documentation, then use web search to find recent guides and recommendations for "[specific search query]".
</task>
<output_format>
Report:
- 1. Recommended approach with rationale
- 2. Concrete code/config examples
- 3. Every pitfall you found, including ones you are uncertain about or consider minor. Your job is coverage; synthesis will rank and filter. Note each pitfall's consequence (what breaks, what it costs)
- 4. Sources consulted (with publication dates)
+ 1. Recommended approach with rationale.
+ 2. Concrete code/config examples.
+ 3. Every pitfall you found, including ones you are uncertain about or consider minor. Your job is coverage; synthesis will rank and filter. Note each pitfall's consequence (what breaks, what it costs).
+ 4. Sources consulted (with publication dates).
Keep it under 400 words. If space runs short, compress the explanations rather than dropping pitfalls. If you cannot find authoritative guidance on a point, say so explicitly rather than guessing.
</output_format>
</subagent_prompt_template>
### 3. Synthesize
After all subagents return, merge using these criteria:
- 1. **Deduplicate** overlapping recommendations
- 2. **Rank by authority:** official docs > well-known guides > blog posts > training data
- 3. **Flag conflicts** with attribution (which source said what)
- 4. **Discard stale results**: a 2022 guide for a fast-moving framework is noise
+ 1. **Deduplicate** overlapping recommendations.
+ 2. **Rank by authority:** official docs > well-known guides > blog posts > training data.
+ 3. **Flag conflicts** with attribution (which source said what).
+ 4. **Discard stale results**: a 2022 guide for a fast-moving framework is noise.
If a subagent failed or returned empty, note the gap and proceed with the results you have. Do not block synthesis waiting for a straggler.
### 4. Present Findings
Deliver to the user in this structure:
- 1. **Recommended Approach**: the primary recommendation with rationale
- 2. **Key Patterns**: concrete code/config examples the user can apply immediately
- 3. **Gotchas & Pitfalls**: cover every recommendation above, not just the primary one. For each: the mistake, its consequence, and how to avoid it
- 4. **Sources**: what was consulted, so the user can dig deeper
+ 1. **Recommended Approach**: the primary recommendation with rationale.
+ 2. **Key Patterns**: concrete code/config examples the user can apply immediately.
+ 3. **Gotchas & Pitfalls**: cover every recommendation above, not just the primary one. For each: the mistake, its consequence, and how to avoid it.
+ 4. **Sources**: what was consulted, so the user can dig deeper.
## Constraints
- **2-4 focused subagents, not more.** Each carries ~20K tokens of startup overhead. Fewer focused queries beat many shallow ones.
- **User-provided URLs are additive.** If the user provided specific URLs, fetch those too, but they supplement research, not replace it.
- **Context7 quota limits exist.** If `find-docs` fails with quota errors, fall back to web search only and note the limitation.
- If both `find-docs` and web search fail, say so explicitly rather than falling back to training data.