falsify-the-problem

falsify-the-problem — An Agent Skill for Problem Framing

English | 简体中文

Project website

Stop solving the wrong problem faster.

An open-source Agent Skill for problem framing and assumption testing across coding, debugging, architecture, scientific research, and product decisions. It asks Are we solving the right problem? before proposing solutions. Start with installation and a first invocation.

Illustrative scenarios, not production incidents or measured results:

One Markdown file. No dependency, API key, server, or database. The distinctive focus is a falsifiable framing, materially different alternatives, one primary discriminating test per investigation round, evidence updates, and an explicit handoff before solution design. KEEP is a successful result.

Installation

The complete runtime artifact is SKILL.md. Evaluation files are development materials, not dependencies. The skill itself needs no package, API key, or service; your host agent has its own setup requirements.

Codex: choose an installation scope

Codex is one way to use this cross-domain skill. According to the official skills documentation, local skills can live in either of these locations:

Choose one scope. Run the commands below in a terminal, not in the Codex prompt. Git must be installed. Project commands start in the root of the project where you want to use the skill; user commands can start in any directory. These commands clone into a new folder and will fail if the destination is already populated. Keep an existing installation instead of overwriting it.

Windows PowerShell, project scope:

New-Item -ItemType Directory -Force -Path .agents/skills | Out-Null
git clone https://github.com/ordinary-s/falsify-the-problem.git .agents/skills/falsify-the-problem

Windows PowerShell, user scope:

$skillRoot = Join-Path $env:USERPROFILE '.agents/skills'
New-Item -ItemType Directory -Force -Path $skillRoot | Out-Null
git clone https://github.com/ordinary-s/falsify-the-problem.git (Join-Path $skillRoot 'falsify-the-problem')

macOS / Linux, Bash or Zsh, project scope:

mkdir -p .agents/skills
git clone https://github.com/ordinary-s/falsify-the-problem.git .agents/skills/falsify-the-problem

macOS / Linux, Bash or Zsh, user scope:

mkdir -p "$HOME/.agents/skills"
git clone https://github.com/ordinary-s/falsify-the-problem.git "$HOME/.agents/skills/falsify-the-problem"

Alternatively, download or clone this repository elsewhere and copy only SKILL.md into the chosen falsify-the-problem folder. Codex detects skill changes automatically; restart it if the skill does not appear. In Codex CLI or the IDE extension, use /skills or type $ to select the skill.

First invocation in Codex CLI or the IDE extension

Paste this into the Codex prompt, not PowerShell or a shell:

$falsify-the-problem
Our API has become slower and we are considering a cache.
Inspect the available evidence, distinguish observations from assumptions,
and test the problem framing before proposing a solution.

The local setup commands do not establish skill activation or model behavior. macOS and Linux installation and cross-host behavior have not been verified in this documentation change. See Usage for ordinary-language examples.

Other hosts

1. Download or clone this repository into a local falsify-the-problem folder.
2. For a host with skill-folder support, place the folder containing SKILL.md in that host's documented skill location and use its normal reload/discovery procedure. You can copy just SKILL.md into a folder of the same name.
3. For a host that accepts reusable Markdown instructions, attach or load the complete SKILL.md and explicitly request its use before solving the task.

Paths, discovery, invocation syntax, and tool permissions are host-specific. The skill is designed to be portable across agents that support reusable Markdown instructions or skill-like workflows; identical behavior across hosts is not guaranteed.

Why

A requested solution often contains an untested definition of the problem. Optimizing that solution can make the wrong investigation expensive. This skill exposes the definition and seeks cheap evidence that could overturn it. It is useful across coding, debugging, architecture, research, and product work. The protocol stays the same across domains.

How it works

1. Preserve observations and their provenance; separate interpretation, causal hypothesis, problem formulation, and proposed solution.
2. Identify the current formulation and plausible, materially different alternatives.
3. Find load-bearing assumptions and derive distinct observable predictions.
4. Select one Primary Discriminating Test per round, balancing information against cost, risk, and time. Inspect available, permitted, cheap evidence directly.
5. Strengthen, weaken, kill, or merge candidates from the result. Investigate again when another discriminating observation is worth its cost.
6. Stop with an overall verdict and return control to the host agent.

Before choosing the Primary Discriminating Test, the skill checks whether all live formulations share the same consequential, untested frame. It may add one grounded outside-frame challenger; unexplained evidence can reopen that check. Output defaults to compact Fast / Normal / Deep paths, with later turns showing only changed evidence and decisions.

BYPASS is an activation decision, not a verdict. KILL does not imply a known replacement. After REFORMULATE, the host can validate the replacement in a brief new pass using existing evidence, obtain KEEP, and continue within task scope.

STOP solutioning does not mean STOP investigating. Skill STOP does not mean Host Agent STOP. After KEEP, a host already authorized to implement can proceed in the same turn without asking for permission again. No new authority is granted.

Quick example

User: "API P99 increased from 300 ms to 2.8 s. Add Redis."

• Observation: user-reported latency increase;