best-practices
Best Practices
Two-Phase Rule
- Phase 1: Research. Dispatch find-docs and/or WebSearch queries.
- Phase 2: Synthesize and act. 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.
Red flags indicating you are about to skip 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
More from vinta/hal-9000
commit
Use when making any git commit. Always pass a brief description of what changed as the argument.
73update-allowed-tools
Use when creating or editing a skill that uses Bash commands, external tools, or skill invocations and the allowed-tools frontmatter may be incomplete
49sync-skills
(hal-9000) Use when a skill in skills/ has its name or description changed, or is added or removed — syncs README.md, settings.json, and hal_dotfiles.json
46magi
Use when brainstorming ideas, features, or directions for a project where independent perspectives from different model families (Claude/Codex/Gemini) would surface blind spots and spark creative options the user hasn't considered — especially "what cool things can I add", "what should I build next", "give me ideas for X
44second-opinions
Use when wanting independent perspectives from external models (Codex, Gemini) on code, plans, docs, or any task — or when the user asks for a second opinion, codex review, or gemini review
38explore-codebase
Use when navigating unfamiliar code, tracing call flows or symbol definitions, finding files by name or pattern, or locating all references before refactoring
35