andrem-sec 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:
- High reversal cost -- if the wrong path is taken, unwinding it requires significant rework
- Competing valid options -- multiple approaches appear reasonable; it's not obvious which to pick
- Hidden assumption -- the correct choice depends on an assumption that might be wrong
- Downstream impact -- the decision constrains multiple future decisions
- 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.
Entropy Scan Format
Output a numbered list of candidates. For each:
1. [Branch point name]
Decision: [What must be decided here]
Why it's high-cost: [One sentence -- reversal cost / competing options / assumption / downstream]
Options: [2-3 concrete alternatives]
Present the full list before asking for confirmation. Do not reason through them yet -- the scan is identification only.
Gate Confirmation
After presenting candidates:
Which of these should get a reasoning gate?
all / [numbers] / none
User responds. Confirmed gates get deep reasoning before that decision point is reached during execution. Unconfirmed gates proceed normally.
Gate Execution
At each confirmed gate, before making the decision:
- Enumerate options -- list each viable path explicitly
- State assumptions -- what must be true for each option to be correct
- Identify the dominant risk -- what breaks if this choice is wrong
- Pick with explicit rationale -- state the choice and why it wins
Then continue execution. Do not gate indefinitely -- the goal is one well-reasoned decision per gate, not a committee meeting.
Depth without extended thinking: If extended thinking is unavailable, use multi-step verbal reasoning. Work through the options out loud before committing.
Fallback Standing Instruction
The fallback applies to two scenarios that emerge during execution:
1. Unexpected fork -- a discrete decision point appears that wasn't in the scan:
BRANCH DETECTED: [description of the unexpected decision point]
This was not in the original gate list. Do you want to:
1. Gate it (pause here and reason through it)
2. Continue with my best judgment
3. Stop and re-scan
2. Complexity buildup -- within a continuous output section (plan, report, ADR), complexity accumulates mid-generation to the point where the next tokens depend on an assumption that hasn't been verified. This is not a fork -- it's a local concentration of reasoning cost that wasn't visible from the upfront scan.
When this occurs, pause before continuing that section:
COMPLEXITY BUILDUP: [section name]
Reasoning before continuing: [work through the assumption explicitly]
Continuing with: [the resolved path]
Do not surface complexity buildup to the user unless it changes the overall approach. Resolve it inline and continue.
Never silently resolve an unexpected branch. Surface it and wait for a response.
Anti-Patterns
Over-gating: Gating on obviously correct decisions wastes time. If there's one clear answer and no competing options, it's not a gate candidate.
Under-gating: Treating one-way-door decisions as two-way-door decisions is the most common failure mode. When in doubt about reversibility, gate it.
Gating the whole task: Reasoning gates are for branch points, not for every step. If you find more than 5 candidates in a scan, the task needs decomposition first.
Post-hoc gating: Gating after execution has already begun at that point. Gates must be confirmed before reaching them, not at the moment of decision.
Mandatory Checklist
- Verify entropy scan produced 2-3 candidates (not 0, not 6+)
- Verify each candidate has a stated reason for high reversal cost
- Verify user confirmed which gates are active before execution began
- Verify each confirmed gate was paused on with explicit option enumeration
- Verify unexpected branches during execution were surfaced, not silently resolved