
thinking-skills
28 eval-informed thinking skills for Claude Code, including first-principles, probabilistic reasoning, systems thinking, TRIZ, OODA, pre-mortem analysis, and more
- version
- 1.0.0
- GitHub stars
- 1.8K
Install
/plugin install thinking-skills@thinking-skills-marketplaceRun it inside Claude Code after adding the marketplace with /plugin marketplace add tjboudreaux/cc-thinking-skills.
Contents
Discovered from sourceSkills 28
Bounded Rationality
Under finite tool, context, and time budgets, stop at the first option that meets a predeclared aspiration level. Optimize only when the good-to-best gap is worth the remaining budget.
When to Use
- Search or option comparison has no natural endpoint and could consume the turn budget.
- Multiple options would clear the requirement and further comparison has diminishing returns.
- The decision is reversible or low-stakes relative to more search.
- You are gathering context beyond what the decision needs to ship.
When NOT to Use
- Irreversible or high-stakes choices (data loss, security, migrations, public commitments) where the good-to-best gap is material.
- Correctness gates: tests, security checks, and "did the fix work?" need the right answer, not a sufficient-looking one.
- One cheap lookup would settle the fact — do it; do not satisfice past it.
- The aspiration level cannot be stated — clarify the requirement first.
Procedure
- State decision and budget. Name the choice, residual tool/context/time budget, and reversibility.
- Set aspiration before searching. Write concrete pass/fail criteria for "good enough." Do not evaluate until the threshold is explicit.
- Search sequentially. Score options in encounter order against the threshold only. Skip full matrices unless step 1 marked high-stakes/irreversible.
- Stop at first adequate. When an option clears every criterion, select it immediately.
- Handle search failure without moving the goalposts. If nothing clears after the pre-set cap, preserve the threshold and report no adequate option. Relax only a criterion predeclared as non-load-bearing, record the relaxation, and resume within a new cap; never raise the bar after failure.
- Commit. Record choice and residual uncertainty; spend remaining budget on execution, not re-ranking.
Stop condition: First option meets the predeclared aspiration level, or the search cap is exhausted with none adequate.
Output
Decision: <choice>
Aspiration: <pass/fail criteria>
Search: evaluated N; stopped at first adequate | cap exhausted
Selected: <option or none>
Residual risk: <what further search might change>
Next spend: <execution step>
Verification
- Falsify if you kept comparing after an option cleared the threshold, or invented the threshold after seeing winners.
- Falsify if a correctness gate or irreversible decision was treated as satisficeable.
- Over-application guard: if one cheap check settles a fact, look it up — do not invoke this skill.
Circle of Competence
Treat competence as an evidence boundary, not self-image. Answer only when grounded; otherwise fetch, mark uncertainty, or abstain. The failure mode is a fluent fabrication treated as fact.
When to Use
- About to assert a specific fact (API, path, number, config, version behavior) without a citable source from this session.
- The claim is about this codebase or system and you have not read or run the relevant artifact.
- Pattern reconstruction would sound complete but is unconfirmed.
- Cost of a wrong confident answer is material (security, data, irreversible action, trust).
When NOT to Use
- Claim is grounded in something you read, ran, or can cite this session, or is stable universal knowledge — answer without false humility.
- Error cost is trivial and reversible and you will flag the claim as unverified.
- Grounding is one cheap fetch away — fetch first; abstention is not an excuse to skip a check.
- User explicitly wants labeled brainstorming or hypotheticals.
Procedure
- Name the claim. Isolate the assertion that would be treated as fact.
- Classify the zone.
- Grounded: citeable session source (read/run) or stable non-version-specific knowledge.
- Partial: general shape known; version/repo/config detail unconfirmed.
- Ungrounded: would invent a concrete value with no source.
- Size wrongness cost. If high-stakes (security, data loss, irreversible ops), treat Partial as Ungrounded until verified.
- Act by zone.
- Grounded → answer; cite when useful; do not hedge verified facts.
- Partial → cheap fetch then answer; else answer only with explicit uncertainty and a check path.
- Ungrounded → fetch if possible; else ask or abstain with what would enable an answer. Never invent.
- Refuse competence creep. Adjacent code, prior versions, or general capability do not ground the unread target.
- Stop. Emit answer, fetch request, or abstention. Do not round "probably" to a flat assertion.
Stop condition: Claim answered with grounding, marked partial with a check path, or refused with missing-evidence note.
Output
Claim: <assertion>
Zone: grounded | partial | ungrounded
Evidence: <source or none>
Wrongness cost: low | medium | high
Action: answer | fetch-then-answer | answer-with-uncertainty | abstain/ask
Response: <wording or missing artifact>
Verification
- Falsify if a specific value was asserted with no session source and no uncertainty marker.
- Falsify if Partial/high-stakes was treated as Grounded, or a cheap fetch was skipped for abstention theater.
- Over-application guard: do not hedge or refuse claims verified this session.
Cynefin Classification
Classify by cause-effect, then use only the matching response mode. Wrong-domain method is the failure mode.
When to Use
- Unsure whether to run a playbook, analyze, probe, or stabilize.
- A method keeps failing and domain mismatch is plausible.
- A novel or mixed problem needs approach selection before solution work.
When NOT to Use
- Domain and method are already agreed—execute.
- Task is finding a specific cause, not choosing an approach.
- Classification done; switch to the domain method—do not re-label endlessly.
- Pure mechanical edits with no approach uncertainty.
Procedure
- State the unit. Name the decision, incident, or subsystem; if mixed, list separable parts.
- Probe cause-effect. Is the link obvious, expert-analyzable, retrospective only, or imperceptible in turbulence? Check predictability, urgency, and probe safety.
- Assign one domain per unit:
- Clear — obvious → Sense → Categorize → Respond with a runbook.
- Complicated — expert-analyzable → Sense → Analyze → Respond; several valid answers.
- Complex — emergent → Probe → Sense → Respond with safe-to-fail probes; amplify/dampen signals.
- Chaotic — no safe sensing time → Act → Sense → Respond; stabilize first.
- Disorder — unknown → split and classify each part.
- Mismatch check. Reject Clear if its runbook fails; Complicated if analysis cannot predict; Complex if probing is unsafe; Chaotic once safe probing becomes possible.
- Commit and stop. Output domain + first actions. Re-classify only on evidence of domain shift.
Stop when every unit has one domain, first actions, and a falsifier—or disorder is decomposed.
Output
unit: <decision/incident/part>
domain: clear | complicated | complex | chaotic | disorder
evidence: <cause-effect basis>
response_mode: <Sense-Categorize-Respond | Sense-Analyze-Respond | Probe-Sense-Respond | Act-Sense-Respond | decompose>
first_actions: <1-3 concrete steps>
falsifier: <what forces reclassification>
parts: <only if disorder>
Verification
- Falsify: Reliable prediction → not Complex. No safe probe → Chaotic. Working runbook → Clear.
- Stop: Stop classifying once the matched action is clear.
- Over-application guard: Do not call work Complex to avoid analysis or Complicated to avoid a standard fix. One label per unit; decompose multi-domain work.
Effectuation
Under Knightian uncertainty, start from available means and affordable loss—not a fixed goal and predicted return. Create the path through controllable action and real commitments.
When to Use
- The market, technology, or problem is novel enough that outcome probabilities are not trustworthy.
- Means are clearer than the goal: identity, skills, assets, and network exist before a fixed target does.
- A small action can buy information or a partner commitment without risking ruin.
- Plans keep breaking because the environment shifts faster than forecasts.
When NOT to Use
- The path is predictable: known market, knowable unit economics, established playbook → use causal planning.
- A single wrong step is ruinous or irreversible → de-risk first; do not treat affordable-loss steps as free.
- The goal is already fixed and resources are the only uncertainty → plan to the goal.
- Routine execution with settled requirements → act; do not re-inventory means.
Procedure
- Inventory means only. List who you are (skills, constraints, values), what you know (domain, tools, data), and who you know (reachable partners, users, resources). Reject "what would be needed for an ideal plan" as input.
- Cap affordable loss. State the maximum time, money, reputation, and opportunity cost you can lose and still continue. If the proposed step exceeds any cap, redesign the step smaller or stop.
- Choose one controllable next action. Prefer the smallest action that can yield either (a) a real commitment from someone else or (b) discriminating information. Act inside the loss cap; do not optimize expected return.
- Seek commitments, not opinions. Share the working means-based offer. Anyone who commits resources, access, or work becomes a co-creator and may reshape the goal. Discard non-committing feedback as non-binding.
- Leverage contingencies. Treat surprises as new means: failed hires, competitor moves, off-roadmap requests. Ask "how can this expand control?" not "how do we restore the old plan?"
- Update means and goal, then stop or loop. Fold new means and commitments into the inventory; restate the emerging goal. Stop when a viable path is controlled enough to execute, the loss cap is exhausted without traction, or uncertainty collapses into a predictable plan (then switch to causal planning).
Output
Emit an effectuation brief:
means: identity / knowledge / network actually available nowaffordable_loss: hard caps (time, money, reputation, opportunity)next_action: one controllable step inside those capscommitments_sought_or_won: who must put skin in the game, and what changed if they didcontingencies_used: surprises turned into means (or none)emerging_goal: current goal shaped by means and commitments (may differ from the starting wish)stop_or_loop: continue under effectuation, switch to causal planning, or halt
Verification
- Falsify means-first claims: if the brief starts from a fixed goal and backfills resources, rewrite from means or abandon effectuation.
- Loss-cap check: every recommended action must fit inside stated affordable loss; if not, shrink or stop.
- Commitment test: progress that depends only on predictions or uncommitted interest is invalid—require at least one real commitment or a cheap information gain.
- Over-application guard: if a reliable forecast and known playbook exist, do not force effectuation; plan causally.
- Stop: after one means → loss-cap → action → commitment cycle with an explicit stop/loop decision; do not endless-explore under the effectuation label.
First Principles
Strip assumed constraints to independently supported primitives, then rebuild. Escape analogy when convention fails or looks artificially expensive.
When to Use
- A constraint is treated as fixed ("too expensive," "impossible," "always done this way") without independent support.
- Convention or analogy has failed, stalled, or only yields weak incremental variants.
- Greenfield design where industry defaults may smuggle false requirements.
- Cost or feasibility claims rest on pricing, precedent, or authority rather than physics, math, or measured need.
When NOT to Use
- The constraint is verified physics, hard regulation, or measured capacity → accept it and optimize within it.
- A proven standard library, protocol, or known-good pattern already fits → use it; do not re-derive.
- Time-critical incidents → act on the most likely cause first; reserve first-principles rebuild for post-incident redesign.
- Incremental polish of a working system with no false-constraint signal → skip.
Procedure
- State the problem and claimed constraints. List every limit treated as fixed (cost, scale, stack, process, "must use X").
- Classify each constraint. Tag as
physics/math,regulation/contract,measured fact, orconvention/analogy/authority. Keep only the first three as binding unless evidence upgrades a convention. - Decompose to primitives. Required inputs, conservation/complexity bounds, true non-negotiables. Demand independent support (measurement, derivation, primary requirement)—not vendor pricing or competitor precedent.
- Discard unsupported assumptions. For each convention tag, state a falsifier. Drop or renegotiate anything lacking support.
- Rebuild from remaining primitives only. Simplest solution that satisfies binding constraints and ignores artificial ones. Prefer commodity inputs and fewer moving parts over analogy.
- Validate and stop. Check against real physics, contracts, and measured needs. Define the cheapest kill test. Stop when a coherent rebuild plus discriminating validation exists, or when only verified hard constraints remain.
Output
Emit a first-principles rebuild:
claimed_constraints: list with classification tagsprimitives: independently supported truths onlydiscarded_assumptions: conventions dropped and whyrebuild: solution derived only from primitivesbinding_residuals: real limits that remainkill_test: cheapest check that would falsify the rebuild
Verification
- Independence check: every primitive must cite measurement, derivation, or primary requirement—not precedent alone.
- No smuggled analogy: if the rebuild still depends on "how others do it" without a primitive, strip it.
- Constraint honesty: verified physics/regulation must remain; do not wish them away.
- Over-application guard: if a standard solution is already optimal under verified constraints, do not rebuild for novelty.
- Stop: one decompose → classify → rebuild → kill-test pass; do not recurse without new evidence.
Five Whys Plus
Build an evidence-linked causal chain from a known proximate fault to an actionable systemic root, then prescribe a countermeasure that would have blocked it.
When to Use
- A fault is already localized to a component, path, or subsystem.
- The proximate cause is known, but recurrence or systemic root is not.
- Prior symptom-only fixes failed and the failure returned.
- You need prevention that addresses why the proximate cause was possible.
When NOT to Use
- Fault is not localized or multiple candidate causes remain — discriminate first.
- Root is evidenced and actionable — fix it.
- No evidence can answer the next "why" — gather evidence.
- One-off error without a process, tooling, or design enabler.
- Selective defect needing IS/IS-NOT analysis.
- Forward failure forecasting before commitment.
Procedure
- State the localized problem. Record the observable symptom, confirmed component/path, time window, scope, and impact. Stop if localization is missing.
- Chain why with evidence. Make the prior answer the new effect; propose a cause; cite logs, code, config, metrics, or witnesses; name and rule out alternatives. Stop on speculation.
- Branch before descending. Ask what else could produce the same effect; keep every evidenced independent pathway. Treat the retained branches as a causal set rather than forcing one root.
- Counterfactually test each pathway and the set. For each candidate ask, "Would removing this cause block this pathway?" Then ask, "Would removing the retained set block the observed failure?" Retain independently sufficient branches whose removal blocks their own pathway; do not reject them merely because another branch could still cause the failure.
- Enforce stop criteria per branch. Stop a branch only when its cause is evidenced, controllable, actionable, recurrence-preventing, non-blame (not merely "someone erred"), and counterfactual-positive for that pathway. If it hits human error, ask why the error was possible.
- Prescribe a countermeasure for every retained root. Name the systemic fix, owner-capable action, and how recurrence will be checked. Prefer removing enabling conditions over only patching the proximate symptom.
- Stop when verified or blocked. Halt when stop criteria pass and a countermeasure is specified, or when further steps lack evidence. Do not pad by habit.
Output
Problem: <localized symptom + component>
Chain:
Why1: <cause> | Evidence: <...> | Ruled out: <...>
WhyN: ...
Causal set check: would removing all retained roots block the failure? yes/no
Roots:
- <systemic cause> | Pathway counterfactual: <...>
Countermeasure: <action that removes the enabling condition>
Verification: <how to confirm this pathway is blocked>
Verification
- Falsify the chain if any step lacks evidence, if alternatives were never considered, if a retained root does not pass its pathway counterfactual, or if the full causal set does not explain the failure.
- Stop applying this skill once the root is fixed and verified, or when the problem is still pre-localization.
- Over-application guard: skip a full chain for a single known one-line defect; do not end at blame; do not invent depth without data.
Jobs to Be Done
Core rule: users hire solutions for progress in a situation. Prioritize the job, forces, outcome, and competing workaround—not the feature list.
When to Use
- Choosing what to build, cut, or prioritize when user need is unclear
- Explaining low adoption of a shipped feature
- Mapping competition beyond same-category products (email, spreadsheets, manual work, non-consumption)
- Positioning or research when the progress sought is contested
Requires at least one evidence source: PRD/spec, tickets, support/sales notes, analytics/logs, or current product behavior. If none exist, name the research gap; do not invent quotes.
When NOT to Use
- Pure execution once the job is known (bug fix, schema, CI, performance)—implement, do not rediscover the job
- Retro-justifying a decision already locked—framework theater
- Infrastructure/internal work with no end-user progress decision
- When the open question is only how to implement a settled job
Procedure
- Name performers and circumstance. Who hires a solution, in what trigger situation, how often, and with what stakes. Prefer primary performers with daily high-stakes jobs over rare secondary ones.
- State the job, not the solution. Frame:
When [circumstance], I want to [progress], so I can [outcome]. Reject solution-shaped statements ("use Slack", "add a dashboard"). Capture functional, emotional, and social dimensions only if evidence supports them. - Map forces and switch. From artifacts: what push made the old way fail, what pull the new progress offers, what anxiety blocks switching, what habit keeps the status quo. List what they hire today—including non-software and non-consumption.
- Define done and outcome metrics. How the performer knows the job is finished. List outcomes to minimize and maximize (time-to-progress, rework, confidence, surprises). Prefer frequent, poorly served jobs over rare, adequately worked-around ones.
- Score candidates against the job. For each feature/priority: which job step it serves, performer share, frequency, quality of alternatives. Promote high-frequency underserved dimensions; demote polished work for well-served or low-stakes jobs.
- Strongest countercase. State the best case that the stated job is wrong (wrong performer, vanity metric, process-is-the-job, competition is actually non-consumption). If the countercase fits evidence better, revise the job before recommending build.
- Stop. Stop when one primary job statement, competing set, and outcome metrics are evidence-backed enough to change a build/position decision—or when artifacts cannot answer and research is the only next step.
Output
Produce a JTBD decision artifact:
Job statement: When …, I want to …, so I can …
Performers: primary / secondary (frequency, stakes)
Forces: push / pull / anxiety / habit
Competition: direct | indirect | non-consumption
Outcomes: minimize […] ; maximize […]
Priority implication: build / cut / reposition — because job gap is …
Countercase checked: …
Evidence used / gaps: …
Verification
- Falsify: If replacing the job statement with a feature name does not change the recommendation, you never left solution-space—rewrite the job from circumstance and progress.
- Stop: Do not keep mapping job steps once the ranking decision is stable.
- Over-application guard: Skip on pure implementation tasks and known jobs. Never fabricate user quotes or personas to fill missing evidence.
Kepner-Tregoe Analysis
Core rule: Diagnose deviations by testing causes against both IS and IS-NOT. Compare consequential choices by screening MUSTs, weighting WANTs, and exposing adverse consequences before selecting.
When to Use
- A defect affects some objects, places, times, or cohorts but not comparable others.
- Several candidate causes remain and the contrast boundary can discriminate them.
- A consequential option choice has explicit non-negotiables, competing objectives, and risks that should be compared consistently.
When NOT to Use
- A uniform failure has no meaningful IS-NOT contrast, or the cause is already confirmed.
- One cheap observation settles the cause or one option plainly dominates every requirement.
- The criteria cannot be made operational; clarify them before assigning weights.
- The task is forward failure discovery for a planned change rather than diagnosis or option selection.
Procedure
- Choose the mode. Use Problem Analysis for a deviation from expected behavior; use Decision Analysis for a choice among options. State the target and do not mix scores with causal evidence.
- Frame the target. For a deviation, record object, defect, location, time, extent, and impact. For a choice, state the decision, alternatives, constraints, and deadline.
- Problem Analysis — build IS/IS-NOT. For WHAT, WHERE, WHEN, and EXTENT, record IS, closest comparable IS-NOT, and the distinction unique to the IS side. List changes near the first occurrence.
- Problem Analysis — difference-test causes. Generate candidates from distinctions and changes. A candidate survives only if it explains both IS and IS-NOT. Run the cheapest discriminating check; stop when one verified cause explains the full boundary.
- Decision Analysis — screen and score. Define pass/fail MUSTs and weighted WANTs (1–10 importance) before scoring. Eliminate options that fail any MUST; score survivors against each WANT and calculate weighted totals using the same scale.
- Decision Analysis — test downside and sensitivity. For leading options, list adverse consequences with probability × impact and identify assumptions or weight changes that would reverse the ranking. Do not let a high total conceal a ruinous failure mode.
- Decide or expose the gap. Return the verified cause or highest-ranked acceptable option, the evidence/score behind it, residual risk, and next verification. If no cause verifies or no option passes MUSTs, return open/none rather than force a winner.
Output
Return one mode-specific decision artifact:
- Problem Analysis: problem statement; IS/IS-NOT matrix with distinctions; nearby changes; candidate-vs-boundary tests; confirmed cause or next discriminating check.
- Decision Analysis: decision statement; alternatives; MUST screen; weighted WANT matrix; adverse-consequence table; sensitivity/reversal conditions; selected option or none.
Verification
- Falsify/stop: reject a cause that cannot explain both sides of the boundary. Reject a choice if it fails a MUST, depends on inconsistent scoring, or loses under a plausible weight/risk change that was hidden.
- Over-application guard: skip the full matrix for an obvious cause, trivial choice, or one-shot check. Stop when the cause verifies or the option is robust enough for the stated stakes; extra rows are ceremony.
Lindy Effect
For non-perishable ideas, technologies, and practices, expected remaining life scales with current survival age. Prefer proven survivors unless the new option clears a burden of proof or the domain has drifted.
When to Use
- Choosing languages, frameworks, databases, protocols, patterns, or dependencies where long-term survival matters.
- Skill or architecture bets whose value depends on lasting relevance.
- Ranking options when ages differ materially and the choice outlives a short experiment.
When NOT to Use
- Perishable targets: specific SaaS vendors, hardware, fashion, or products that can shut down regardless of concept age.
- Active paradigm discontinuity where age in the old regime is weak evidence.
- Throwaway work where longevity is irrelevant — optimize for fit and speed.
- Treating "older" as "optimal for a new requirement"; survival predicts further survival, not best fit.
Procedure
- Confirm non-perishable scope. Concept/tech/practice continues; vendor/device → score fit/risk only and stop.
- Record survival age. First significant production use and current age (ecosystem-relative if the ecosystem is young).
- Form the Lindy prior. Expected remaining life ≈ current age; mark confidence from age and continued active use.
- Run domain-drift checks. Problem class changed? Paradigm shift invalidating old assumptions? New option uniquely closes a real present gap?
- Assign burden of proof. Default to the older adequate option. Accept newer only for a stated necessary advantage the Lindy option cannot meet at acceptable cost.
- Decide with residual risk. Pick primary; note impact if the prior is wrong and any fallback.
Stop condition: Primary chosen with age prior, drift check, and why new did or did not meet burden of proof.
Output
Options: <name, age, Lindy prior>
Drift: stable | discontinuous — <note>
Burden: on new | waived because <gap>
Decision: <primary>
Rejected: <one line each>
If Lindy wrong: <impact + fallback>
Verification
- Falsify if age was used without non-perishable scope, or a paradigm shift was ignored.
- Falsify if a new option was rejected solely for youth despite a documented necessary gap.
- Over-application guard: skip throwaway prototypes and perishable vendor bets where fit and exit cost dominate.
Map Territory
Docs, tests, diagrams, metrics, comments, and mental models are maps. Running code and actual data are the territory. When they disagree, verify territory and update the model — never force reality to match the description.
When to Use
- Observed behavior contradicts a doc, test expectation, diagram, comment, dashboard, or prior assumption.
- A claim about the system rests on a secondary source rather than current code or data.
- Tests pass but production or manual behavior is wrong.
- You are about to theorize why something happens before inspecting what happens.
- A decision depends on whether a model, schema, or metric is still current.
When NOT to Use
- The map is the artifact you are asked to edit (doc, diagram, spec) — that artifact is the task territory.
- Same path already verified this session — reuse that observation.
- Map is authoritative and generative (codegen types, derived schema) with no claimed drift.
- The mismatch cannot change the decision — note and move on.
- Competing causal hypotheses after territory is confirmed — switch to scientific-method.
- Security exploit construction — use red-team; this skill only settles model-versus-observation.
Procedure
- Name the map. State the exact representation trusted: which doc, test, metric, diagram, comment, or assumption. Quote the claim, not a paraphrase.
- Name the territory check. Specify the observation that would prove or disprove the claim: code path, runtime value, query, reproduction, recent change, or live metric.
- Verify source and freshness. Confirm origin of the map (author, generator, last update) and whether it could be stale relative to deploy, config, or data change. Prefer primary current sources over summaries.
- Observe the territory. Read the real code path, run or instrument it, query real data, or reproduce the behavior. Do not predict from signatures or names alone.
- Record the delta and update. If territory contradicts the map, territory wins for shipped behavior. Document the gap, revise the model, then decide the fix (code, map, or both). Note unmapped paths — likely next failure sites.
- Stop when settled. Once the claim is confirmed or overturned with a concrete observation, stop re-checking the same path.
Output
Map: <claim + source + freshness>
Territory check: <what was inspected/run/queried>
Observation: <concrete result, not interpretation>
Delta: <aligned | map wrong | territory incomplete>
Updated model: <corrected understanding>
Action: <fix code | update map | no decision impact>
Uncovered: <paths no map covers>
Verification
- Falsify if you reasoned from the map without a territory observation, trusted a stale secondary source, or forced code to match a wrong doc without checking either.
- Stop when the contradiction is resolved or irrelevant to the decision.
- Over-application guard: do not re-verify the whole system when editing the map, when the map is the generative source of truth, or when the gap cannot change the next action.
Margin of Safety
Core rule: commit a buffered number when residual uncertainty plus breach cost can cause ruin or costly failure. Margin covers estimation error; it is not free slack for laziness.
When to Use
- Capacity, timeouts, pool sizes, queue depths, storage, or SLA numbers under load uncertainty
- Timeline or budget commitments where underestimation is costly
- Architecture headroom when scaling or recovery is slow
- Any public or production commitment where being wrong has asymmetric downside
When NOT to Use
- Breach is detected immediately and fixed near-zero cost (fast auto-scale, live-tunable limit)—static fat buffers waste resources
cost(buffer) > P(breach) × cost(breach)—right-size or measure instead of maxing out- Uncertainty is eliminable by measurement or lookup—get the real number first
- Stopping-criterion / search budget problems—use bounded rationality, not padding
- Fully known parameters and low stakes where edge optimization is the goal
Procedure
- Point estimate without padding. State the base requirement in explicit units (RPS, weeks, GB, ms) and confidence (high / medium / low).
- Uncertainty and breach cost. List drivers (spike, growth, unknowns, dependency variance). State what fails if undershot: outage, missed launch, data loss, reputation—and whether failure is recoverable or ruinous.
- Size the buffer. Multiply or add margin to residual uncertainty and stakes—not to vanity. Typical bands (adjust with evidence):
- Well-known, low consequence: ~1.2–1.5×
- Familiar with unknowns / reversible: ~1.5–2×
- New domain, external deps, SLA, irreversible: ~2–3× Cap or cut when buffer cost exceeds expected breach cost.
- Ruin constraint. If a breach can cause irreversible harm, size so the worst plausible miss still stays above the failure threshold; if that buffer is unaffordable, change the design (shed load, degrade, stage) rather than pretend precision.
- Strongest countercase. Challenge both under-buffering ("we will scale later") and over-buffering (idle cost, complexity). Prefer measure-then-trim when history exists.
- Commit and monitor. Publish the buffered commitment, the failure threshold, and the metric that would prove margin excessive or thin. Stop when the number is set and monitorable.
Output
Base estimate: … (units, confidence)
Uncertainty drivers: …
Breach cost / failure threshold: …
Margin applied: …× (or absolute buffer …)
Buffered commitment: …
Ruin check: pass | redesign needed
Cost of margin vs expected breach cost: …
Monitor: metric … ; thin if … ; excessive if …
Verification
- Falsify: If the buffered number equals the optimistic point estimate, no margin was applied—or if margin was added with zero stated breach cost, it is cargo-cult padding.
- Stop: Once commitment, threshold, and monitor exist, stop stacking multipliers without new uncertainty evidence.
- Over-application guard: Do not pad when adjustment is free and instant, or when the real number is cheaply measurable. Do not confuse search-stopping with capacity buffers.
Model Combination
Core rule: Combine only when each model answers a different named question. Cap at three, name the conflict rule before applying, then synthesize once.
When to Use
- One model already applied (or clearly primary) still leaves a material blind spot that another mechanism covers.
- Problem spans domains (e.g. risk + choice + system structure) and stakes justify multi-lens work.
- You need independent checks, not confirmation of the same conclusion.
- You can name a distinct role per model before running them.
When NOT to Use
- A single catalog skill fully answers the unknown — apply that skill alone.
- Routine, local, or fully reversible work where multi-lens cost exceeds upside.
- You cannot state what unique question each extra model answers (checkbox / model soup).
- Near-duplicate mechanisms (two diagnosis skills that ask the same causal question).
- Time budget cannot support genuine synthesis — prefer one honest model over contradictory partials.
Procedure
- State the unknown and the gap. Write the decision question. If one model already covers it, stop and use that model alone. Otherwise name the specific blind spot (e.g. "failure modes unexamined", "displaced alternative unknown").
- Pick 2–3 models with distinct roles. For each, record: model id, role (narrow / decide / stress / cost / …), and the unique question it answers. Drop any model that only rephrases another. Prefer sequential pipeline (narrow → stress → decide) over parallel unless independent concurrent checks are required.
- Lock the relation and conflict rule before applying. Choose pattern: sequential, parallel, nested (macro→meso→micro), or adversarial (for/against). Predeclare the tiebreaker (e.g. reversibility class, evidence strength, ruin constraint, primary decision owner). Incompatible worldviews run sequential or adversarial — never blended.
- Apply each model fully for its role only. Capture one key insight per model plus what only that model revealed. Do not re-run a model that adds no new insight.
- Synthesize once. Record convergence, divergence, how the conflict rule resolves divergence, and a single combined recommendation with residual uncertainty. Stop when the recommendation is decision-ready or when further models would only reconfirm.
Output
problem: <decision question>
gap: <named blind spot justifying combination>
pattern: sequential | parallel | nested | adversarial
models:
- id: <skill>
role: <named job>
unique_question: <what only this answers>
insight: <key finding>
conflict_rule: <predeclared tiebreaker>
convergence: <where models agree>
divergence: <where they conflict + resolution>
recommendation: <single decision-ready answer>
stop_reason: gap_closed | single_model_suffices | budget
Verification
- Falsify / stop: Remove a model only when it changes none of the recommendation, supporting evidence, confidence, residual risks, or mitigations; then re-synthesize with fewer. If no predeclared conflict rule exists and models disagree, do not average — pick one primary model or stop and re-route.
- Over-application guard: Never exceed three models. Never add a model for thoroughness theater. If the first adequate single model already closes the gap, combination is wrong for this task.
Model Router
Core rule: Prefer NONE or one primary skill. Route by mechanism fit, not habit. Combine only when roles are distinct and necessary.
When to Use
- The right thinking skill is unclear and you would otherwise guess or stack tools.
- Several catalog skills seem plausible and you need a single primary (or explicit NONE).
- High-stakes work where a wrong frame is costly and a quick domain×type match helps.
When NOT to Use
- The match is already known or obvious ("where's the bottleneck?" → theory-of-constraints) — invoke that skill directly; do not route for show.
- The task is routine implementation with no analytical unknown — reason directly (NONE).
- You are mid-execution of an agreed plan and only need the next concrete step.
- The ask is outside this catalog (pure coding syntax, tool ops with no judgment call) — NONE.
Invoking a Model (Skill IDs)
The router outputs bare slugs (e.g. id: five-whys-plus). Invoke a routed skill with the Skill tool using the exact ID thinking-skills:thinking-<slug> — never invent a slug not cited in Procedure. NONE means no invocation.
Procedure
- Short-circuit. If one skill clearly fits by mechanism, return that skill alone. If no skill clearly improves the work, return NONE and reason directly. Stop.
- Characterize. Record domain (coding, architecture, product, strategy, personal, abstract, risk, innovation) and problem type (diagnose, decide, understand, create, evaluate, predict, optimize). Note constraints: time, information, stakes, reversibility, complexity.
- Candidate by type defaults (override when constraints demand). Keep only active catalog skills:
- Diagnose → five-whys-plus or scientific-method (kepner-tregoe if IS/IS-NOT matrix needed)
- Decide → reversibility first; then opportunity-cost or probabilistic
- Understand → systems (map-territory if model-vs-reality gap; cynefin if approach domain unclear)
- Create → first-principles (triz for contradictions; effectuation for means-driven; via-negativa for remove-first)
- Evaluate → steel-manning (socratic if assumptions/definitions are the unknown)
- Predict → probabilistic
- Optimize → theory-of-constraints (ooda under time pressure; bounded-rationality for search stop)
- Risk / "what fails?" → pre-mortem or red-team; margin-of-safety for buffers
- Product "what to build?" → jobs-to-be-done
- Competence / durability → circle-of-competence, lindy-effect
- Controlled hypothetical → thought-experiment
- Multi-lens only after one primary fails a blind-spot check → model-combination
- Select with criteria (satisficing). Score only if 2+ candidates remain or stakes make a forced default unsafe. Rate each criterion 1–5 (1 = absent/wrong fit; 3 = usable with gaps; 5 = direct fit): problem fit (30%), available inputs (20%), time to apply (15%), stakeholder usability (15%), competence to apply correctly (20%). A route must score problem fit ≥4 and weighted total ≥3.5; otherwise return NONE. For totals within 0.25, prefer fewer inputs and shorter execution; if still tied, choose NONE unless the skills answer distinct complementary questions.
- Multi-skill only as exception. Add a second or third skill only when each has a distinct complementary role the primary leaves open. Cap at three. Prefer sequential over parallel. Near-neighbors and synonyms do not stack. For composition patterns, hand off to model-combination after naming the primary.
- Exit. State abandon signals (forced fit, ignored factors, no insight ~15 minutes). On mismatch, re-route once or fall back to NONE — never force a frame.
Domain cheat-map (primary first; still default to one or NONE):
| Domain signal | Prefer |
|---|---|
| Bug / root cause / flaky | five-whys-plus, scientific-method, systems |
| Architecture / tech choice | reversibility, systems, lindy-effect, opportunity-cost |
| Feature / roadmap / engagement | jobs-to-be-done, opportunity-cost, theory-of-constraints |
| Strategy / competition / growth | cynefin, systems, red-team, second-order |
| Personal / career commitment | opportunity-cost, reversibility, circle-of-competence, pre-mortem |
| Argument / belief update | steel-manning, probabilistic, socratic, first-principles |
| Security / disaster / ruin | pre-mortem, red-team, margin-of-safety, via-negativa |
| Innovation / contradiction / simplify | first-principles, triz, effectuation, via-negativa |
Output
outcome: NONE | one | multi
routes:
- id: <primary skill id or NONE>
role: <job this skill performs>
unique_question: <question only this route answers>
- id: <secondary skill id, only for multi>
role: <distinct complementary job>
unique_question: <distinct open question>
- id: <tertiary skill id, only for multi>
role: <distinct complementary job>
unique_question: <distinct open question>
domain: <domain>
problem_type: <type>
constraints: <time/info/stakes/reversibility>
rationale: <mechanism fit in one sentence>
blind_spots: <what primary still ignores, if any>
exit: <when to abandon or re-route>
Default fill: outcome: NONE with one id: NONE route, or outcome: one with one route. Use multi only when every listed skill has a distinct role and unique question.
Verification
- Falsify / stop: If the route is habit or familiarity rather than mechanism fit, discard and re-score or return NONE. If multi-skill entries lack distinct roles, collapse to the single best primary. If no candidate clearly helps, NONE is correct — do not invent a route.
- Over-application guard: Do not route when the skill is already obvious. Do not return more than three skills. Do not cite deleted or non-catalog names. Do not treat the router as a prerequisite for leaf skills invoked directly.
OODA Loop
Core rule: For reversible moves under time pressure, act on ~70% confidence, then immediately re-observe. Cycle faster than the situation compounds; a late perfect plan loses to a fast loop.
When to Use
- Incident response, outage, or ongoing degradation where state is still moving.
- Debugging a moving target (intermittent failure, live traffic shift).
- Any time-bounded decision where waiting for full certainty costs more than a reversible action.
When NOT to Use
- The situation is static and you have time — deliberate analysis or a hypothesis differential wins.
- The next action is irreversible or high blast-radius — raise the evidence bar; 70% is not enough.
- You can cheaply localize the cause (read the failing diff, log, or metric) — test that hypothesis directly instead of looping in the dark.
- There is no time pressure and no changing environment — OODA adds churn without value.
Procedure
- Observe (time-boxed): gather the cheapest high-signal state now — metrics, logs, alerts, recent deploys/config, and feedback from the last action. Cap the window; do not collect forever.
- Orient: match observations to a pattern and form ≥2 candidate explanations. Update or discard the mental model when data contradicts it; refuse single-hypothesis lock.
- Decide: pick one reversible action that tests the leading hypothesis. State confidence (~70% threshold for reversible moves), the predicted effect, the observation you will check next, and a time box for that check.
- Act: execute once, decisively, with a known rollback or degrade path.
- Re-observe immediately: compare outcome to prediction within the time box; feed the result into the next Observe. Loop until stable or until the next move is no longer reversible enough for this skill.
- Stop condition: exit the loop when the system is stable, the remaining work is static analysis, or the next step requires irreversible commitment — then switch method.
Output
A cycle record (repeat per loop):
- Observed — current signals and what changed since last cycle.
- Orientation — ≥2 hypotheses; which one leads and why.
- Decision — action, confidence, predicted effect, next observation, time box.
- Act + result — what ran and what the immediate re-observe showed.
- Loop status — continue / stable / escalate out of OODA.
Verification
- Falsify/stop: if you cannot name a reversible next action and a near-term observation that would refute it, stop looping and gather more evidence or escalate. If re-observe never happens after act, the loop is broken — fix that before another action.
- Over-application guard: do not OODA static design work, irreversible launches, or cases where a single cheap localization check ends the uncertainty. Do not wait for 100% confidence on reversible mitigations under active incident pressure.
Opportunity Cost
Core rule: every commitment displaces its best alternative. Report both that forgone value and the net value delta; decide on the delta, not the chosen path alone.
When to Use
- Allocating scarce time, headcount, budget, or attention across competing options
- Feature prioritization, build-vs-buy, tech-debt vs product work
- Saying yes to a large commitment that displaces other work
- Comparing a bold path against polishing the status quo when windows may close
When NOT to Use
- Trivial or cheaply reversible choices where analysis costs more than the resource
- No real alternative use (resource is idle, earmarked, or non-fungible)
- Mandatory work (compliance, security fix, hard dependency) with no optional alternative
- Inventing speculative alternatives only to look rigorous when the next-best is clearly worse
Procedure
- State the commitment. Name the choice, the scarce resource units (eng-weeks, dollars, calendar), and the decision horizon.
- List real alternatives, including do-nothing. At least: proposed option, next-best productive use of the same resources, and status quo / wait. Drop fantasy options with no owner or feasibility.
- Value each path. For each alternative, estimate direct value, strategic value, risk, and time-to-value in the same units. Prefer rough comparable magnitudes over fake precision.
- Compute best forgone value and value delta. Identify the single best non-chosen alternative (may be do-nothing).
best_forgone_value= its estimated value.value_delta=chosen_value − best_forgone_value(same units). True cost of choosing = direct cost of the choice +best_forgone_value. Prefer the option with the superior (positive) value delta after risk; a large positive chosen value is not enough if the forgone alternative is larger. - Future tradeoff / permanent forgone options. For serious alternatives (including the bold path): mark temporary recoverable costs vs permanent losses (window closes, lock-in, no re-entry). Prefer avoiding the greater permanent loss when acting downside is recoverable and non-catastrophic—even if near-term value_delta is slightly negative. Do not invent permanence for speculative upside without evidence.
- Strongest countercase and decide. Steel the case that the best alternative or its value is misidentified (sunk-cost anchoring, status-quo undervalued, or a "free" option that still burns time). Recompute
value_deltaunder that challenge. Then choose: proceed if delta stays favorable (or permanent-loss rule applies), else switch, wait, or split. Stop when ranking is stable.
Output
Choice: …
Resources committed: …
Alternatives:
A (proposed): value … risk …
B (next-best): value … risk …
C (do-nothing / wait): value … risk …
Best forgone alternative: …
Best forgone value: …
Value delta (chosen_value − best_forgone_value): …
Permanent vs temporary losses: …
Decision: proceed | switch | wait | split — because value_delta … (and permanent-loss rule if used)
Countercase checked: …
Verification
- Falsify: If the analysis never names a concrete next-best use of the same resources, or reports only one number labeled both "opportunity cost" and "delta," it is incomplete—add B, then report
best_forgone_valueandvalue_deltaseparately. - Stop: When one best forgone alternative and a signed value delta determine the choice, stop enumerating weaker options.
- Over-application guard: Do not run full accounting on mandatory or trivial work. Ignore sunk costs; revalue only from current state forward.
Pre-Mortem Analysis
Core rule: Prospective hindsight beats "what could go wrong?" Assume the plan has already failed (past tense), generate concrete failure paths, reverse them into prevention requirements, and bind each top path to a verifiable plan change.
When to Use
- Before kickoff, major technical commitment, high-risk sprint work, launch, or release.
- After a plan looks solid but before execution, especially when optimism or overconfidence is likely.
- When a decision is costly to reverse and risks are still implicit rather than enforced.
When NOT to Use
- Work is small, local, and cheaply reversible — skip the ceremony.
- You are mid-incident under time pressure — act now (OODA / scientific method); pre-mortem is pre-execution.
- You would only emit generic risks ("scope creep", "requirements unclear") that do not bind to this plan.
- Risks are already enforced by live gates (CI, canary, rollback, alerts) with no residual unlisted path.
- A mature risk register already covers the same specific failure paths with owners and checks.
Procedure
- Set the failure frame in past tense: "It is [post-deadline date]. The plan failed: [rollback / data loss / no adoption / SLA breach]." Explaining a happened failure is required; predicting one is not enough.
- Generate failure reasons before filtering: sweep technical, process, assumptions, dependencies/external, and people. Force a second pass: "What did the plan most need to be true that was not?" Collect breadth first (aim for many distinct reasons); do not rank mid-sweep.
- Prioritize: group by theme; score likelihood × impact; keep the top 3–5 concrete risks (drop generics that do not bind).
- Failure-first reverse analysis (absorbed reverse path): for each top risk, (a) restate the failed outcome in past tense, (b) list necessary/enabling conditions that had to be true for that failure, (c) invert each condition into a verifiable prevention requirement (avoid/require rule + check), (d) bind owner, verification checkpoint, and ship/stage gate.
- Mitigate and update the plan: for each top risk, attach mitigation steps, spike/contingency if needed, and the reverse-analysis prevention requirements as explicit plan gates. A pre-mortem with no plan change is incomplete.
- Stop when top risks each have a bound mitigation or prevention gate, or when further reasons are only generic restatements — then ship the updated plan, do not keep brainstorming.
Output
- Failure scenario — past-tense disaster frame with date and failed outcome.
- Failure reasons — unfiltered list, then prioritized top 3–5 with likelihood × impact.
- Reverse paths — for each top risk: necessary conditions → inverted prevention requirements.
- Mitigations — owner, verification checkpoint, ship/stage gate per top risk.
- Plan deltas — concrete tasks, spikes, contingencies, and gates added to the plan.
Verification
- Falsify/stop: if no plan-specific failure path can be stated in past tense with necessary conditions, stop — you are generating theater, not risk. If a "mitigation" has no verification checkpoint, it is not done.
- Over-application guard: do not pre-mortem reversible chores, mid-incident firefighting, or systems that already enforce the same paths. Do not leave abstract risks as "mitigate later"; either invert them into gates or drop them as non-actionable.
Probabilistic Thinking
Core rule: State beliefs as numbers and ranges, not vibes. Anchor on a base rate, update with an explicit likelihood, and bound unknowns by factoring them — never invent false precision.
When to Use
- Timeline, effort, or outcome forecasts where the true value is uncertain.
- Risk sizing for a change, migration, deploy, or launch.
- Any moment you are about to state a confident single number you cannot actually know.
- New evidence arrives and a prior estimate should move.
When NOT to Use
- The quantity is measurable or look-up-able — measure or look it up.
- The decision is invariant across the whole plausible range — skip the estimate and act.
- There is no real reference class and you would invent a base rate — label it a guess, not a calibrated forecast.
- You only need a binary gate and already have a decisive observation — do not pad with ceremony.
Procedure
- Define a checkable claim: outcome + timeframe + unit. Prefer a falsifiable statement over vague language ("likely").
- Lock a prior and challenge it: name a reference-class base rate and at least one credible alternative path/hypothesis with its rate. Pull the prior toward the base rate unless you write a concrete reason for deviation. Then state the strongest evidence-based case that your chosen prior or range is wrong, what estimate it supports, and revise if that countercase survives. Convert vague words to numbers (e.g. "likely" ≈ 65–80%).
- Express a range, not a point: give at least one confidence interval (50% and 80% preferred). Assume overconfidence; widen intervals when the outside view is thin.
- Update prior → likelihood → posterior when evidence arrives:
- Prior odds = p / (1 − p).
- Likelihood ratio LR = P(E|H) / P(E|¬H). LR > 1 supports H; LR = 1 is noise; LR < 1 undermines H.
- Posterior odds = prior odds × LR (multiply even when LR < 1); p = odds / (1 + odds).
- Strength bands for distance from 1: weak ~1.5–3×, moderate 3–10×, strong 10–100×, definitive 100×+.
- Yesterday's posterior is today's prior for the next evidence. For rare events, start from the base rate — vivid positives still leave most mass on false alarms.
- Fermi-bound unmeasured quantities (only when you need a magnitude you cannot measure/look up):
- Decompose: Quantity = Factor₁ × Factor₂ × … (or sum of components).
- Bound each factor with a range; use one-significant-figure geometric means for order-of-magnitude.
- Multiply; report "~X within 3–5×"; sanity-check whether a 10× error would change the decision; replace any factor that is actually lookup-able.
- Skip Fermi when the number is cheaply measurable, when the decision needs tighter than ~3–5× precision, or when every factor is pure invention.
- State the final estimate for checking: claim, range/CIs, key uncertainties, and the observation that would prove it wrong. Stop when the decision is stable across the remaining range or the next update needs new evidence you do not have.
Output
- Claim — falsifiable statement with timeframe.
- Prior — base rate, alternative path, adjustment reason, strongest countercase, and resulting prior probability.
- Range — confidence intervals (not a lone point).
- Updates — each evidence row: prior, LR (or explicit heuristic Δ), posterior.
- Fermi bounds (if used) — factor product and "~X within N×".
- Decision implication — what changes if the true value is at the low vs high end of the range.
Verification
- Falsify/stop: if you cannot name a base rate, alternative, or serious countercase, label the estimate as a guess rather than calibrated. If the decision is unchanged across the full range, stop estimating. If new evidence arrives and the number does not move (or moves without an LR/Δ), recompute.
- Over-application guard: do not dress checkable facts as probabilities, invent reference classes, or Fermi-decompose quantities you can measure. Do not report three significant figures on a 5×-uncertain product. For rare events, refuse jumps from one vivid hit to near-certainty without the base-rate prior.
Red Team
Adversarial security review of systems you are authorized to assess. Attack before an outsider does, but report only what you can actually break: every finding needs a concrete exploit path and a check that the proposed fix closes it.
When to Use
- Security review of code, authentication, authorization, APIs, data handling, or infrastructure you control and are permitted to probe.
- Pre-launch hardening of systems that handle auth, money, personal data, or privileged actions.
- Checking whether a specific vulnerability class (injection, XSS, IDOR, auth bypass, SSRF, secret exposure, etc.) is present with a real path.
- Validating that a claimed control actually blocks the attack, not only that a scanner is quiet.
When NOT to Use
- No authorization to attack the target — stop; do not probe systems you do not own or have written leave to test.
- Speculative "best practice" notes without a reproducible exploit path — drop them; they are not findings.
- Plan, strategy, or decision stress-testing — use pre-mortem (how the plan fails) or steel-manning (strongest case against the decision).
- Architecture resilience without a security objective — use systems or pre-mortem.
- Scanner output alone as a report — patterns are leads; red-team requires an exploit path.
- Non-security root-cause or hypothesis localization — use scientific-method or five-whys-plus.
Procedure
- Confirm authorization and objective. State target, allowed scope, out-of-scope assets, success condition (e.g., unauthorized data read, privilege escalation), and stop rules. Refuse or narrow if authorization is unclear.
- Build the threat model. Name adversary profiles (anonymous external, authenticated user, privileged insider) and their goals under realistic access. Attacks without an actor and goal are noise.
- Map the attack surface. Enumerate entry points and trust boundaries: public endpoints, auth flows, APIs, uploads, admin surfaces, jobs, webhooks, secrets, and data stores. Note exposure and required privileges.
- Trace exploit paths. For each high-value surface, attempt concrete abuse: input manipulation, authz gaps, token/session misuse, injection, SSRF, IDOR, mass assignment, rate-limit bypass, secret leakage. Record exact steps and observed behavior.
- Apply the anti-fabrication gate. Keep a finding only if you can complete: entry point → ordered steps → realized impact on this code/config. Incomplete paths are dropped, not listed as "informational."
- Score severity and attempt defense bypass. Rate impact and exploitability. For each relevant control (rate limit, validation, session check), try a realistic bypass and record held vs broken.
- Prescribe and verify mitigations. For each kept finding, give a minimal concrete fix and state how to re-test that the path is closed. Prefer fixes that remove the exploit precondition. Stop when in-scope surfaces are covered or authorization/budget ends; zero findings is valid.
Output
Target/scope: <in | out | goal | authorization>
Threat model: <actors, access, goals>
Attack surface: <entry points + trust boundaries>
Findings (only complete paths):
- Title | Severity
Entry: <endpoint/param/file>
Steps: <1..n>
Impact: <realized effect>
Bypass attempts: <control → result>
Mitigation: <minimal fix>
Re-test: <how to confirm closed>
Summary: <kept count; dropped speculative count>
Verification
- Falsify any finding missing entry, steps, or realized impact; treat "could be vulnerable" as non-finding.
- Stop when in-scope attack surfaces are exhausted under authorization, or when re-test shows mitigations close the paths.
- Over-application guard: do not pad with best-practice laundry lists; do not use this skill for non-security plan critique; do not attack without authorization.
Reversibility
Core rule: match process depth to undo cost. Most decisions are cheaper to reverse than they look; irreversible ones deserve deliberation and staged commitment.
When to Use
- Uncertain how much analysis a decision deserves (tech, process, product, org)
- Tempted to committee a low-blast-radius choice, or to rush a high-lock-in one
- Can redesign the move (pilot, flag, abstraction, time-box) to lower undo cost
- High-stakes choice where acting vs waiting have asymmetric recovery profiles
When NOT to Use
- Already classified this session—decide at matched depth; do not re-label forever
- Trivial two-way calls (names, local refactors) where deciding is cheaper than classifying
- Externally forced move with no optionality (hard deadline, contract, regulation)
- Correctness gates (security, data integrity) that need the right answer, not speed theater
Procedure
- Name the decision and undo path. State what would be committed and the concrete reverse move (rollback, migrate back, revoke, re-hire, re-contract).
- Score reversibility. Assess technical effort, time, money, reputation, dependents, and learning lost if reversed. Classify:
- Type 2: undo in days, low cost → decide fast
- Type 1.5: undo in weeks, moderate cost → light structure + monitor
- Type 1: months or not realistically undoable → deliberate
- Asymmetric downside / recovery. For Type 1 or 1.5:
- Acting wrong: downside, recoverable?, recovery cost
- Not acting: what permanently closes (window, exclusivity, path lock)
- Rule: recoverable acting downside + permanent inaction loss → staged commit over indefinite delay; catastrophic or third-party harm → refuse or redesign first
- Option-preserving redesign. Prefer pilots, feature flags, interfaces, versioning, time-boxed vendor terms, or strangler slices that convert Type 1 surface into Type 2 experiments. Deliberate only the residual irreversible core.
- Match process and commit. Type 2: pick a reasonable option, ship, monitor. Type 1: document assumptions, argue the opposing case, surface to owner if stakes require it. Stop once class and commitment depth are set—do not re-analyze without new undo-cost evidence.
Output
Decision: …
Undo path: …
Class: Type 2 | 1.5 | 1 (factors: …)
Acting downside / recovery: …
Not-acting permanent loss: …
Staging / option-preserving move: …
Process depth: decide-now | pilot | full deliberation
Commitment: …
Verification
- Falsify: If "we can always change later" has no concrete undo path and cost, treat as more irreversible until proven otherwise.
- Stop: After class and process depth are set, further taxonomy is waste—execute the matched process.
- Over-application guard: Do not slow trivial Type 2 work with matrices. Do not use "two-way door" to skip verification on irreversible data, security, or public commitments.
Scientific Method (Hypothesis Differential)
When a symptom could come from several places, enumerate competing falsifiable hypotheses and spend the cheapest observation on the one that best discriminates among them. After each observation, keep only hypotheses that still fit, then prefer the survivor with the fewest unsupported assumptions as the working explanation.
When to Use
- A bug, incident, or anomaly has more than one plausible cause.
- You can observe code, logs, diffs, traces, tests, configs, or data now.
- You must localize the faulty file, function, branch, config, or invariant before fixing.
- Competing explanations fit the same surface facts and you need a discriminating check.
When NOT to Use
- Cause is already obvious from a single stack, failing test, or recent diff — fix directly.
- Only one plausible hypothesis exists — test it; do not invent rivals for ritual.
- No observation is possible yet — obtain access first; do not speculate a localization.
- Multi-week experiments, product A/B tests, or policy trials — this skill is for agent-now checks.
- Fault is already localized and you need systemic root/prevention depth — use five-whys-plus.
- Selective "only these objects/times" defects better suited to IS/IS-NOT comparison — use Kepner-Tregoe.
- Representation (doc/dashboard) may be stale versus reality — verify territory with map-territory first, then resume hypotheses.
Procedure
- State the symptom precisely. Capture failing behavior, scope, timing, environment, and constraints. Separate observation from interpretation.
- Enumerate 2–5 competing hypotheses. Name specific files, functions, configs, input conditions, or invariants. Reject vague buckets ("backend issue"). If no serious alternative remains after a deliberate check, exit this differential and test or fix the sole evidenced cause directly; never fabricate a rival to continue the procedure.
- Name falsifiers and cheap observations before looking. For each hypothesis: what result drops it, and what read/grep/diff/log/test check can you run now. Prefer observations available immediately over deploys, canaries, or long waits.
- Rank observations by discrimination × cheapness. Run the cheapest check that best separates the top contenders. Do not deep-dive the favorite first if a cheap cross-check would kill alternatives.
- Update after each observation. Drop falsified hypotheses. Among survivors that still fit all evidence, prefer the one with the fewest independent unsupported assumptions (extra components, rare timing, external dependencies). Parsimony ranks survivors after fit; it never rescues a leaner hypothesis that evidence already contradicts. Escalate complexity only when simpler survivors are ruled out.
- Localize and stop. When one hypothesis has direct supporting evidence and key alternatives are ruled out, name the file/function/config to change and the evidence that localizes it. Stop analyzing once localization is direct.
Output
Symptom: <specific failing behavior, scope, timing>
Hypotheses:
H1: <specific cause> | Why plausible | Observation | Falsified if
H2: ...
H3: ...
Test order: <cheapest discriminating checks>
Results: <what each observation showed>
Survivors: <remaining Hs; least-assumptive working pick among fit>
Localized fault: <file/function/config + supporting evidence>
Ruled out: <Hs dropped and why>
Verification
- Falsify the differential conclusion if you continued with fewer than two serious hypotheses, if no pre-stated falsifier existed, if a cheaper discriminating check was skipped, or if a "simpler" story was kept after evidence contradicted it.
- Stop when the fault is directly localized and alternatives that matter are ruled out; do not continue theorizing.
- Over-application guard: do not narrate observe→question without competing causes; do not treat fewest assumptions as proof; do not run this skill when a single obvious cause is already evidenced.
Second-Order Consequence Chains
Do not stop at the intended first effect. Trace what happens next across actors, time, and feedback until the chain stops changing the decision.
When to Use
- Strategic, policy, incentive, or architecture choices with lasting coupling.
- The obvious fix feels too easy or has known backfire patterns.
- Success or scale would create new problems (load, gaming, debt).
- Need to compare options by delayed effects, not only day-one benefit.
When NOT to Use
- Local reversible edit with no incentive or cross-component coupling—just ship and observe.
- Full system structure (stocks, many loops, leverage ranking) is the goal—use systems.
- Pre-mortem of failure modes for a plan already chosen—use pre-mortem.
- Pure mechanical changes (rename, format) with no behavioral effect.
Procedure
- State decision and first-order effect. One sentence each: action and intended immediate result.
- Chain "and then what?" At least two further orders. For each link record: effect, who responds, rough probability (high/med/low), timing (immediate / next cycle / at scale), and whether it feeds back into the original problem (reinforce or counteract).
- Expand affected parties. Who else reacts (users, operators, other teams, attackers, markets)? What incentives does the change create or destroy?
- Scale test. Ask what happens if everyone does this or usage grows 10x. Mark paths that only appear under scale or repetition.
- Prune and decide. Drop speculative links that do not change the choice. Keep only effects that alter go/no-go, design, or mitigations. Revise the action or add guards where second-order harm exceeds first-order gain.
Stop when further "and then what?" no longer changes the decision, or the remaining chain is pure speculation without mechanism.
Output
decision: <action>
first_order: <intended immediate effect>
chain:
- order: 2
effect: <what>
actors: <who>
p: high|med|low
when: immediate|next_cycle|at_scale
feedback: none|reinforce|balance
- order: 3
...
scale_if_universal: <one sentence or n/a>
revised_decision: <same | modified action | no-go>
mitigations: <guards for kept risks>
Verification
- Falsify: If no credible second-order path changes the choice, first-order is enough—stop inventing cascades. If the core issue is multi-loop structure rather than one decision's trail, switch to systems.
- Stop: End at the first order that no longer affects the decision; do not pad to a fixed depth.
- Over-application guard: No low-probability sci-fi chains. No treating parameter tweaks as deep strategy. Probability and timing required on kept links; omit decoration without mechanism.
Socratic Questioning
Core rule: Surface the load-bearing assumption or undefined term before you build. Ask only what you cannot resolve yourself; stop when the next action is decision-ready.
When to Use
- Request is underspecified ("make it fast", "add a dashboard", "fix the bug") and a guess would misbuild.
- Claim rests on an unstated assumption that may be the real problem.
- Someone treats a premise as "obvious" or jumps to a solution before the problem is defined.
- Debugging a vague symptom that needs a checkable specific before investigation.
When NOT to Use
- Spec is already clear and actionable — do the work; do not interrogate for theater.
- Ambiguity is resolvable by reading code, running a command, or checking docs — resolve it yourself.
- Mid-execution of an agreed plan — re-questioning every step is friction, not rigor.
- Emergency where one load-bearing fact is enough to act — clarify that fact, then act (prefer ooda).
- You need the strongest opposing case, not clarification — use steel-manning.
- You need causal chain depth on a defined failure — use five-whys-plus or scientific-method.
Procedure
- Name the gap. State what is undefined, assumed, or uncheckable. If you can fill it from tools/repo without the user, do that and stop.
- Ask the load-bearing question first. Prefer one question whose answer most changes what you will build. Categories (use only what the gap needs):
- Clarification — "What does X mean / for whom / success looks like?"
- Assumption — "What must be true? What if it is false?"
- Evidence — "What supports this? What would disprove it?"
- Perspective — "Who is affected / who would disagree?"
- Implication — "What follows if we do this?"
- Meta — "Is this the right question?"
- Resolve or branch. From the answer, either (a) write the clarified requirement/decision and proceed, or (b) ask at most one follow-up that still gates the work. Do not run all six categories by default.
- Make assumptions explicit. Restate: "This assumes X; success means Y; out of scope is Z." Confirm only if still ambiguous after your restatement.
- Stop at decision-ready clarity. When the next action no longer depends on a hidden premise, end questioning and act or hand off. Cap user-facing questions tightly; prefer batching the few that truly gate work.
Output
gap: <what was vague or assumed>
resolved_by: self | user | mixed
questions_asked:
- <only questions actually needed>
assumptions_made_explicit:
- <X must be true / success = Y>
clarified_requirement: <decision-ready statement>
next_action: <build | investigate | re-scope | stop>
stop_reason: clear_enough | self_resolved | blocked_on_<fact>
Verification
- Falsify / stop: If answers do not change the plan, you asked non-load-bearing questions — stop interrogating. If the "clarification" is still a guess, do not build; name the remaining blocker.
- Over-application guard: Do not Socratic-interview a well-specified task. Do not outsource facts you can read or measure. Do not turn every step of execution into a new question round.
Steel-Manning
Core rule: Engage the best form of the opposing case, not a weak one. If your position survives that, reaffirm; if not, update.
When to Use
- About to reject a proposal, design, or alternative approach.
- Inclined to agree with the user/plan and risk sycophancy — construct the best case against first.
- Design review, architecture debate, or conflict where trade-offs are real.
- Validating your own preferred decision before locking it (strongest-countercase check).
When NOT to Use
- Settled fact, security anti-pattern, or violated hard requirement — correct it; do not invent a defense of what is wrong.
- You already agree for stated, weighed reasons — do not perform a fake debate.
- Trivial or fully reversible choices where deliberation cost exceeds downside.
- Live emergency — act first; steel-man in the post-incident review.
- Need definition/assumption cleanup, not opposition — use socratic.
- Need failure scenarios for a plan — use pre-mortem; need attacker paths — use red-team.
Procedure
- State the target claim or decision you are about to accept or reject, in one sentence. Name the real alternative if one exists.
- Extract the core insight behind the opposing position (or against your preferred path): the legitimate concern even if the proposed solution is wrong.
- Construct the strongest faithful case an informed advocate would make: best evidence, incentives, and failure modes — no mockery, no cherry-picked weak version, no motive attacks. Include base rates or concrete alternatives that could overturn the preferred path when relevant.
- State agreement / overturn conditions. Write one observation or result that would make you accept the opposing case (or abandon your preferred path), and whether you have looked for it.
- Engage that strong version, then decide. Respond to the steel-manned case on the merits. Output one of: accept opposing path, revise synthesis, or reaffirm original with explicit residual risks. Naming the countercase without accept/revise/reaffirm is incomplete. Stop once the decision updates or is reaffirmed with conditions.
Output
claim: <decision or proposal under test>
core_insight: <legitimate concern behind the opposition>
steel_man: <strongest faithful opposing argument>
overturn_if: <concrete observation that would change your mind>
looked_for_overturn: yes | no | partial
response_to_steel_man: <engagement on the merits>
decision: accept_opposing | revise | reaffirm
update: <what changed in belief or plan, or why reaffirm stands>
residual_risks: <what remains even after reaffirm/revise>
Verification
- Falsify / stop: If the "steel man" is weaker than the original or attacks a caricature, rebuild it. If no overturn condition is stated, the check is incomplete. If evidence meets the overturn condition, you must update — reaffirmation is then false.
- Over-application guard: Do not steel-man factual errors or hard constraints. Do not run a full adversarial brief for near-zero-cost reversible choices. Do not use this skill to delay an emergency response.
Systems Mapping and Leverage
Treat the problem as structure and interaction, not isolated parts. Map boundary, stocks/flows, loops/delays, and recurring patterns; intervene at the highest feasible leverage after a side-effect check.
When to Use
- Symptom spans services/components; single-stack fixes fail or bounce.
- A change in one place breaks another; behavior is emergent.
- Problem recurs despite local fixes (structure, not only symptom).
- Need to rank interventions when parameter/buffer tweaks do not stick.
When NOT to Use
- Single-component linear bug with clear stack/diff—trace and fix.
- Throughput limited by one obvious stage—use theory-of-constraints.
- Decision is a consequence chain of one proposed action—use second-order.
- Approach selection (plan vs probe vs stabilize)—use cynefin first.
Procedure
- Bound the system. Name purpose, actors, boundary, and in/out flows. Exclude noise outside the decision horizon; include any path that can feed the symptom.
- Map stocks and flows. List accumulating stocks (queue depth, debt, cache size, WIP) and the rates that fill/drain them. Note what changes slowly even when flows jump.
- Find feedback and delays. For each candidate loop: classify reinforcing (amplifies) vs balancing (resists); mark same-direction (+) vs opposite (-) links; name delays (TTL, deploy lag, metric lag, ramp-up). Even count of opposite links → reinforcing; odd → balancing. Long delay + strong correction → overshoot risk.
- Match recurring structure when problems return. Check only if recurrence or policy resistance is present; do not force a pattern:
- Fixes That Fail — quick fix, delayed worse side effect
- Shifting the Burden — workaround starves fundamental fix
- Limits to Growth — growth hits a balancing constraint
- Tragedy of the Commons — local optima deplete a shared stock
- Escalation — mutual reaction spiral
- Success to the Successful — advantage compounds via allocation
- Growth and Underinvestment — capacity lags demand until crisis If none fits after a genuine pass, keep the from-scratch map.
- Trace symptom to structure. Walk upstream along flows and loops; separate proximate symptom from structural driver (interaction, delay, wrong goal, missing info).
- Rank interventions by leverage, then side effects. Prefer higher feasible class: goals/paradigm → rules/information → loop structure (gain, balancing add, delay shorten) → stock/flow topology → buffers/parameters. For each candidate: feasibility, blast radius, delayed reversal risk. Prefer moves that cut harmful reinforcing gain or strengthen needed balancing loops without creating a new commons/escalation.
- Stop. Commit highest feasible intervention plus watch signals for loop/delay response. Re-map only if the structure changes or the intervention fails its watch.
Stop when boundary, key stocks/flows, dominant loop(s)+delay(s), optional archetype, and a ranked intervention with side-effect check are stated—or when the problem collapses to a single linear cause.
Output
boundary: <system purpose and edges>
stocks_flows: <stock → inflow/outflow list>
loops:
- name: <loop>
type: reinforcing | balancing
delay: <where cause lags effect>
links: <brief +/->
archetype: <name or none>
structural_driver: <one sentence>
interventions_ranked:
- level: <goals|rules|loops|structure|params>
action: <what>
side_effects: <feedback/elsewhere/delay risk>
chosen: <highest feasible>
watch: <signals that confirm or falsify>
Verification
- Falsify: If removing one component fully explains and fixes the issue with no cross-effects, systems mapping is wrong—drop to local debug. If utilization shows one fixed stage as the sole cap, switch to theory-of-constraints.
- Stop: Do not keep adding loops after the chosen intervention and watch are set.
- Over-application guard: No archetype without recurrence evidence. No low-leverage param tweak listed as primary when a feasible higher class exists. Do not recreate standalone archetype/feedback/leverage procedures—those checks live only inside this map.
Theory of Constraints
A throughput-limited system has one binding constraint. Improve only that constraint; local optimization of non-constraints wastes effort and often grows WIP.
When to Use
- Latency or throughput goal where one stage dominates time or rate.
- Work piles up before one stage; downstream idles.
- Adding capacity/workers elsewhere does not raise end-to-end output.
- Need ordered plan: exploit cheaply before spending to elevate.
When NOT to Use
- Load is spread; no stage dominates—use systems for interactions.
- Problem is correctness/fault, not flow rate—debug the fault.
- Bottleneck hops every run due to coupling/contention without a stable stage—systems or concurrency design, not five focusing steps.
- Constraint already known and a cheap fix is ready—apply it without ceremony.
Procedure
- Define the flow and goal. Name the unit of work (request, job, PR, record) and the metric that matters (end-to-end rate or latency).
- Identify the constraint with evidence. Compare stages on utilization, queue/wait, and throughput. Constraint signals: near-100% use, longest queue, lowest stage rate, work piles here, more input does not raise system output. Prefer measured rates over opinions. If two candidates tie, pick the one whose improvement would raise system throughput first.
- Exploit (no major spend). Maximize constraint output: cut idle, drop nonessential work on the constraint, reduce rework/setup, protect its time, improve quality at the constraint so output is not wasted. Estimate gain before spending.
- Subordinate non-constraints. Pace upstream to constraint rate; do not flood WIP. Make other stages serve the constraint (readiness, clarity, immediate pull). Reject local utilization targets that grow queues before the constraint.
- Elevate only if still short. After exploit is maxed, invest to raise constraint capacity (people, tooling, sharding, parallel path). Choose cheapest adequate elevation.
- Recheck (prevent inertia). After elevation or large exploit, remeasure all stages—the constraint often moves. Return to step 2. Do not keep optimizing the old constraint.
Stop when constraint, evidence, exploit plan, subordination rules, and elevate-or-not decision are explicit—or when no single stage binds (exit to systems).
Output
system_goal: <throughput/latency objective>
flow: <stage sequence>
constraint: <stage or resource>
evidence: <utilization / queue / rate facts>
exploit: <actions, expected gain>
subordinate:
- stage: <name>
change: <how it serves the constraint>
elevate: <none | option + cost/gain>
next_constraint_watch: <what to remeasure after change>
Verification
- Falsify: If raising the named stage cannot increase system throughput (another stage already caps), identification is wrong. If non-constraint optimizations change end-to-end rate, re-identify.
- Stop: Do not elevate before exploit is exhausted. Do not optimize multiple stages “just in case.”
- Over-application guard: One constraint at a time. Idle capacity upstream is not a problem to fill. Do not use TOC language for pure multi-loop emergence without a binding stage.
Thought Experiment
When empiricism is out of reach, run a disciplined counterfactual: one isolated change, fixed conditions, step-by-step mechanism, and a hard bound on implications.
When to Use
- You need behavior under failure, scale, or policy you cannot cheaply trigger or measure (region outage, 100x load, one-way architecture).
- A decision is expensive or irreversible and a mental trace can surface break points before commit.
- Edge cases are too costly to stage, but a mechanistic chain can still expose missing controls.
When NOT to Use
- A cheap real test exists (load test, flag, query, spike) → run the test; do not substitute imagination.
- Adversarial security attack-path work → use red-team structure, not free-form scenarios.
- You already know the mechanism and only need a decision under known facts → decide; do not dramatize.
- Vague "what if everything" brainstorming without a single isolated variable → tighten or stop.
Procedure
- State the question and isolation. Name exactly one primary variable or counterfactual change. Freeze all other conditions as the control world. Reject multi-variable "and also" scenarios.
- Fix initial conditions. Specify system state, load, configuration, actors, and what is not changed. Write values concrete enough that another agent could replay the setup.
- Trace the mechanism step by step. From t0, record what fails, queues, retries, or adapts next—and why—using known components and policies only. No hand-wavy "then everything collapses"; each step needs a causal link.
- Extract invariants and break points. Note what still holds (invariants) and the first step where the system violates a requirement (capacity, correctness, safety, UX). Mark assumptions that, if false, void the chain.
- Bound implications. Map insights only to actions or checks justified by the chain (limits, guards, monitoring, redesign). Label speculative leaps beyond the isolation as out of bound.
- Name a discriminating real check, then stop. For the weakest link, state the cheapest observation or experiment that would confirm or kill it. Stop after one controlled chain with bounded implications; if a link is cheaply testable now, exit to that test instead of further imagination.
Output
Emit a thought-experiment record:
question: what behavior or decision is under testisolated_variable: single change vs control worldinitial_conditions: frozen state and non-changesconsequence_chain: ordered mechanistic stepsinvariants: what still holdsbreak_points: first requirement failures and critical assumptionsimplication_bound: actions/checks justified by the chain onlydiscriminating_check: cheapest real observation to confirm or kill the weak link
Verification
- Isolation check: more than one free variable without a stated control → invalid; reset.
- Mechanism check: any step without a causal link to a known component/policy → rewrite or drop.
- Implication bound: recommendations not entailed by the chain are out of scope.
- Empiricism override: if a real test became available mid-analysis, stop the thought experiment and test.
- Over-application guard: do not use this skill for ordinary debugging you can reproduce, or as a substitute for red-team threat modeling.
- Stop: one isolated counterfactual → full chain → bounded implications + discriminating check; no scenario sprawl.
TRIZ
Resolve technical design contradictions without midpoint compromise. Name the conflict, separate the opposing states, and transform the system so both benefits hold.
When to Use
- Architecture, API, or system parameters pull in opposite directions (stable vs evolving, fresh vs cached, strict vs frictionless).
- You are about to accept a trade-off because "you can't have both."
- Every candidate solution shares the same structural weakness—the conflict is in the requirements, not the options list.
When NOT to Use
- One option is simply better under stated constraints → pick it; do not manufacture a contradiction.
- A cheap measurement shows which side actually matters → measure instead of inventing a separation.
- A standard pattern already resolves it (cache-aside, CQRS, feature flags, versioning) → apply the pattern directly.
- Non-technical people/org conflicts → out of scope; separation targets system parameters.
- Ordinary prioritization or resource allocation without opposing states of the same parameter.
Procedure
- Name the contradiction in template form. Write: "We need [PARAMETER] to be [STATE_1] for [BENEFIT_1] BUT [STATE_2] for [BENEFIT_2]." If this form fails, stop—use another method.
- State the ideal final result (IFR). Describe both benefits held with minimal new machinery and no permanent midpoint sacrifice.
- Try separation before invention. Test, in order: time (different moments), space (different components/layers), condition (context, load, risk), scale (interface vs implementation, aggregate vs element). Keep the first separation that delivers both benefits without hidden compromise.
- If separation fails, apply an inventive transform. Prefer resource-light moves: segmentation, preliminary action, inversion (push/pull), intermediary, copying/replication, dynamization (flags/config), another dimension (metadata/versioning/events). Scan only principles that map to the named parameter conflict.
- Reuse existing resources first. Before adding services or stores, check data, traffic, headers, schedulers, and side effects already present that can carry the separation.
- Lock a concrete resolution and stop. Specify the design change, where each state lives, and how both benefits are preserved. Stop when a no-compromise design is stated, or when honest analysis shows only a constrained trade-off remains—then document the residual trade-off explicitly rather than forcing TRIZ theater.
Output
Emit a TRIZ resolution:
contradiction: parameter / state_1+benefit_1 / state_2+benefit_2ideal_final_result: both benefits without permanent compromiseseparation_tried: time | space | condition | scale → result eachinventive_move: principle or pattern used if separation alone was insufficient (or none)resources_reused: existing capabilities leveragedresolution: concrete design decision and where each state holdsresidual_tradeoff: none, or the honest remaining compromise
Verification
- Template gate: if the contradiction cannot be written in the required form, do not apply TRIZ.
- No-compromise check: a pure midpoint on the trade-off curve without a separation or inventive move is a failed application.
- Separation-first: principles without attempted time/space/condition/scale separation are incomplete.
- Over-application guard: if measurement or a standard pattern settles the design, skip TRIZ.
- Stop: one named contradiction → separation/inventive pass → concrete resolution; do not cycle principles as decoration.
Via Negativa
Improve by subtraction before addition. Prefer removing harm, waste, and nonessential complexity; add only when a demonstrated need remains after removal candidates are exhausted.
When to Use
- About to add a feature, abstraction, dependency, process, or control to fix a problem.
- Simplifying a system or workflow where complexity is the tax.
- Prioritizing by deciding what not to keep, build, or maintain.
- Performance or reliability work where eliminating a bad path beats bolting on mitigation.
When NOT to Use
- Load-bearing controls: auth, validation, tests, rate limits, retries, safety checks — presume necessary until proven dead.
- A demonstrated requirement that cannot be met by removal or simplification.
- Aesthetic minimalism without evidence of non-use or net harm.
- Irreversible deletion without a rollback path when impact is unknown.
Procedure
- Pause the add reflex. State the goal and the proposed addition in one line.
- Ask the subtraction question first. List what could be removed or stopped to achieve the same goal with less surface area.
- Catalog candidates with evidence. Prefer unused, redundant, high-cost/low-value, or harmful elements. Require usage, call-graph, metrics, or experiment evidence — not taste.
- Apply the irreversibility guard. Classify reversible vs hard-to-restore; identify dependents; refuse deleting unproven mystery guards. Plan staged removal or flag when risk is non-trivial.
- Remove the safest high-value candidate first. Subtract, monitor, and verify absence of needed behavior before the next removal.
- Add only if the goal still fails. If subtraction cannot meet the need, add the minimum change and record why removal was insufficient.
- Stop when the goal is met by absence, or remaining candidates fail the irreversibility/evidence bar and a minimal addition is justified.
Stop condition: Goal achieved via removal, or residual need documented after evidence-backed subtraction failed.
Output
Goal: <desired outcome>
Proposed add (if any): <thing>
Removal candidates: <element — evidence — risk — reversible?>
Action: remove <X> | staged remove <X> | add minimal <Y> because <why removal failed>
Verification plan: <how absence/success is checked>
Do-not-touch: <load-bearing items preserved>
Verification
- Falsify if something was deleted without non-use/harm evidence, or a safety control was removed as "complexity."
- Falsify if an addition shipped without a prior subtraction pass on the same goal.
- Over-application guard: do not delete for line-count or purity when the element is load-bearing or the need is demonstrated.
Sponsors
Details
- Marketplace
- tjboudreaux/cc-thinking-skills
- Category
- Productivity