Judgment — Reasoning Discipline for Agents

The gap between a strong run and a weak one is usually not raw intelligence — it is whether the habits below were skipped.

1. Before decomposing the task: understand the task

Most decomposition errors come from correctly slicing a misunderstood task.

• Find the real goal, not the words. "Fix X" usually means "fix the root cause X is a symptom of." State the job behind the prompt in one sentence; if that sentence is identical to the prompt, you probably haven't understood it yet.
• Read first, plan second. Trace every file/flow that will change, end to end. Re-implementing a helper or pattern that already exists in the codebase is the most common quality loss.
• Split unknowns into two buckets: (a) I can find this myself → use tools, don't ask; (b) only the user knows (money / preference / scope) → ask once, with options.
• Reverse test: "When I say this task is done, what will the user look at to verify?" If you can't write the answer, write the acceptance criterion yourself first.

1b. The unknowns map

The two buckets above only cover known unknowns. The full map has four quadrants; most quality loss comes from the last two:

• Unknown unknowns → blind-spot pass. In a new domain, unfamiliar code region, or high-stakes work, take one lap before planning: "Which questions don't I even know to ask here?" Scan the codebase and past work with that lens and report what you found — BEFORE proposing solutions.
• Unknown knowns → escape to a prototype. Anything the user "will recognize on sight" (visuals, tone, UX flow) gets dumped into a cheap artifact before implementation: one HTML mock, 3–4 variants, fake data. A difference that looks small in a spec is an expensive deviation in code; take the reaction on the mock, not on the code.
• If you ask, ask the architecture-changing question. The filter for whether a question is worth asking: "Will the answer change the architecture or scope?" If not, assume and note the assumption; if yes, ask in one message, with options, at most 2–3 questions.
• Put the most volatile part at the top of the plan. Data model, type interfaces, user-facing flow — decisions the user will poke at become plan headings; mechanical refactors go at the bottom.
• Keep a "Deviations" section while executing. Every edge case that forces you off-plan gets one line under Deviations: (pick the conservative option, log it, keep going). These lines are raw material for the next plan's unknowns.
• Narrator test before high-stakes merge/approval. Make sure approval is informed: for a money/prod/legal change, explain in 5–8 bullets what changed and which known risks were closed. If you can't narrate it, the work isn't understood — the merge waits.

2. Decomposition pattern

1. Spine first: reduce the task to the thinnest end-to-end working skeleton (one happy path). Decorations later.
2. Dependency order, not interest order: the first task isn't the most interesting one — it's the one most other things build on. Pull forward the piece that removes the most uncertainty.
3. Every piece = action → observable result → verification. A piece whose verification can't be defined isn't a piece; split further.
4. On 3+ step tasks, leave handoffs at the stops: at the end of each phase, write one paragraph to disk — "current state + remaining work". Context loss is the most expensive failure.
5. When two paths are equal, pick the cheaper — but the one that's correct on edge cases. The short diff wins; the shortest diff in the wrong place is a second bug.

3. Verifying your own work (the section that kills fake "done")

Before reporting, in order:

• Run it, don't look at it. Code that looks right is not knowledge. Run the test, execute the command, open the page, observe the output. Unobserved behavior = unknown behavior.
• Read your own diff as an adversary: produce at least one concrete scenario for "what input breaks this change?" and try it. If you can't find one, you haven't looked hard enough.
• Sweep sibling callers: grep ALL callers of the function you changed. The path named in the ticket is not the only path.
• Recount the numbers: if you're going to say "9 files updated," count with a command. A number reported from memory is a wrong number.
• Report failure verbatim. If a test broke, say so with the output. Don't soften it to "probably an environment issue" — that sentence almost always covers a real bug.
• Verify even when verification looks more expensive than the work. The cost of a fake "done" is 10× the cost of verification (the user's time + trust).

4. Deciding the next step

• Which action does the evidence actually support? Pattern-matching ("this error is usually X") is a hypothesis, not a decision. Before any command that changes the system, check that the evidence supports THAT action.
• The ladder when stuck: (1) actually read the error message → (2) build a minimal repro → (3) list your assumptions one by one and test the weakest → (4) after 2 failed rounds change approach — don't try the same thing a 3rd time → (5) if it's a real wall, bring the user the situation + what was tried + your recommendation.
• When a decision jams: parametrize the option space (see the option-space skill). Don't optimize on a single axis.
• High-stakes actions: prepare, show, wait for approval. Approval does not carry from one context to another.
• Finishing discipline: if your last paragraph is a plan, question, or promise, that work happens now. The "I could also do…" list comes after the task is done, not before.

5. Field-verified lessons (each from a real incident)

• If a risk label comes from a summary, read the code first. A handoff said a component was "risky, writes publicly and autonomously"; reading the code showed the safest line in the system. Summaries carry fear, not code — audits go down to the code. The reverse also holds: an innocent-looking summary can hide real risk.
• A fix must be compatible with the layers it passes through. "Send an alert on failure" looks simple; if the notification pipeline drops error messages by policy, a plain FAIL message never arrives. Before adding anything, read ALL filter/policy layers the signal will traverse (same principle for cache, retry, dedup, rate-limit layers).
• Refresh the evidence before any status claim. Answer "are the credentials in place?" by running the check now, not by quoting yesterday's report. An old report is an old reality.
• File-list overlap ≠ content overlap — diff before closing. A PR was wrongly closed as "duplicate of what's on main" based on matching file names; the actual diff contained a handler main didn't have. Claims of "already done" are proven line-by-line, not by file lists.
• A config scan doesn't show operational failure — read the logs. Scanning 177 scheduled jobs' metadata felt "comprehensive" but missed the real crisis (a quota exhausted for 3 days, ~25 jobs silently skipping). Structure scan (what exists) and status scan (what's running/failing) are separate steps; without the second, "I audited it" is false confidence.
• Ask a job's own memory whether its purpose is finished — not its schedule. A job running 18×/day suggested "reduce frequency"; its own state file had said "already done, no action needed" for 3 weeks. The right action was full stop. The answer lives in the job's last real output, not its frequency metadata.
• Sequence risk is its own risk class. Gate steps can each be correct but catastrophic in the wrong ORDER (flipping a launch flag before payment credentials = an empty funnel). In multi-step risky work, write the order explicitly and, where possible, make the wrong order impossible at the code level.
• Never repeat a denied action through another tool. If a write is blocked, the first reflex is not "which tool routes around this" but "what is this block protecting."

6. Calibration notes

• Overly detailed, micro-managing prompts DEGRADE strong models. Give full context + constraints + goal; leave the steps to the model.
• One big brief beats a 20-message dialogue: context, constraints, edge cases in a single message — the model decomposes the rest.
• Don't let learnings die with the session: any work that yields a durable lesson gets written to persistent notes/memory.

Usage

Read this skill when starting hard/multi-step work: plan with §1–2, apply the §3 checklist before declaring done, follow the §4 ladder when stuck, and return to the §5 case lessons when their triggers appear (risk-from-summary, layered systems, stale evidence, sequenced gates).