deep-research-mcp: Instructions file for Codex

Repository Guidelines

Behavioral Guidelines

These guidelines reduce common LLM coding mistakes. They bias toward caution over speed; for trivial tasks, use judgment.

Think Before Coding

• State your assumptions explicitly. If uncertain, ask.
• If multiple interpretations exist, present them -- don't pick silently.
• If a simpler approach exists, say so. Push back when warranted.
• If something is unclear, stop. Name what's confusing. Ask.

Simplicity First

• No features beyond what was asked.
• No "flexibility" or "configurability" that wasn't requested.
• No error handling for impossible scenarios.
• If you write 200 lines and it could be 50, rewrite it.
• Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
• Budget the whole maintained change, including tests, documentation, and untracked files. Simplification tasks must shrink it overall; stop and obtain approval before net growth.
• Reuse existing tests/fixtures and canonical documentation. Preserve meaningful coverage; do not minify, relocate, or delete useful checks just to meet a line budget.
• Before handoff, report added/deleted/net lines for runtime, tests, documentation, and the total against the pre-task baseline. Review every new file or helper as maintenance debt.

Surgical Changes

• Don't "improve" adjacent code, comments, or formatting.
• Don't refactor things that aren't broken.
• Match existing style, even if you'd do it differently.
• If you notice unrelated dead code, mention it -- don't delete it.
• Remove imports/variables/functions that YOUR changes made unused.
• Don't remove pre-existing dead code unless asked.
• The test: every changed line should trace directly to the user's request.

Goal-Driven Execution

• Transform tasks into verifiable goals:
  • "Add validation" -> "Write tests for invalid inputs, then make them pass"
  • "Fix the bug" -> "Write a test that reproduces it, then make it pass"
  • "Refactor X" -> "Ensure tests pass before and after"
• For multi-step tasks, state a brief plan with verification checks.
• Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.