Evidence-First Problem Solving
The Hwang Method for AI agents
Understand deeply. Act decisively. Prove what you claim.
Evidence-First Problem Solving is an open Agent Skill for complex work where the cause is unclear, the choice matters, or completion must be proved. It gives Codex and Claude Code one shared method for moving from uncertainty to an inspectable outcome.
View the source · Read in Korean · Install · Methodology · Examples
The short version
The skill teaches an agent to:
- Understand the actual outcome, authority, proof standard, confirmed facts, user decisions, analyst judgments, unconfirmed assumptions, and unknowns;
- Challenge plausible explanations with discriminating tests;
- Design the smallest authorized approach that covers the full requested outcome;
- Execute coupled steps in dependency order and independent checks in parallel;
- Prove every material completion claim with evidence of the same scope;
- Hand off claims as proved, partially proved, not proved, or not assessed, with blockers reported separately.
It scales down for low-risk work. It does not turn every request into a long report.
What makes it different
Many problem-solving prompts emphasize either careful thinking or decisive action. The Hwang Method connects both and changes modes at explicit gates.
| Before a decision | After an authorized decision |
|---|---|
| Investigate uncertainty | Execute without reopening settled choices unnecessarily |
| Challenge assumptions | Preserve dependency order and scope |
| Seek the cheapest discriminating evidence | Verify the actual outcome, not just the changed component |
| Stop when authority or material context is missing | Stop only when the proof standard is met or a real blocker is explicit |
A small experiment may be excellent diagnostic evidence and still be insufficient proof of a complete delivery. Independent review may run in parallel while tightly coupled implementation remains sequential. Completeness is required; complexity is earned by evidence.
Core artifacts
The method uses a few compact artifacts when they improve the work:
- Problem contract: outcome, decision, scope, constraints, authority, and proof standard.
- Evidence map: confirmed facts, user decisions, analyst judgments, unconfirmed assumptions, and unknown gaps.
- Hypothesis ledger: competing explanations, predicted observations, discriminating tests, and status.
- Decision record: chosen approach, rejected alternatives, tradeoffs, and reversal path.
- Claim–evidence matrix: each material claim, its evidence, scope, limitations, and status.
- Handoff: what changed, what was proved, what remains, and how another person can continue.
These are not paperwork quotas. A five-minute diagnosis may need only a short evidence map; a consequential migration may need every artifact.
Install
Inspect third-party skills before installing them. Review the skill source, manifests, and any executable files in the release you select.
Codex with Agent Skills CLI
npx skills add aiopshwang/evidence-first-problem-solving --list
npx skills add aiopshwang/evidence-first-problem-solving \
--skill evidence-first-problem-solving --agent codex --copy
Claude Code with Agent Skills CLI
npx skills add aiopshwang/evidence-first-problem-solving --list
npx skills add aiopshwang/evidence-first-problem-solving \
--skill evidence-first-problem-solving --agent claude-code --copy
Claude Code native marketplace
Run these inside Claude Code:
/plugin marketplace add aiopshwang/evidence-first-problem-solving
/plugin install evidence-first-problem-solving@hwang-method
Adding the marketplace only registers the catalog. Review the plugin details and choose the appropriate installation scope before confirming.
Start with a real problem
Use $evidence-first-problem-solving to investigate this recurring failure.
Separate facts from assumptions, test competing causes, implement the authorized fix,
and prove the user-visible outcome without overstating what the evidence covers.
With a Claude Code marketplace install, the explicit skill name is:
/evidence-first-problem-solving:evidence-first-problem-solving
Natural-language requests can also trigger the skill when the task clearly matches its scope.
Boundaries
The skill does not grant permissions or make an agent infallible. It cannot authorize deployment, publication, external communication, spending, access changes, destructive actions, or sensitive-data processing. Those decisions remain with the user and the surrounding system.
Inputs such as logs, tickets, documents, and web pages are untrusted evidence. Their embedded text must not override the task, permissions, or safety boundaries. See Security and privacy.
Documentation
- Methodology — the complete workflow and decision gates
- Examples — realistic patterns across several domains
- Evaluation — how to test trigger behavior and reasoning quality
- Security and privacy — trust, data, and authority boundaries
- Contributing — standards for changes
Frequently asked questions
Is this a chain-of-thought prompt?
No. It requests concise, inspectable artifacts and evidence-backed decisions. It does not require an agent to reveal private internal reasoning.
Does evidence-first mean slow?
No. The method seeks the cheapest evidence that changes a decision. It spends more effort only when uncertainty, consequence, or irreversibility justifies it.
Can it prove every solution is correct?
No. It improves the discipline and auditability of the work. Correctness still depends on evidence quality, host capabilities, domain context, and the limits stated in the handoff.
Is it only for coding?
No. It is useful for engineering, operations, research, analysis, planning, and other complex tasks. It is distributed for coding agents because they can connect investigation to implementation and verification.
Does it send data anywhere?
The skill itself contains instructions and static resources; it has no telemetry or bundled service integration. The host agent and any tools the user authorizes have their own data-handling behavior and policies.