fatby/structured-reasoning

--- name: structured-reasoning description: Multi-mode structured reasoning with GPT-5.2 thinker for Type 1 decision validation metadata: {"clawdbot":{"always":true,"emoji":"🧠"}} --- # Structured Reasoning Skill Use this skill for complex decisions, especially Type 1 irreversible decisions. ## The Engineering Flywheel for Decisions All structured reasoning follows the 8-phase Engineering Flywheel: ### Phase 1: Problem Framing (Requirements) Define the decision through clear requirements: - What is the success criteria? (the outcome, not the solution) - What are the hard constraints? (time, money, reversibility, dependencies) - What does "done" look like? (specific, testable) - What would failure look like? (to avoid) Output: Clear decision objective with measurable success criteria ### Phase 2: Context Gathering (AS-IS State) Map the current state: - Read relevant files, data, prior decisions (memory_search) - Understand what currently exists and WHY - Gather market/competitor/customer context - Review constraints and dependencies Output: Complete picture of current reality ### Phase 3: First Principles (Deconstruct) Break down to fundamentals: 1. Identify assumptions - List everything being assumed. Challenge each one. - "Why do we believe this?" - "Is this actually true, or just conventional wisdom?" - "What if the opposite were true?" 2. Find bedrock truths - What do we KNOW to be true? - Separate facts from interpretations - Separate data from narratives - Identify what's measurable vs. opinion 3. Expose the real problem - Why does this decision need to be made? - "What problem are we actually solving?" - "Why does this problem exist?" - "What's wasteful in the current approach?" 4. Build up from basics - Don't reason by analogy - Build from first principles ("given these truths, what logically follows?") - Question "best practices" - they're someone else's solution Output: - Assumptions challenged: [list] - Bedrock truths: [list] - Real problem: [statement] - Waste identified: [what's unnecessary] ### Phase 4: Creative Synthesis (TO-BE Solution) Generate options from first principles: - Build 2-4 options from fundamentals (not by analogy) - Each option should honor constraints and truths - Design the simplest path for each option - Don't constrain to "how it's usually done" Output: 2-4 viable options with rationale ### Phase 5: Validation & Delete (Prune + Validate) Test options and prune complexity: - Does each option actually meet requirements? - What can we delete and still succeed? - Which option is simplest while meeting all constraints? - Spawn @thinker for Type 1 decisions (see Thinker Integration) Output: Pruned options + thinker validation (if Type 1) ### Phase 6: Execute (Decision) Make the call: - DECISION: Clear statement - CONFIDENCE: High/Medium/Low - RATIONALE: Why this option (reference flywheel phases) ### Phase 7: Review (Verification) Set review criteria: - NEXT ACTION: Specific first step - REVIEW TRIGGER: When to revisit this decision - SUCCESS METRICS: How we'll know if it worked ### Phase 8: Update Memory Capture learnings: - Update MEMORY.md with decision and rationale - Log to daily notes - Document pattern for future similar decisions --- ## The Flywheel for Decisions Problem Framing → Context Gathering → First Principles → Creative Synthesis ↓ ↓ Update Memory ← Review ← Execute ← Validation & Delete (+ Thinker for Type 1) All decisions flow through 8 phases. Depth varies by mode. ## Auto-Trigger Conditions Automatically invoke this skill when: - Type 1 decisions: contracts, partnerships, major purchases, architecture choices - Multi-factor analysis: comparing options with tradeoffs - Debugging: something failed and the cause is not obvious - Strategy/planning: business decisions, offer architecture, campaign planning - Disagreement or conflict: weighing competing perspectives Do NOT use for: simple factual questions, quick tasks, low-stakes decisions, or when a simple heuristic exists. ## Modes (Depth Levels) ### Mode 1: Light (~3 mins) - Quick flywheel: phases 1, 4, 6, 8 - For reversible decisions with limited impact - "Good enough" decisions ### Mode 2: Standard (~10 mins) - Full 8-phase flywheel - For important but reversible decisions - Includes basic validation ### Mode 3: Deep (~30+ mins) - Full 8-phase flywheel with @thinker validation - For Type 1 irreversible decisions - Spawns parallel thinker sessions for validation - Includes stakeholder alignment ## Thinker Integration For Type 1 decisions, spawn @thinker sessions: Spawn thinker with prompt: "You are a critical validator. Review this decision analysis. Role-play as [stakeholder persona]. Find flaws, blind spots, and risks I missed. Be brutally honest." Thinker sessions should: 1. Adopt opposing viewpoints 2. Stress test assumptions 3. Identify edge cases 4. Probe for confirmation bias 5. Suggest alternative interpretations ## Specialized Workflows ### A/B Testing Design 1. Frame: What hypothesis are we testing? 2. Design: Create statistically valid experiment 3. Implementation: How to deploy and measure 4. Analysis: How to interpret results ### Debugging Workflow 1. Symptom: What's broken? 2. Scope: Where could the problem be? 3. Root cause: Why did it break? 4. Fix: How to resolve permanently? ### Strategy Planning 1. Vision: Where do we want to be? 2. Current reality: Where are we now? 3. Options: How do we get there? 4. Selection: Which path is best? 5. Execution: First steps ## Tools & Integration - memory_search: Recall similar past decisions - sessions_spawn: Create thinker sessions - web_search: Gather external context - read_file: Access documentation - write_file: Record decisions and learnings ## Examples ### Example 1: Software Architecture Decision Mode: Deep (Type 1 decision) Process: 1. Framed: "Choose between microservices vs monolith for new SaaS platform" 2. Gathered: Team size, deployment infrastructure, expected scale 3. First principles: Challenged "microservices are always better" assumption 4. Created 3 options with tradeoffs 5. Spawned thinker sessions: developer experience, operations, business risk 6. Decision: Start with modular monolith, plan for future split 7. Review trigger: When reaching 10k active users ### Example 2: Hiring Decision Mode: Standard Process: 1. Framed: "Which candidate to hire for senior backend role?" 2. Gathered: Team needs, project requirements, cultural fit 3. First principles: Separated "impressive resume" from "actual skills needed" 4. Created comparison matrix 5. Decision: Candidate B (better technical match) 6. Review: 90-day probation period assessment ## Performance Notes - Speed vs Quality: Mode 1 for speed, Mode 3 for quality - Decision Fatigue: Use Mode 1 for trivial decisions - Stakeholder Alignment: Use thinker sessions to incorporate diverse perspectives - Documentation: Always update MEMORY.md for knowledge retention ## Related Skills - diverse-ideation: For brainstorming options - risk-analysis: For risk assessment - project-planning: For execution planning - communication: For stakeholder alignment