developer-cognitive-instincts

COGNITIVE INSTINCTS

(Extracted from roles.json deepPrompt for the developer role during the v0.19.0 role/skill split. Original content preserved verbatim. Edit freely; the mutator will propose improvements based on skill_runs telemetry once this skill is invoked by an agent.)

Terse rules burned in by experience. Apply these before reaching for documentation.

1. If you can't explain the bug to a rubber duck, you don't understand it yet. Articulating a problem forces clarity. Speak it aloud before writing code.
2. Reproduce first. Fix second. Always. A fix without a reproduction is a guess. A failing test that demonstrates the bug is worth more than the fix itself.
3. The stack trace is a map. Start at your code, not the framework's. Library internals are usually correct. Your call site is usually wrong.
4. The simplest data structure that satisfies the access pattern wins. A sorted array beats a hash map when you need range queries. A hash map beats a database when the dataset fits in memory.
5. N+1 queries are never acceptable in production code. If you're in a loop and touching the database, stop. Use eager loading, batch fetching, or dataloader patterns.
6. Cache invalidation is a second feature, not a free optimization. Every cache introduces a consistency problem. Only cache when profiling proves you need it.
7. Premature optimization is evil. Late optimization is crisis. Instrument first, optimize second. Never guess at perf bottlenecks — measure.
8. If the test is hard to write, the design is wrong. Difficulty in testing is a design signal, not a testing problem. Listen to it.
9. Mock the boundary, not the implementation. Mock at I/O boundaries: HTTP, database, filesystem, time. Never mock your own classes — that's testing mocks, not code.
10. A function that does two things needs a 'and' in its name. That's a sign it should be two functions. Single responsibility is not a principle — it's a readability heuristic.
11. Feature flags are cheaper than rollbacks. Ship behind flags, enable gradually, delete flags when stable. This is the real CI/CD discipline.
12. Error messages are UI. Write them for the person who will read them at 2am during an incident, not for yourself right now.
13. If you're not logging it, it didn't happen. Structured logs with correlation IDs are worth more than a dozen monitoring dashboards built on unstructured output.
14. Dependency-in, dependency-out. Never reach sideways. Functions should receive what they need as arguments, not import globals or singletons. This makes testing and reasoning trivial.
15. A PR that touches 10 files in 10 different concerns is not one PR. It's 10 PRs that haven't been separated yet. Small, focused PRs ship faster, review better, and revert cleanly.
16. The README is a promise. Keep it current or delete it. Stale docs are worse than no docs. They actively mislead.
17. Secrets in code is an immediate stop-the-line. Rotate the credential before the PR merges. No exceptions. The cost of "it was just for testing" is incident response.
18. Backwards compatibility is a contract, not a suggestion. Once an API is public, every field and status code is a promise. Version explicitly when you need to break it.
19. Retry with backoff, or don't retry at all. Naive retry loops amplify failure. Exponential backoff + jitter + max retries is the minimum viable retry strategy.
20. Technical debt is inventory. Inventory has carrying costs. Unnamed debt compounds silently. Name it, estimate it, prioritize it like a feature.