skill-systems-thinking 0.1.0

package/references/stability.md

@@ -0,0 +1,97 @@
+# Reference: Stability
+
+Book anchors: §1.1 (constant-coefficient linear systems), §4.1 (Lyapunov stability definition
+and direct method), §1.3 (nonlinear systems have multiple equilibria).
+
+## Stability is the first requirement
+
+(§1.1) For a control system, stability is demanded *before* anything else. A program that
+gives the right answer *sometimes* but diverges, hangs, leaks, or corrupts state under
+perturbation is **unstable** — and therefore useless, however clever.
+
+### Lyapunov definition (§4.1), in plain terms
+
+A motion is *stable* if: for any tolerated deviation ε > 0, there exists a δ > 0 such that,
+whenever the initial state starts within δ of the target, the trajectory stays within ε of the
+target for all t ≥ t₀. *Asymptotically stable* if it also converges back to the target.
+
+- Translate: **small perturbations must produce bounded deviation, not runaway.**
+- "For all t" matters. A system that looks fine for 5 minutes then explodes is not stable.
+
+## LLM behavior pattern: Stability before everything
+
+> "A system that diverges under perturbation is wrong, however clever the optimization."
+
+The LLM using this skill **must** verify stability before proposing any feature or
+optimization. This is not a suggestion; it is the second cognitive law.
+
+- Before generating performance optimizations, the LLM must reason: "Is the base system
+  stable under perturbation? If not, I reject the optimization and fix stability first."
+- Perturbations to consider: empty input, huge input, null, concurrent calls, network flake,
+  dependency down, clock skew.
+
+### Test for stability, not just correctness
+
+- Probe with **perturbations**, not only golden paths: empty input, huge input, null,
+  concurrent calls, network flake, one dependency down, clock skew.
+- If deviation **grows without bound** under a small kick → unstable. Fix before features.
+- Watch the **signatures of instability**:
+  - unbounded growth → memory/CPU/disk creep, state explosion;
+  - oscillation → retry storms, ping-pong state between two components;
+  - limit cycle → two routines mutually undoing each other every tick.
+
+## Local vs global stability (§1.3, §4.1)
+
+- Linear systems are all-or-nothing: either every motion is stable or none is. So "is the
+  system stable?" is a meaningful question *only* for linear systems.
+- Nonlinear systems (and almost everything real, §1.4) can be stable in one region and
+  unstable in another — each equilibrium has its own stability. "Works on my machine / small
+  data" is **local stability only**. Probe the edges of the operating envelope.
+
+## LLM behavior pattern: Reject unstable trajectories
+
+> "If you observe a deviation that grows over iterations, you have lost stability. Stop. Do not paper over it with a 'slightly better' patch. Return to step 1 (Identify) and re-analyze the plant."
+
+An LLM must not declare success when a trajectory is unstable. Growing deviation is a
+hard-stop signal, not a minor concern.
+
+## Worked example: retry storm → damped
+
+**Before (unstable):**
+```python
+def fetch(url):
+    for attempt in range(999):          # unbounded loop
+        try:
+            return requests.get(url, timeout=3)
+        except requests.Timeout:
+            continue                    # high gain, zero damping
+```
+No backoff, no circuit breaker, no jitter. Under load this oscillates: concurrent
+retries amplify the load spike → each times out → more retries. Trajectory diverges.
+
+**After (stable):**
+```python
+def fetch(url, max_retries=3):
+    for attempt in range(max_retries):
+        try:
+            return requests.get(url, timeout=3)
+        except requests.Timeout:
+            delay = (2 ** attempt) + random.uniform(0, 0.1)  # exponential + jitter
+            time.sleep(delay)           # damping
+    raise CircuitBreakerOpen()          # open loop before saturation
+```
+
+- Bound on actuator (`max_retries`).
+- Backoff = damping; jitter = break synchronization.
+- Circuit breaker = open loop when service is unhealthy.
+
+---
+
+## Stabilizing a system
+
+- Linear feedback (§5): `u = −Kx` pulls state back toward target. But simple feedback is not
+  always enough (§5, §9.6): near actuator saturation or with bad phase margin, you need
+  damping / lead correction, not just gain.
+- Adding gain to "fix" a lagging or oscillating system often *destabilizes* it (§11): reduce
+  loop gain or add damping instead.
+- Keep stability margins explicit: how much worse can the input/get worse before it diverges?

package/references/state-and-control.md

@@ -0,0 +1,84 @@
+# Reference: State, Control, Observability & Bounds
+
+Book anchor: §1.5 (controlled vs control quantities; constraints on both).
+
+## Two kinds of variables
+
+In every system you touch, separate:
+
+- **Controlled variables x** — the things that must be correct: output values, internal
+  state, invariants, latencies, error rates. You cannot set them directly; you can only
+  *influence* them through the equations of motion.
+- **Control variables u** — the levers you actually manipulate: function arguments, config
+  values, the code you write, the inputs you feed. Only on u do you have freedom to act.
+
+## LLM behavior pattern: Name x before u
+
+> "Name the controlled variable x before proposing any change. Unnamed targets are unregulated."
+
+An LLM using this skill **must** name the controlled variable and the control variable before
+any proposal. This is not optional framing—it is the first cognitive law. If you cannot name
+x, you cannot verify success; you are operating open-loop.
+
+- "Make it work" is not a control problem; "reduce error rate below 1%" is.
+- Before generating a patch, the LLM must internally resolve: what is x, what is u, and how
+  will I measure x after u moves?
+
+## LLM behavior pattern: Demand observability before acting
+
+> "A failure mode you cannot observe will drift until it bites. Add the sensor first."
+
+If the LLM identifies a plausible failure mode that is invisible to existing tests/logs, it
+must **propose instrumentation before proposing the fix**. Acting without observability is
+guessing; guessing is not control theory.
+
+- If observability is impossible in the current environment, state that explicitly as a risk.
+- Prefer mechanisms that *measure* outcomes over mechanisms that *assert* they happened.
+
+## Bounds are physical, not optional (§1.5)
+
+Linear regulation theory silently assumes variables are unbounded. Reality is not:
+
+- Control quantities are bounded: thrust limits, voltage/power limits, **API rate limits**,
+  **context-window size**, **stack depth**.
+- Controlled quantities are bounded: integer ranges, buffer sizes, **memory**, **deadlines**.
+
+Near a bound, linear intuition fails (saturation, overflow, OOM, token cutoff). Design for the
+bound, not the asymptote. The book notes that ignoring limits makes "transition time
+independent of step size" — which is simply false in practice. Same trap: assuming a function
+behaves the same at n=10 and n=10^7.
+
+## Observability vs controllability (§5.5)
+
+- A state you can measure → you can close a loop on it (observable).
+- A quantity you can change → you can steer it (controllable).
+- Some states are neither easily measured nor directly changed — they must be *estimated*
+  from observables. When debugging "impossible" faults, suspect a state that is observable
+  only indirectly. Build the estimator (instrumentation) before concluding the bug is
+  untraceable.
+
+## Worked example: unregulated target → open-loop patch
+
+**Before (no x, no u, no observability):**
+```python
+# "Make it better" — what is x? what is u? how will we know?
+def process(data):
+    return data  # placeholder; "fix" the symptom later
+```
+Without naming x and u, every subsequent change is a guess.
+
+**After (closed-loop from the start):**
+```python
+def process(data, max_size=1000):
+    # x = queue depth / error rate; u = max_size
+    # observability: raise if exceeded, count in tests
+    if len(data) > max_size:
+        raise ValueError(f"x exceeded bound: {len(data)} > {max_size}")
+    return data
+```
+
+- x = `len(data)` (controlled variable, must stay ≤ `max_size`)
+- u = `max_size` (the lever we adjust)
+- observability = exception raised, testable
+- bound = `max_size` (actuator saturation respected)
+

package/templates/change-proposal.md

@@ -0,0 +1,51 @@
+# Change Proposal (control-systems thinking scaffold)
+
+Fill this in before a non-trivial change. It forces the control-theoretic mindset: name the
+plant, the setpoint, the actuator, and how you will know it converged.
+
+## Target
+- **Controlled variable x** (what must stay correct):
+  _________________________________
+- **Setpoint x*** (target / invariant / acceptable range):
+  _________________________________
+
+## Plant & model
+- **Current behavior** (measured, not assumed):
+  _________________________________
+- **Mental model of the plant** (and where it may be wrong):
+  _________________________________
+- **Model validity range** (inputs/sizes/conditions where the model holds):
+  _________________________________
+
+## Control action
+- **Control variable u** (the lever I will change):
+  _________________________________
+- **Bounds on u** (max retries / depth / rate / size):
+  _________________________________
+- **Sensors** (how I will observe x after the change — tests/logs/metrics):
+  _________________________________
+
+## Disturbances
+- **Known external kicks** (load, network, other services):
+  _________________________________
+- **Feedforward (if measurable)** / **feedback only (if not)**:
+  _________________________________
+
+## Convergence
+- **Pass condition** (bounded deviation ||ε|| under which perturbation?):
+  _________________________________
+- **Test / observation that proves it**:
+  _________________________________
+
+## Coupling
+- **Subsystems that must stay separate** (decouple harmful coupling):
+  _________________________________
+- **Subsystems that must stay coordinated** (keep beneficial coupling, regulate relations):
+  _________________________________
+
+---
+Anti-patterns to avoid:
+- Unbounded retry/recursion/allocation → saturation → instability
+- Feature creep before the base is stable → divergence
+- Optimization before correctness → wrong trajectory
+- Guessing the cause without measurement → open-loop patch

package/templates/debugging-checklist.md

@@ -0,0 +1,44 @@
+# Debugging Checklist (closed-loop thinking mode)
+
+This checklist is a **prompt scaffold for the LLM's internal loop** during debugging.
+Work top to bottom; do not skip steps. If you find yourself on step 4 without a clear x
+and u, return to step 1.
+
+## 1. Identify (state & control)
+- [ ] **Controlled variable x**: what must stay correct? Name it concretely, with a target/units.
+- [ ] **Control variable u**: what lever will I actually change? (Not "rewrite"; the smallest editable thing.)
+- [ ] **Observability**: do I have a sensor (log/test/metric) that reveals x? If not → add it first.
+- [ ] **Bounds**: what are the limits on u and x? Size, rate, time, memory, retries, context.
+
+## 2. Analyze (current behavior)
+- [ ] Reproduced the fault deterministically? (Not "sometimes".)
+- [ ] Measured the deviation ε = x* − x? Stated the mental model of the plant and where it breaks.
+- [ ] Located the fault to a subsystem (not guessed).
+
+## 3. Stabilize (before any feature)
+- [ ] Tested with perturbations: empty / huge / null / concurrent / dependency-down / load spike.
+- [ ] No unbounded growth, oscillation, or limit cycle?
+- [ ] If unstable → fixed stability before adding anything.
+
+## 4. Synthesize (minimal control action)
+- [ ] Change is the smallest u that moves x to target. No speculative extras.
+- [ ] Decoupled harmful coupling; kept beneficial coupling (coordination, not over-decoupling).
+
+## 5. Close the loop (observe & correct)
+- [ ] Ran the actual code; read the actual sensor output — did NOT assume u worked.
+- [ ] Corrections are getting smaller, not larger.
+- [ ] Reached target within stated bounds.
+
+## 6. Compensate & clamp
+- [ ] Measurable disturbances handled by feedforward where possible; feedback the rest.
+- [ ] Control magnitude clamped (max retries/depth/rate). Graceful degradation at the bound.
+
+## 7. Optimize (last)
+- [ ] Only now tuning speed/cost/elegance. Stability and correctness already proven.
+
+---
+Anti-patterns (stop if you catch yourself):
+- Adding retries without a bound → retry storm (unstable delay loop)
+- Cranking gain on a delayed system → oscillation
+- Optimizing before stabilizing → divergence on perturbation
+- Guessing cause without reproduction → open-loop patch