research-before-code

name	research-before-code
description	Use when a bug involves platform/OS behavior, third-party service quirks, or any issue where the root cause is outside your codebase. Also use when 3+ fix attempts have failed without understanding why. Triggers on fullscreen, window level, permissions, sandbox, codesign, notarization, OS-specific behavior, Linux window manager behavior, Windows API quirks, Electron/Tauri platform APIs, browser compatibility issues, or any "works on my machine" cross-OS scenario.
version	1.0.0
scope	public

Research Before Code

Overview

When a bug is in platform/OS behavior (not your code logic), the code-test loop is a trap. Each attempt feels productive but you're guessing without understanding.

Core principle: For platform behavior bugs, exhaust research BEFORE writing any code. One hour of reading Apple docs beats five hours of trial-and-error.

Relationship to systematic-debugging: This skill is Phase 0 — it determines WHETHER you should enter code-level debugging or research-level investigation first.

When to Use

digraph classify {
  "Bug encountered" -> "Where is the problem?";
  "Where is the problem?" -> "systematic-debugging" [label="your code"];
  "Where is the problem?" -> "THIS SKILL" [label="platform/OS/external"];
  "Where is the problem?" -> "isolate first" [label="unknown"];
  "isolate first" -> "systematic-debugging" [label="confirmed: your code"];
  "isolate first" -> "THIS SKILL" [label="confirmed: platform"];
}

Platform behavior bugs look like:

• OS does something unexpected (windows, permissions, sandboxing)
• Behavior varies by OS version
• Apple/Microsoft docs are incomplete or contradictory
• Stack Overflow answers are 5+ years old
• "Works on my machine" across OS versions
• Framework (Tauri, Electron) abstracts the underlying API

The guess loop signal — STOP if you notice:

• Tried 3+ approaches without understanding WHY each failed
• Each attempt is a variation of the same idea (e.g., different window levels)
• You can explain what your code does but not what the OS does
• You're reading your code more than platform documentation

The Process

Step 1: Classify (2 min)

Type	Signal	Strategy
Code logic error	Stack trace points to your code	systematic-debugging
Platform API misuse	Docs say X, you did Y	Read docs, fix call
Platform behavior unknown	Docs don't explain, or behavior contradicts docs	Research first
Unknown	Can't tell yet	Build minimal repro to isolate

Step 2: Research (no code changes)

Answer these questions before touching any code:

1. What does the platform document about this behavior?

   • Official docs (Apple Developer, MSDN)
   • WWDC sessions, technical notes
   • Release notes for relevant OS versions

2. What are the known limitations?

   • Is this a documented limitation?
   • Did behavior change between OS versions?
   • Are there known workarounds in official docs?

3. How do other apps solve this?

   • Find open-source apps with the same requirement
   • Read their implementation, not just their README
   • Check their issue trackers for the same problem

4. Does the framework interfere?

   • What does Tauri/Electron/etc. do under the hood?
   • Does it set conflicting flags or override your settings?
   • Read framework source code for the relevant API

5. Is it possible at all?

   • Some things require entitlements, private APIs, or are simply impossible
   • Better to know this at minute 10 than hour 5

Output: A list of possible approaches ranked by confidence, with sources.

Step 3: Assess Feasibility

Research conclusion	Next step
Clear documented solution	Implement with confidence
Multiple approaches, unclear winner	Build minimal prototype to test ONLY the platform behavior (not your full app)
Confirmed impossible without private API	Design workaround, accept limitation, or evaluate private API tradeoffs
Confirmed impossible, period	Stop. Document. Move on.

Step 4: Implement (only now)

With a validated approach, implement in your actual codebase.

Quick Reference

Bug in platform behavior?
  │
  ├─ YES ──→ RESEARCH (no code) ──→ FEASIBILITY ──→ IMPLEMENT
  │            │                       │
  │            │ Questions:             │ Outcomes:
  │            │ 1. What do docs say?   │ A. Clear solution → code
  │            │ 2. Known limits?       │ B. Uncertain → prototype
  │            │ 3. How do others do?   │ C. Impossible → workaround
  │            │ 4. Framework conflict? │ D. Impossible → stop
  │            │ 5. Possible at all?    │
  │            │                       │
  │
  └─ NO ───→ systematic-debugging (trace root cause in your code)

Common Mistakes

Mistake	Why it happens	Fix
"Let me just try one thing"	Feels faster than reading	It's not. One attempt = 10 min build+test. Research = 5 min reading.
Assuming platform constants	"kCGStatusWindowLevel is 25"	Verify from official headers, not memory or Stack Overflow
Reading your code instead of platform docs	Comfort zone	Your code is fine. The platform is the unknown.
Trying framework workarounds before understanding the OS	Framework is familiar	Framework wraps OS. Understand OS first.
Committing "best effort" without understanding	Sunk cost	If you don't know why it works (or doesn't), you'll revisit it.