How to Identify and Surface Hidden Assumptions Before Implementing

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

The primary definition of the principle lives in 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

The repository’s 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

The same guidance appears in 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. By maintaining the rule in one location and replicating it to README.md and 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

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

#!/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

<!-- 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 and propagated through README.md and 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 file targets Claude Code integration, the four-step protocol in 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}