@polderlabs/bizar 10.7.0 → 10.7.2

package/.claude/skills/thinking-scientific-method/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: thinking-scientific-method
+description: Use when a symptom could have several causes and you must find the faulty code by ranking falsifiable hypotheses and checking the cheapest discriminating observation first.
+---
+
+# Hypothesis-Differential Debugging
+
+## Overview
+
+The scientific method's payoff for an agent is not narrating "observe -> question." It is the **differential**: when a symptom could come from several places, enumerate competing falsifiable hypotheses and spend your cheapest observation on the one that best discriminates between them.
+
+This is the proven replacement for the old broad scientific-method skill. In SWE-bench fault localization, the original was flat; this agent-native version turned it into the strongest measured debugging lift in the current eval set.
+
+**Core Principle:** Don't guess-and-patch. Enumerate competing causes, then make the cheapest observation that would falsify the most likely one.
+
+## When to Use
+
+- A bug or incident symptom could plausibly come from more than one place
+- You have read access to code, logs, diffs, traces, or tests
+- You need to localize the faulty file, function, branch, config, or invariant before fixing
+
+```
+Symptom has several plausible causes?
+  -> no  -> test or fix the obvious cause directly
+  -> yes -> can you make cheap observations now?
+       -> no  -> gather access/evidence first
+       -> yes -> apply hypothesis-differential debugging
+```
+
+## When NOT to Use
+
+- The cause is already obvious from a single trace, failing test, or recent diff -> fix directly.
+- Only one plausible hypothesis exists -> test it directly.
+- You cannot make any observation -> get access first; don't speculate.
+- You are designing an A/B test, canary, or multi-week experiment -> this skill is for observations an agent can make now.
+
+## The Procedure
+
+### Step 1: Enumerate competing hypotheses
+
+List 3-5 specific, falsifiable hypotheses. Name the likely file, function, subsystem, input condition, or invariant. Avoid vague buckets like "backend issue" or "race condition somewhere."
+
+```markdown
+| # | Hypothesis | Why plausible? |
+|---|------------|----------------|
+| H1 | `auth/session.py:refresh` drops rotated tokens | failures start after token rotation |
+| H2 | cache TTL mismatch in `session_cache` | stale sessions persist across deploys |
+| H3 | frontend retries reuse expired cookie | only browser flow is affected |
+```
+
+If you can only think of one hypothesis, you are guessing. Force alternatives before inspecting deeper.
+
+### Step 2: Name the cheapest discriminating observation
+
+For each hypothesis, name one observation you can make now that would separate it from the others.
+
+Good observations:
+- read the function the stack trace names
+- grep callers of a parser or config key
+- inspect the recent diff touching the failing path
+- compare two log lines across working and broken cases
+- check a test fixture or schema invariant
+
+Bad observations:
+- deploy a canary
+- run a long experiment
+- ask users to wait
+- inspect every file in the subsystem
+
+### Step 3: State falsifiers before looking
+
+For each hypothesis, write what result would make you drop it. This prevents confirmation search.
+
+```markdown
+| Hypothesis | Falsified if... |
+|------------|-----------------|
+| H1 token refresh | refresh path never reads rotated token state |
+| H2 cache TTL | cache entry expires before the observed stale window |
+| H3 frontend retry | same failure occurs in API-only reproduction |
+```
+
+### Step 4: Rank by likelihood x cheapness
+
+Test the observation with the best expected information per unit of effort. Start with the cheapest observation that separates your top hypotheses, not the most elaborate investigation.
+
+```
+For each hypothesis → name falsifier → rank by likelihood x cheapness → observe → update/drop → localize fault
+```
+
+### Step 5: Stop on direct localization
+
+Stop when one hypothesis is supported by direct evidence and the key alternatives are ruled out. Name the file/function/config to change and the evidence that localizes it.
+
+## Investigation Template
+
+```markdown
+## Symptom
+[Specific failing behavior, scope, timing, and known constraints]
+
+## Hypotheses
+| # | Hypothesis | Why plausible? | Cheapest observation | Falsified if... |
+|---|------------|----------------|----------------------|-----------------|
+| H1 | [specific file/function/config cause] | [evidence] | [read/grep/diff/check] | [drop condition] |
+| H2 | [specific alternate cause] | [evidence] | [read/grep/diff/check] | [drop condition] |
+| H3 | [specific alternate cause] | [evidence] | [read/grep/diff/check] | [drop condition] |
+
+## Test Order
+1. [Cheapest discriminating observation]
+2. [Next observation if H1 is falsified]
+3. [Deferred only if cheap observations do not localize]
+
+## Localization
+[Supported hypothesis, ruled-out alternatives, and the file/function/config to change]
+```
+
+## Worked Shape
+
+```markdown
+Symptom: intermittent 500s on /export, only eu-west, started three days ago.
+
+Hypotheses:
+1. recent diff to export serializer
+   Observation: inspect commits touching `export_serializer`
+   Falsified if: no diff touches the failing codepath
+2. eu-west Redis rotation broke a cache key
+   Observation: read cache key construction + region config
+   Falsified if: key and TTL match healthy regions
+3. upstream timeout under load
+   Observation: compare timeout logs during failure window
+   Falsified if: no upstream latency spike
+
+Test order: H1, H2, H3.
+Result: H1 diff changed nested export handling and matches stack trace.
+Localized fault: `app/export/serializer.py`.
+```
+
+## Anti-Patterns
+
+- Narrating the scientific method without proposing competing causes
+- Looking only for evidence that supports your first guess
+- Calling an expensive experiment a "test" when a cheap observation exists
+- Stopping at a plausible explanation before ruling out alternatives
+- Continuing to analyze after the faulty file/function is localized
+
+## Verification Checklist
+
+- [ ] Listed 3-5 specific hypotheses
+- [ ] Each hypothesis has a cheap observation available now
+- [ ] Each hypothesis has a stated falsifier
+- [ ] Observations are ranked by likelihood x cheapness
+- [ ] Final answer names the localized file/function/config and the evidence
+
+## Key Questions
+
+- What would I see if this hypothesis were false?
+- Which observation best separates the top two hypotheses?
+- Am I testing a hypothesis or confirming my first guess?
+- Can I localize the fault with a cheaper observation?
+
+## Feynman's Wisdom
+
+"The first principle is that you must not fool yourself - and you are the easiest person to fool." Your intuition generates hypotheses; the differential tests them.

package/.claude/skills/thinking-second-order/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: thinking-second-order
+description: When a change has effects past the immediate fix (incentives, scale, feedback loops), ask "and then what?" across horizons before committing — the obvious fix often backfires downstream.
+---
+
+# Second-Order Thinking
+
+## Overview
+Second-order thinking, articulated by Howard Marks, moves beyond immediate effects to consider what happens next, and what that leads to. First-order thinking is simplistic ("This action solves the problem"); second-order thinking asks "And then what?" repeatedly.
+
+**Core Principle:** The obvious answer to "What should I do?" is often wrong because it ignores downstream effects.
+
+## When to Use
+- Making strategic or architectural decisions
+- Evaluating policy or process changes
+- Considering incentive structures
+- Planning features that change user behavior
+- Decisions with long-term consequences
+- When the "obvious" solution feels too easy
+
+Decision flow:
+```
+Decision with consequences beyond immediate? → yes → APPLY SECOND-ORDER THINKING
+                                            ↘ no → First-order may suffice
+```
+
+## When NOT to Use
+- The change is local and reversible (a two-way door) with no downstream coupling — just make it and observe.
+- The first-order fix is also the correct one and the chain is obvious; don't manufacture speculative cascades.
+- You'd be inventing implausible third- and fourth-order effects to seem thorough — stop at the first effect that actually changes the decision.
+- Pure mechanical edits (rename, format, dependency bump) with no behavioral or incentive change.
+
+## First vs Second-Order Thinking
+
+| Situation | First-Order | Second-Order |
+|-----------|-------------|--------------|
+| Team is slow | Add more engineers | More engineers → more coordination → slower decisions → may get slower |
+| Users complain | Add the feature they request | Feature → complexity → more support load → less time for core work |
+| Costs too high | Cut spending | Cuts → reduced quality → customer churn → revenue drop → worse situation |
+| Bug in prod | Hotfix immediately | Hotfix → skip testing → more bugs → trust erosion → slower deployments |
+
+## The Process
+
+### Step 1: Identify the Decision and First-Order Effect
+```
+Decision: Add a feature flag system
+First-order: Teams can ship features independently ✓
+```
+
+### Step 2: Ask "And Then What?"
+Chain the consequences:
+```
+Feature flags → More flags created → Flag debt accumulates
+             → Teams don't clean up → Combinatorial testing complexity
+             → Bugs from flag interactions → "Turn it off" becomes risky
+             → Flags become permanent → Codebase complexity explodes
+```
+
+### Step 3: Evaluate Across Engineering Horizons
+Trace the effect at three concrete horizons (not emotional ones):
+
+| Horizon | Question | Analysis |
+|---------|----------|----------|
+| Immediate | What happens on the next request/run? | Problem solved—flag ships the feature |
+| Next deploy / weeks | What does the team do because of this? | Flag sprawl, more flags created |
+| At scale / months+ | Where does the trajectory lead at 10x usage or adoption? | Combinatorial flag debt, fragile codebase |
+
+### Step 4: Consider Systemic Effects
+Ask: "What if everyone did this?"
+```
+Decision: Skip code review for urgent fixes
+If everyone: All urgent fixes skip review
+Result: Definition of "urgent" expands → most things skip review
+Outcome: Quality collapses, more urgent fixes needed
+```
+
+### Step 5: Map the Consequence Chain
+```
+┌─────────────────┐
+│ Decision: X     │
+└────────┬────────┘
+         ▼
+┌─────────────────┐
+│ 1st Order: A    │ ← Obvious, intended
+└────────┬────────┘
+         ▼
+┌─────────────────┐
+│ 2nd Order: B    │ ← Less obvious
+└────────┬────────┘
+         ▼
+┌─────────────────┐
+│ 3rd Order: C    │ ← Often counterintuitive
+└────────┬────────┘
+         ▼
+┌─────────────────┐
+│ Feedback Loop   │ ← May reinforce or counteract
+└─────────────────┘
+```
+
+## Common Second-Order Effects in Software
+
+### Optimization
+```
+1st: Optimize critical path → Faster
+2nd: Team focuses on optimization → Less feature work
+3rd: Premature optimization spreads → Complexity increases
+4th: Maintenance burden grows → Slower overall
+```
+
+### Hiring
+```
+1st: Hire senior engineers → More capacity
+2nd: Salary expectations rise → Budget pressure
+3rd: Junior engineers feel stuck → Attrition
+4th: Knowledge concentrated in seniors → Bus factor risk
+```
+
+### Process Addition
+```
+1st: Add approval process → More oversight
+2nd: Approvals create bottleneck → Slower delivery
+3rd: People route around process → Shadow processes
+4th: Formal process becomes theater → Worst of both worlds
+```
+
+### Technical Shortcuts
+```
+1st: Skip tests to ship faster → Feature delivered
+2nd: Bugs emerge → Support load increases
+3rd: Team fights fires → Less time for features
+4th: More shortcuts taken → Quality death spiral
+```
+
+## Application Framework
+
+For any significant decision, fill out:
+
+```markdown
+## Second-Order Analysis: [Decision]
+
+### Immediate Effect (1st Order)
+[What happens right away]
+
+### Near-Term Consequences (2nd Order)
+[What does the immediate effect cause? 1-3 months]
+
+### Medium-Term Consequences (3rd Order)  
+[What do the near-term effects cause? 3-12 months]
+
+### Long-Term Trajectory
+[Where does this path lead? 1+ years]
+
+### Feedback Loops
+[Does this create reinforcing or balancing dynamics?]
+
+### If Scaled
+[What happens if this becomes standard practice?]
+
+### Revised Decision
+[Given analysis, what should we actually do?]
+```
+
+## Questions to Surface Second-Order Effects
+- "And then what?"
+- "Who else is affected, and how will they respond?"
+- "What incentives does this create?"
+- "What behavior does this encourage/discourage?"
+- "If this works, what problems does success create?"
+- "What will we wish we had done differently in a year?"
+- "What does this look like if everyone does it?"
+
+## Verification Checklist
+- [ ] Identified first-order effect clearly
+- [ ] Asked "and then what?" at least 3 times
+- [ ] Traced effects across immediate / next-deploy / at-scale horizons
+- [ ] Considered systemic/scaled effects
+- [ ] Identified potential feedback loops
+- [ ] Revised decision based on full consequence chain
+- [ ] Documented reasoning for future reference
+
+## Marks' Warning
+"First-level thinking is simplistic and superficial, and just about everyone can do it. Second-level thinking is deep, complex, and convoluted."
+
+The crowd uses first-order thinking. Competitive advantage comes from thinking one level deeper—seeing what happens after the obvious effect.

package/.claude/skills/thinking-socratic/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: thinking-socratic
+description: Use before building when a request is vague, assumption-laden, or "obvious." Ask the clarifying questions that surface hidden requirements and false premises instead of guessing.
+---
+
+# Socratic Questioning
+
+## Overview
+The Socratic Method, developed by the ancient Greek philosopher Socrates, uses systematic questioning to stimulate critical thinking and illuminate ideas. Rather than providing answers, it draws out knowledge by challenging assumptions and exploring implications.
+
+**Core Principle:** A vague or assumption-laden request is cheaper to clarify than to misbuild. The right question up front surfaces the hidden requirement or false premise that would otherwise be discovered only after the work is done.
+
+Use this as a **pre-build clarification tool**: when a task is underspecified, ambiguous, or rests on an unstated assumption, ask the targeted question before writing code or committing to an approach — don't fill the gap with a guess.
+
+## When to Use
+- A request is vague ("make it fast", "add a dashboard", "fix the bug") and you'd otherwise guess the spec
+- The request rests on an unstated assumption that might be the actual problem
+- Someone asserts something is "obvious" or "everyone knows" — exactly when premises go unchecked
+- A proposal jumps to a solution before the problem is defined
+- Debugging, to trace a claim ("the system is slow") back to a checkable specific
+
+Decision flow:
+```
+About to build/commit on an underspecified request? → yes → ASK CLARIFYING QUESTIONS FIRST
+Request rests on an unexamined assumption?           → yes → PROBE THE ASSUMPTION
+Stated problem is a vague symptom?                   → yes → QUESTION DOWN TO A SPECIFIC
+```
+
+## When NOT to Use
+- **The request is already clear and specified.** Don't interrogate a well-defined task — just do it. Question-asking theater wastes the user's time.
+- **You can answer the question yourself by checking.** If the ambiguity is resolvable by reading the code, running a command, or consulting the docs, do that instead of asking the user.
+- **During execution of an agreed plan.** Clarify before building; once the spec is settled, stopping to re-question every step is friction, not rigor.
+- **A genuine emergency / time-pressured incident** where acting on 70% understanding beats a round of questions — clarify the one thing that's load-bearing, then act.
+
+## The Six Types of Socratic Questions
+
+### 1. Clarification Questions
+**Purpose:** Ensure clear understanding of the claim or concept
+
+| Question | Use When |
+|----------|----------|
+| "What do you mean by X?" | Term is ambiguous |
+| "Can you give me an example?" | Concept is abstract |
+| "How does this relate to Y?" | Connection unclear |
+| "Can you rephrase that?" | Statement is confusing |
+| "What is the main point?" | Discussion is scattered |
+
+**Example:**
+> "The system needs to be fast."
+> → "What do you mean by 'fast'? What latency is acceptable?"
+> → "Fast for whom? End users? Batch processes?"
+
+### 2. Assumption-Probing Questions
+**Purpose:** Expose underlying beliefs that may be unexamined
+
+| Question | Use When |
+|----------|----------|
+| "What are we assuming here?" | Conclusion seems too pam |
+| "Is this always true?" | Generalization made |
+| "What if that assumption is wrong?" | Testing robustness |
+| "Why do we believe this?" | Basis unclear |
+| "What would have to change for this to be false?" | Finding conditions |
+
+**Example:**
+> "We need microservices for scale."
+> → "What are we assuming about our scale requirements?"
+> → "Is it always true that microservices scale better?"
+> → "What if a modular monolith could meet our needs?"
+
+### 3. Reason & Evidence Questions
+**Purpose:** Examine the support for a claim
+
+| Question | Use When |
+|----------|----------|
+| "What evidence supports this?" | Claim is asserted |
+| "How do we know this?" | Source unclear |
+| "Are there other explanations?" | Causation assumed |
+| "What would prove this wrong?" | Testing falsifiability |
+| "Is this evidence sufficient?" | Conclusion seems strong |
+
+**Example:**
+> "Users don't want feature X."
+> → "What evidence do we have for this?"
+> → "How many users did we ask? How were they selected?"
+> → "Could there be other explanations for the feedback?"
+
+### 4. Perspective & Viewpoint Questions
+**Purpose:** Consider alternative angles and stakeholders
+
+| Question | Use When |
+|----------|----------|
+| "How would X see this?" | Single perspective dominates |
+| "What's the opposite view?" | No alternatives considered |
+| "Who disagrees, and why?" | Consensus seems too easy |
+| "What are we not seeing?" | Blind spots suspected |
+| "How does this look from [role]?" | Stakeholder impact unclear |
+
+**Example:**
+> "This API design is intuitive."
+> → "How would a new developer view this?"
+> → "What would someone from a different language background expect?"
+> → "Who might find this confusing, and why?"
+
+### 5. Implication & Consequence Questions
+**Purpose:** Explore downstream effects and logical conclusions
+
+| Question | Use When |
+|----------|----------|
+| "What follows from this?" | Implications unexplored |
+| "If this is true, what else must be true?" | Testing consistency |
+| "What are the consequences?" | Impact unclear |
+| "How does this affect X?" | Ripple effects not considered |
+| "What are the second-order effects?" | Only immediate effects seen |
+
+**Example:**
+> "We'll add this field to the API response."
+> → "What follows from adding this field?"
+> → "How does this affect clients that don't need it?"
+> → "What are the implications for backward compatibility?"
+
+### 6. Questions About the Question
+**Purpose:** Reflect on the inquiry itself; meta-level examination
+
+| Question | Use When |
+|----------|----------|
+| "Why is this question important?" | Purpose unclear |
+| "What would answering this tell us?" | Value of question unclear |
+| "Is this the right question?" | May be missing the point |
+| "What question should we be asking?" | Reframing needed |
+| "Why are we asking this now?" | Timing or priority unclear |
+
+**Example:**
+> "Which database should we use?"
+> → "Why is this question important right now?"
+> → "What would answering this tell us that we don't know?"
+> → "Is the real question about database, or about data modeling?"
+
+## Application Patterns
+
+### For Requirements Gathering
+```
+Stakeholder: "We need a dashboard."
+Clarification: "What decisions will the dashboard help you make?"
+Assumptions: "What are we assuming about who will use this?"
+Evidence: "What data shows this is the highest priority?"
+Perspective: "How do different user roles need different views?"
+Implications: "If we build this, what won't we build?"
+Meta: "Is a dashboard the best solution, or is there another approach?"
+```
+
+### For Debugging
+```
+Report: "The system is slow."
+Clarification: "Which operations are slow? How slow?"
+Assumptions: "What are we assuming about where the bottleneck is?"
+Evidence: "What metrics/traces support this?"
+Perspective: "Is it slow for all users or specific patterns?"
+Implications: "If we fix this, what else might change?"
+Meta: "Is 'slow' the right frame? Could it be 'inconsistent'?"
+```
+
+### For Design Review
+```
+Proposal: "We should use event sourcing."
+Clarification: "What do you mean by event sourcing in this context?"
+Assumptions: "What are we assuming about our query patterns?"
+Evidence: "What evidence suggests this fits our use case?"
+Perspective: "How would ops view this? New team members?"
+Implications: "What are the consequences for debugging? Storage?"
+Meta: "Is the real question about event sourcing or auditability?"
+```
+
+## How to Ask Well
+- **Ask the load-bearing question first**: lead with the one whose answer most changes what you'll build.
+- **One or two questions, not an interrogation**: batch the few that actually gate the work; don't run all six categories for show.
+- **Follow the thread**: let each answer narrow the next question instead of working from a fixed script.
+- **Resolve what you can yourself**: only ask the user what you can't determine by reading the code, running a command, or checking the docs.
+- **Make the assumption explicit**: "This assumes X — is that right?" beats silently guessing X.
+
+## Verification Checklist
+- [ ] Used questions from at least 3 of the 6 categories
+- [ ] Probed assumptions underlying the topic
+- [ ] Explored at least one alternative perspective
+- [ ] Examined implications and consequences
+- [ ] Reached deeper understanding than starting point
+- [ ] Documented key insights from questioning
+
+## Key Meta-Questions
+- "What do I think I know, and how do I know it?"
+- "What question am I not asking?"
+- "What would change my mind about this?"
+- "Who knows more about this than I do?"
+- "What's the question behind the question?"
+
+## Socrates' Reminder
+"I know that I know nothing."
+
+The goal is not to prove others wrong but to discover truth together. The best questions reveal what everyone—including the questioner—doesn't yet understand.