# How to Identify and Surface Hidden Assumptions Before Implementing

> Learn to identify and surface hidden assumptions before implementing. Convert implicit models into clear requirements to prevent coding errors. Improve your development process.

- Repository: [Jiayuan Zhang/andrej-karpathy-skills](https://github.com/forrestchang/andrej-karpathy-skills)
- Tags: best-practices
- Published: 2026-04-08

---

**Explicitly surfacing hidden assumptions before writing code prevents implementation errors by converting implicit mental models into verifiable, discussable requirements.**

Identifying and surfacing hidden assumptions before implementing is a discipline that transforms ambiguous requirements into precise specifications. The `forrestchang/andrej-karpathy-skills` repository codifies this approach through the **"Think Before Coding"** principle, providing a structured framework for LLMs and developers to validate their understanding prior to generating any implementation.

## The Core Principle: Think Before Coding

The central thesis of the repository is that **hidden assumptions are the primary source of implementation defects**. When developers (or AI models) proceed with unstated presumptions about input formats, API schemas, or error-handling policies, they inevitably build software that fails at integration time.

The "Think Before Coding" guideline requires four concrete actions before any code is written: state every known fact, list every unknown as a question, present alternatives without choosing, and stop to ask for clarification when confused. This process forces explicit verification of requirements rather than implicit guesswork.

## Where the Guidelines Live

The repository maintains this principle across three synchronized files to ensure consistent application across different consumption contexts.

### [`skills/karpathy-guidelines/SKILL.md`](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/skills/karpathy-guidelines/SKILL.md)

The **primary definition** of the principle lives in [`SKILL.md`](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/SKILL.md), which enumerates the actionable checklist for surfacing assumptions. This file serves as the single source of truth for the behavioral guideline and defines the exact phrasing used to trigger verification loops【SKILL.md】.

### [`README.md`](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/README.md)

The repository’s [`README.md`](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/README.md) expands the technical directive into a human-readable philosophy, explaining why unstated assumptions degrade code quality and how the surfacing process improves maintainability【README.md】.

### [`CLAUDE.md`](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/CLAUDE.md)

The same guidance appears in [`CLAUDE.md`](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/CLAUDE.md), packaged specifically for the Claude Code plugin. This ensures that any project installing the plugin inherits the "Think Before Coding" constraint automatically【CLAUDE.md】.

## Architectural Rationale

The repository’s structure reflects three deliberate design decisions that reinforce assumption-surfacing behavior.

### Single Source of Truth

All three files reference identical phrasing derived from [`SKILL.md`](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/SKILL.md). By maintaining the rule in one location and replicating it to [`README.md`](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/README.md) and [`CLAUDE.md`](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/CLAUDE.md), the repository eliminates documentation drift and guarantees that every consumer (human or model) receives the same guidance.

### Guidelines as Data, Not Code

The repository contains **no executable code**. The behavioral constraints are pure data in markdown files, preventing accidental execution of assumptions and making the repository safe to import as a plugin without side effects.

### Loop-Ready Wording

Each guideline ends with a concrete verification step (e.g., *"If something is unclear, stop. Name what’s confusing and ask"*). This phrasing enables an explicit confirmation loop where the system checks assumptions and awaits validation before proceeding to implementation.

## Practical Implementation Steps

To identify and surface hidden assumptions before implementing, follow this four-step protocol:

1. **Enumerate what you know** – List every input, output, side-effect, and environment requirement you can verify with certainty.
2. **Highlight the unknowns** – Convert any item that lacks 100% verification into an explicit question.
3. **Present alternatives** – When a requirement admits multiple implementations (e.g., synchronous versus asynchronous processing), list the options without selecting one.
4. **Pause for confirmation** – State the uncertainty explicitly (e.g., *"I’m uncertain about X; should I proceed with Y or Z?"*) and suspend implementation until receiving clarification.

This protocol transforms implicit mental models into explicit, discussable items, preventing the "running along" phenomenon where code is built atop faulty premises.

## Code Examples in Practice

The following examples illustrate how to embed assumption-surfacing into your development workflow.

### Function Scaffold with Assumption Checklist

```python
def fetch_user_profile(user_id: str) -> dict:
    """
    Assumptions:
    • `user_id` is a UUID string (validated elsewhere?)
    • The remote API returns JSON with keys `name`, `email`
    • Network errors should be retried up to 3 times
    """
    # TODO: Ask for clarification on the above assumptions before implementing.

    raise NotImplementedError

```

Before removing the `NotImplementedError`, ask stakeholders: *"Is `user_id` always a validated UUID? Should we perform validation here? What should we do if the API schema changes?"*

### CLI Tool with Interactive Confirmation

```bash
#!/usr/bin/env bash

# hidden-assumptions.sh

# 1. Assume the user has `jq` installed.

# 2. Assume input JSON follows the same schema as the upstream service.

# 3. Assume the output file path is writable.

read -p "Do you confirm that jq is installed and reachable? (y/n) " jq_ok
if [[ "$jq_ok" != "y" ]]; then
  echo "Please install jq before proceeding."
  exit 1
fi

# Proceed with processing...

```

This script explicitly requires the operator to confirm each hidden assumption, aborting if any verification fails.

### Reusable Markdown Template

```markdown
<!-- karpathy-assumptions.md -->
**Assumptions before coding**

- State every known fact.
- List every unknown as a question.
- Offer alternatives without choosing.
- Stop and ask if anything is unclear.

```

Copy this block into issues, pull requests, or design documents to enforce the practice across team workflows.

## Summary

- **Identify hidden assumptions** by enumerating known facts and explicitly labeling uncertainties before writing code.
- **Surface assumptions** using the "Think Before Coding" principle defined in [`skills/karpathy-guidelines/SKILL.md`](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/skills/karpathy-guidelines/SKILL.md) and propagated through [`README.md`](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/README.md) and [`CLAUDE.md`](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/CLAUDE.md).
- **Implement verification loops** by presenting alternatives and pausing for stakeholder confirmation when requirements are ambiguous.
- **Use scaffold templates** with embedded assumption checklists to prevent premature implementation in functions, CLI tools, and documentation.

## Frequently Asked Questions

### What constitutes a hidden assumption in software development?

A hidden assumption is any unstated belief about system behavior, data formats, environment state, or business logic that a developer holds while writing code. Common examples include assuming an API always returns JSON, that a directory path exists, or that input strings are pre-validated. According to the `forrestchang/andrej-karpathy-skills` repository, these assumptions become defects when they conflict with reality during integration.

### Why does the repository contain no executable code?

The repository stores behavioral guidelines as pure data in markdown files rather than executable scripts to prevent accidental execution of unverified assumptions. This design makes the repository safe to import as a Claude Code plugin while ensuring the "Think Before Coding" rules remain readable constraints rather than hidden automation.

### How do I handle assumptions when working alone without stakeholders?

When independent, document each assumption in code comments or design logs with a confidence level (e.g., *"Assuming X with 70% confidence"*). Implement the most conservative alternative that satisfies all assumptions, or add feature flags that allow runtime switching between options when the assumption proves false during testing.

### Can these guidelines apply to non-AI coding workflows?

Yes. While the [`CLAUDE.md`](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/CLAUDE.md) file targets Claude Code integration, the four-step protocol in [`SKILL.md`](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/SKILL.md) functions equally well for human developers. The practice of listing knowns, questioning unknowns, and presenting alternatives before implementing prevents rework regardless of whether the implementer is an LLM or a software engineer.