reasoning-gates

name	reasoning-gates
description	Scan task for high-cost branch points, confirm which get deep reasoning, execute with gates active
version	0.1.0
level	2
triggers	["/reasoning-gates","where should we think carefully","identify branch points","reasoning gates","where could we go wrong"]
context_files	["context/principles.md"]
steps	[{"name":"Principles Check","description":"Before scanning for branch points, read context/principles.md and surface any active principles that apply to this task. Present them to the user with the override protocol."},{"name":"Entropy Scan","description":"Scan the task and identify 2-3 branch points where a wrong decision has high reversal cost"},{"name":"Gate Confirmation","description":"Present candidate gates as a numbered list; user confirms which get a reasoning gate"},{"name":"Execute with Gates","description":"Proceed with the task; at each confirmed gate, pause and reason through all options before continuing"},{"name":"Fallback Instruction","description":"For unexpected branches that emerge mid-execution, flag and ask before proceeding"}]

Reasoning Gates Skill

Concentrate reasoning effort where decisions are hardest to reverse. By default, reasoning is applied uniformly -- the same depth whether choosing a variable name or a database schema. This skill identifies the specific points in a task where deeper reasoning is worth the cost, then confirms with the user before investing it.

What Claude Gets Wrong Without This Skill

Without explicit gate placement, Claude applies uniform reasoning across easy and hard decisions alike. Low-stakes choices (file naming, minor formatting) consume the same mental effort as high-stakes choices (data model shape, auth strategy, interface boundaries). The result is over-engineering on simple decisions and under-reasoning on the ones that matter.

What Makes a Branch Point High-Cost

A branch point warrants a reasoning gate when two or more of these are true:

1. High reversal cost -- if the wrong path is taken, unwinding it requires significant rework
2. Competing valid options -- multiple approaches appear reasonable; it's not obvious which to pick
3. Hidden assumption -- the correct choice depends on an assumption that might be wrong
4. Downstream impact -- the decision constrains multiple future decisions
5. Ambiguous requirement -- the specification doesn't clearly dictate the answer

One-way-door decisions always get a gate. Two-way-door decisions usually don't.

Principles Check

Before the entropy scan, read context/principles.md and identify any active principles relevant to the current task. Surface them before presenting branch point candidates:

Active principles for this task:
  P-XX: [rule summary] -- say "override P-XX" to bypass
  P-XX: [rule summary] -- say "override P-XX" to bypass

If no principles apply, skip this section silently and proceed to the scan. If the user overrides a principle, follow the override protocol in principles.md before continuing.

Ambient Consensus-Plan Trigger

During the entropy scan, check whether any candidate branch point has 2+ competing valid options with no clear dominant choice. If so, emit a soft suggestion before presenting the candidate list:

Trade-off detected at [branch point name]: [2+ options with no clear winner].
This looks like a consensus-plan candidate. Invoke /consensus-plan or proceed with reasoning gates?

The user can dismiss this with "proceed" and continue with standard gate execution. Do not block execution waiting for a response -- surface and continue.

Emit this suggestion at most once per reasoning-gates invocation, even if multiple trade-offs are detected. The goal is a gentle nudge, not an interruption.