think-before-coding

## Overview

AI agents default to writing code immediately — even when the request is ambiguous, the context is incomplete, or multiple valid interpretations exist. This skill forces a deliberate thinking phase before any implementation begins.

The result: fewer rewrites, fewer wrong-direction implementations, and fewer "I assumed X" surprises.

## When to Use

Activate this skill **before writing any code** when:
- The request is ambiguous or underspecified
- Multiple valid implementations exist
- You are unsure about an existing system's constraints
- The task touches security, data integrity, or public APIs
- You feel the urge to "just start coding" to make progress

## Process

### Phase 1: Understand the Request

1. **Read the full request** — Do not skim. Re-read once.
2. **Identify ambiguities** — List every decision you would have to make silently:
   - What counts as "success"?
   - What are the inputs and expected outputs?
   - What should NOT change?
   - Are there existing patterns to follow?
3. **Surface assumptions** — Write them out: *"I am assuming X because Y."*
4. **Check for contradictions** — Does the request contradict itself or existing code?

**Verify:** Can you state the goal in one clear sentence? If not, ask before proceeding.

### Phase 2: Clarify Before Acting

5. If **genuinely ambiguous**, ask a focused clarifying question — not a list of 10 questions. Pick the one blocker.
6. If multiple valid approaches exist, **present 2–3 options with tradeoffs**, then ask which to proceed with.
7. If something seems wrong with the request, **say so directly** — don't silently work around it.

**Verify:** You have a clear, agreed-upon interpretation of the task.

### Phase 3: State Your Plan

8. Before writing code, state:
   - What you will build
   - What you will NOT touch
   - What success looks like (your verification criteria)
9. For multi-step tasks, write a brief plan:
   ```
   1. [Step] → verify: [check]
   2. [Step] → verify: [check]
   3. [Step] → verify: [check]
   ```

**Verify:** The plan is agreed upon, or you have received approval to proceed.

### Phase 4: Code

10. Now write the code — following the plan exactly.

## Common Rationalizations (and Rebuttals)

| Excuse | Rebuttal |
|--------|----------|
| "I'll figure it out as I go" | Unknown unknowns compound. 5 minutes of thinking saves 50 minutes of rewriting. |
| "The request is clear enough" | If you can't state the goal in one sentence, it's not clear enough. |
| "Asking questions slows things down" | Wrong direction is infinitely slower than a 30-second clarifying question. |
| "I'll handle edge cases later" | Edge cases not considered upfront become bugs found in production. |
| "I can always refactor" | You almost never will. Design now. |

## Red Flags

- You're already writing code and you haven't stated what success looks like
- You made a silent assumption about what the user wants
- You chose between two approaches without mentioning the tradeoff
- You're solving a problem the user didn't ask about
- You're 100 lines in and realize you misunderstood the goal

## Verification

Before leaving this phase, confirm:
- [ ] The goal is stated in one clear sentence
- [ ] All major assumptions are explicitly named
- [ ] Ambiguities are resolved (or flagged for the user)
- [ ] A brief plan exists with verification criteria per step
- [ ] You know what you will NOT touch

## References

- [Andrej Karpathy on LLM coding pitfalls](https://x.com/karpathy/status/2015883857489522876)
- [goal-driven-execution skill](../goal-driven-execution/SKILL.md)
- [idea-to-spec skill](../idea-to-spec/SKILL.md)