best-practices

# 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 WebSearch 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'...