skill-systems-thinking 0.1.0 → 0.1.1

package/references/bounded-control.md

@@ -1,82 +1,82 @@
-# Reference: Time-Optimal & Bounded Control
-
-Book anchors: §8 (time-optimal / bang-bang control), §9.6 (optimal control under control
-constraints).
-
-## Control effort is bounded — always
-
-Real actuators saturate: a thruster cannot exceed max thrust, a valve cannot open past
-fully-open. Software analogues are everywhere and just as hard:
-
-- retry budget, recursion depth, loop iterations, allocation size, request rate, context
-  window, transaction timeout.
-
-Linear theory ignores these bounds and is wrong at the edge (§1.5). **Unbounded control →
-actuator saturation → instability** (e.g. retry storm, stack overflow, OOM, rate-limit ban).
-
-## LLM behavior pattern: Clamp every actuator
-
-> "Every loop must have an explicit bound. No unbounded retry, recursion, or allocation."
-
-The LLM must proactively identify actuators in its proposed changes and clamp them:
-- Retry: max attempts, backoff, jitter, circuit breaker
-- Recursion: depth limit
-- Loop: iteration cap or progress guarantee
-- Allocation: size cap
-- Rate: throughput limit with graceful degradation at saturation
-
-## Bang-bang where appropriate (§8)
-
-To reach a target *fastest* under a bound, the optimal law is often **bang-bang**: drive the
-actuator to its limit in the right direction, then switch. Translated to code:
-
-- Make **decisive, maximal, well-scoped** changes to kill a fault — don't nibble at it with
-  timid partial fixes that leave the system near the unstable region.
-- Switch decisively when the sign of the error flips (e.g. change strategy, not just magnitude).
-
-But note (§9.6): bang-bang is optimal for *time*; for *energy/integral cost* (§9) a softer
-law is better. Pick the criterion to the goal.
-
-## Clamp the actuator
-
-- Bound every control loop: max retries, max recursion, max batch, max rate. Saturation
-  without a clamp is how a bounded disturbance becomes a runaway.
-- When you hit the bound, *degrade gracefully* (drop to a safe mode, shed load, return a
-  partial result) rather than oscillating at the limit.
-
-## Optimize the integral, not just the endpoint (§9)
-
-Often you minimize a **cumulative cost** — total latency, total tokens spent, total energy,
-total user-visible glitches — not just final state. Choose the change that minimizes the
-integral of cost over the whole trajectory, not the one that looks tidiest at the endpoint.
-
-## Generality notes
-
-These ideas apply identically whether the "plant" is a web service, a data pipeline, a
-compiler pass, or an LLM agent loop: every one has bounded actuators and a cost to minimize
-over time. The physical vocabulary (thrust, valve) is illustrative only — the invariant is
-*bounded, goal-directed control*.
-
-## Worked example: uncontrolled recursion → stack overflow
-
-**Before (no bound on actuator):**
-```python
-def walk(node):
-    for child in node.children:
-        walk(child)         # actuator: recursion depth — unbounded!
-```
-Circular reference in `node.children` → unbounded recursion → `RecursionError` /
-stack overflow. The actuator (call stack) has a hard saturation, but the code ignores it.
-
-**After (clamped actuator):**
-```python
-def walk(node, _depth=0, max_depth=100):
-    if _depth >= max_depth:
-        raise ValueError(f"Actuator saturated: depth {_depth} >= {max_depth}")
-    for child in node.children:
-        walk(child, _depth + 1, max_depth)
-```
-- Bound: `max_depth=100` (explicit actuator clamp).
-- Graceful degradation: exception at bound instead of silent crash.
-- Cost: O(n) with bounded cost per call; integral cost stays predictable.
-
+# Reference: Time-Optimal & Bounded Control
+
+Book anchors: §8 (time-optimal / bang-bang control), §9.6 (optimal control under control
+constraints).
+
+## Control effort is bounded — always
+
+Real actuators saturate: a thruster cannot exceed max thrust, a valve cannot open past
+fully-open. Software analogues are everywhere and just as hard:
+
+- retry budget, recursion depth, loop iterations, allocation size, request rate, context
+  window, transaction timeout.
+
+Linear theory ignores these bounds and is wrong at the edge (§1.5). **Unbounded control →
+actuator saturation → instability** (e.g. retry storm, stack overflow, OOM, rate-limit ban).
+
+## LLM behavior pattern: Clamp every actuator
+
+> "Every loop must have an explicit bound. No unbounded retry, recursion, or allocation."
+
+The LLM must proactively identify actuators in its proposed changes and clamp them:
+- Retry: max attempts, backoff, jitter, circuit breaker
+- Recursion: depth limit
+- Loop: iteration cap or progress guarantee
+- Allocation: size cap
+- Rate: throughput limit with graceful degradation at saturation
+
+## Bang-bang where appropriate (§8)
+
+To reach a target *fastest* under a bound, the optimal law is often **bang-bang**: drive the
+actuator to its limit in the right direction, then switch. Translated to code:
+
+- Make **decisive, maximal, well-scoped** changes to kill a fault — don't nibble at it with
+  timid partial fixes that leave the system near the unstable region.
+- Switch decisively when the sign of the error flips (e.g. change strategy, not just magnitude).
+
+But note (§9.6): bang-bang is optimal for *time*; for *energy/integral cost* (§9) a softer
+law is better. Pick the criterion to the goal.
+
+## Clamp the actuator
+
+- Bound every control loop: max retries, max recursion, max batch, max rate. Saturation
+  without a clamp is how a bounded disturbance becomes a runaway.
+- When you hit the bound, *degrade gracefully* (drop to a safe mode, shed load, return a
+  partial result) rather than oscillating at the limit.
+
+## Optimize the integral, not just the endpoint (§9)
+
+Often you minimize a **cumulative cost** — total latency, total tokens spent, total energy,
+total user-visible glitches — not just final state. Choose the change that minimizes the
+integral of cost over the whole trajectory, not the one that looks tidiest at the endpoint.
+
+## Generality notes
+
+These ideas apply identically whether the "plant" is a web service, a data pipeline, a
+compiler pass, or an LLM agent loop: every one has bounded actuators and a cost to minimize
+over time. The physical vocabulary (thrust, valve) is illustrative only — the invariant is
+*bounded, goal-directed control*.
+
+## Worked example: uncontrolled recursion → stack overflow
+
+**Before (no bound on actuator):**
+```python
+def walk(node):
+    for child in node.children:
+        walk(child)         # actuator: recursion depth — unbounded!
+```
+Circular reference in `node.children` → unbounded recursion → `RecursionError` /
+stack overflow. The actuator (call stack) has a hard saturation, but the code ignores it.
+
+**After (clamped actuator):**
+```python
+def walk(node, _depth=0, max_depth=100):
+    if _depth >= max_depth:
+        raise ValueError(f"Actuator saturated: depth {_depth} >= {max_depth}")
+    for child in node.children:
+        walk(child, _depth + 1, max_depth)
+```
+- Bound: `max_depth=100` (explicit actuator clamp).
+- Graceful degradation: exception at bound instead of silent crash.
+- Cost: O(n) with bounded cost per call; integral cost stays predictable.
+

package/references/closed-loop-workflow.md

@@ -1,89 +1,89 @@
-# Reference: Closed-Loop Workflow & Analysis-before-Synthesis
-
-Book anchors: §1.5 (analysis vs synthesis), §3.7 (feedback), §4 (control-system analysis).
-
-## Why closed loop
-
-An open-loop program — "write it once, hope it works" — has no path to recover from error. A
-closed-loop program *acts → observes → corrects*, and therefore converges (§3.7: feedback
-raises both accuracy and speed of response).
-
-Operational rules:
-- After every non-trivial change, **observe the actual state** before declaring success:
-  run it, read output, check tests. Do not assume `u` produced the intended `x`.
-- Prefer mechanisms that **measure** outcomes over mechanisms that **assert** they happened.
-- If you cannot observe a quantity, you cannot control it (§1.5): a controlled quantity is
-  steered only through a control quantity you are free to change.
-
-## Analysis before synthesis (§1.5, §4)
-
-> Analysis is understanding the motion of a given system; synthesis is changing that motion to
-> meet a need. Analysis is the foundation; synthesis is the goal — and the higher stage.
-
-- **Never skip analysis.** Before fixing or refactoring, characterize current behavior:
-  reproduce, measure, locate the fault. You cannot steer what you have not measured.
-- Then synthesize the *minimal* control action that moves state to the target.
-- A change whose effect you cannot predict from analysis is an open-loop guess. Make the
-  prediction explicit, then verify it.
-
-## The loop, made concrete
-
-| Step | Control term | What you actually do |
-|------|--------------|----------------------|
-| Identify | define `x`, `u`, sensors, bounds | Write down what must be correct and what lever you'll pull |
-| Analyze | measure current trajectory | Reproduce the bug / profile the baseline |
-| Stabilize | drive poles to stable region | Stop the divergence/leak/oscillation |
-| Synthesize | choose control law `u = f(ε)` | Make the smallest change that moves `x` to target |
-| Observe | read sensors | Run tests, read logs, check metrics |
-| Correct | update `u` from error `ε = x* − x` | Iterate until `‖ε‖` is bounded and small |
-| Compensate | feedforward + clamp | Pre-handle measurable disturbances; bound the actuator |
-| Optimize | secondary criteria | Only now tune speed/cost/elegance |
-
-## How to know the loop converged
-
-- Deviation `ε` is **bounded** for the largest perturbation you can throw at it (stability, §4.1).
-- Corrections get **smaller**, not larger, over iterations (no limit cycle, no retry storm).
-- The setpoint is reached within the stated bounds (memory, time, rate limit).
-
-## Worked example: analysis before synthesis — cache stampede
-
-**Symptom:** under sudden traffic spike, database CPU spikes to 100%, API returns 503.
-
-**Open-loop (skip analysis):**
-```python
-@app.get("/data/{id}")
-def get_data(id):
-    data = cache.get(id) or db.query(f"SELECT * FROM t WHERE id={id}")
-    return data
-```
-Naive fix (synthesis without analysis): "just add a cache"
-
-**Closed-loop (analysis first):**
-```
-Analyze:
-  x = db CPU utilization; target < 70%
-  u = cache TTL + eviction policy
-  Model: thundering-herd on cache miss → spike proportional to missing-key rate
-  Validity: model holds for any cache with TTL; breaks for in-process unbounded cache
-```
-
-**Stabilize first:**
-```python
-@app.get("/data/{id}")
-def get_data(id):
-    data = cache.get(id)
-    if data is None:
-        with lock:                    # serialize misses per key
-            data = cache.get(id) or db.query(...)
-            cache.set(id, data, ttl=60)
-    return data
-```
-- Lock prevents thundering herd (damps the oscillation).
-- TTL bounds memory.
-
-**Then optimize:**
-- Only after CPU is bounded <70%, consider increasing TTL or adding tiered caching.
-
-Key point: adding a cache *without* the lock in the first patch would have shifted but not
-eliminated the oscillation. Analysis → stabilize → then synthesize = closed loop.
-
+# Reference: Closed-Loop Workflow & Analysis-before-Synthesis
+
+Book anchors: §1.5 (analysis vs synthesis), §3.7 (feedback), §4 (control-system analysis).
+
+## Why closed loop
+
+An open-loop program — "write it once, hope it works" — has no path to recover from error. A
+closed-loop program *acts → observes → corrects*, and therefore converges (§3.7: feedback
+raises both accuracy and speed of response).
+
+Operational rules:
+- After every non-trivial change, **observe the actual state** before declaring success:
+  run it, read output, check tests. Do not assume `u` produced the intended `x`.
+- Prefer mechanisms that **measure** outcomes over mechanisms that **assert** they happened.
+- If you cannot observe a quantity, you cannot control it (§1.5): a controlled quantity is
+  steered only through a control quantity you are free to change.
+
+## Analysis before synthesis (§1.5, §4)
+
+> Analysis is understanding the motion of a given system; synthesis is changing that motion to
+> meet a need. Analysis is the foundation; synthesis is the goal — and the higher stage.
+
+- **Never skip analysis.** Before fixing or refactoring, characterize current behavior:
+  reproduce, measure, locate the fault. You cannot steer what you have not measured.
+- Then synthesize the *minimal* control action that moves state to the target.
+- A change whose effect you cannot predict from analysis is an open-loop guess. Make the
+  prediction explicit, then verify it.
+
+## The loop, made concrete
+
+| Step | Control term | What you actually do |
+|------|--------------|----------------------|
+| Identify | define `x`, `u`, sensors, bounds | Write down what must be correct and what lever you'll pull |
+| Analyze | measure current trajectory | Reproduce the bug / profile the baseline |
+| Stabilize | drive poles to stable region | Stop the divergence/leak/oscillation |
+| Synthesize | choose control law `u = f(ε)` | Make the smallest change that moves `x` to target |
+| Observe | read sensors | Run tests, read logs, check metrics |
+| Correct | update `u` from error `ε = x* − x` | Iterate until `‖ε‖` is bounded and small |
+| Compensate | feedforward + clamp | Pre-handle measurable disturbances; bound the actuator |
+| Optimize | secondary criteria | Only now tune speed/cost/elegance |
+
+## How to know the loop converged
+
+- Deviation `ε` is **bounded** for the largest perturbation you can throw at it (stability, §4.1).
+- Corrections get **smaller**, not larger, over iterations (no limit cycle, no retry storm).
+- The setpoint is reached within the stated bounds (memory, time, rate limit).
+
+## Worked example: analysis before synthesis — cache stampede
+
+**Symptom:** under sudden traffic spike, database CPU spikes to 100%, API returns 503.
+
+**Open-loop (skip analysis):**
+```python
+@app.get("/data/{id}")
+def get_data(id):
+    data = cache.get(id) or db.query(f"SELECT * FROM t WHERE id={id}")
+    return data
+```
+Naive fix (synthesis without analysis): "just add a cache"
+
+**Closed-loop (analysis first):**
+```
+Analyze:
+  x = db CPU utilization; target < 70%
+  u = cache TTL + eviction policy
+  Model: thundering-herd on cache miss → spike proportional to missing-key rate
+  Validity: model holds for any cache with TTL; breaks for in-process unbounded cache
+```
+
+**Stabilize first:**
+```python
+@app.get("/data/{id}")
+def get_data(id):
+    data = cache.get(id)
+    if data is None:
+        with lock:                    # serialize misses per key
+            data = cache.get(id) or db.query(...)
+            cache.set(id, data, ttl=60)
+    return data
+```
+- Lock prevents thundering herd (damps the oscillation).
+- TTL bounds memory.
+
+**Then optimize:**
+- Only after CPU is bounded <70%, consider increasing TTL or adding tiered caching.
+
+Key point: adding a cache *without* the lock in the first patch would have shifted but not
+eliminated the oscillation. Analysis → stabilize → then synthesize = closed loop.
+

package/references/discrete-systems.md

@@ -1,79 +1,79 @@
-# Reference: Discrete / Sampled Systems & Test Cadence
-
-Book anchor: §10 (discrete control systems — difference equations, sampled data).
-
-## Software runs in discrete steps
-
-Continuous control theory assumes you can act and observe at every instant. Software acts and
-observes only at **sample instants**: function calls, test runs, deploys, metric scrapes,
-human reviews. Between samples the state is *unobserved*.
-
-Consequences:
-- **Sample often enough.** A feedback loop sampled too coarsely (tests only at the end,
-  manual checks weeks apart) cannot stabilize a fast-moving fault. Tighten the loop:
-  unit → integration → typecheck → run, frequently and automatically.
-- **Guard the gap.** Between samples, anything can happen: timeout, partial write, concurrent
-  mutation, crash. Design for the unobserved interval — idempotency, transactions, rollback,
-  heartbeat/lease.
-- **Aliasing instability.** A bug that appears only at certain intervals or scales is a
-  *sampled-system alias* — the true dynamics are faster than your sampling. Vary the
-  sample/scale when testing (small vs large input, fast vs slow clock).
-
-## LLM behavior pattern: Treat cadence as a controlled variable
-
-> "Your feedback cadence is a design variable. Tighten it when you need stability; loosen it only when the system is already robust."
-
-The LLM should recognize that its own test/review cadence is a *sampling rate* that affects
-stability margin. It should not propose changes that rely on coarse-grained verification for
-systems with fast dynamics.
-
-- Tight cadence (fast tests, CI on every commit) → can use higher gain (more aggressive
-  fixes) and still stay stable.
-- Loose cadence (nightly, manual) → must use lower gain (conservative, well-reviewed changes)
-  or it will overshoot.
-
-## Discrete instability signatures (§10)
-
-- **Limit cycle at the sample period**: a fault that recurs every N runs because the
-  correction and the next sample line up badly.
-- **Chattering**: a value flips every sample between two states (Zeno-like behavior in
-  continuous terms) — add hysteresis / deadband so small errors don't trigger action.
-- **Deadbeat vs sluggish**: too much gain overshoots and oscillates; too little never
-  converges. Tune the *discrete* gain (e.g. test frequency, retry backoff curve).
-
-## Anti-pattern: Coarse sampling masks instability
-
-> "A system that passes only when tested weekly may be oscillating daily. The LLM must probe at multiple scales before declaring stability."
-
-The LLM must vary test scale and frequency when assessing stability. A single golden-path
-test at low frequency is not observability; it is a sample that may miss the true dynamics.
-
-## Worked example: weekly test passes, daily test reveals oscillation
-
-**Symptom:** a data pipeline passes end-to-end test when run manually, but downstream teams
-report stale data every morning.
-
-```python
-# pipeline runs once a day; test runs manually on demand
-def run_pipeline():
-    ...
-```
-- Sampling rate: 1× per day (coarse)
-- True dynamics: cache TTL = 1 hour; data freshness degrades within hours → oscillation
-  between "fresh" and "stale" every hour
-- Weekly manual test catches only one sample point — coincidentally fresh — masking the
-  daily limit cycle
-
-**Fix (tighten the loop):**
-```python
-# Hourly CI job + explicit freshness assertion
-def run_pipeline():
-    ...
-    assert freshness_hours() < 2, f"Data stale: {freshness_hours()}h"
-
-# Hourly cron in CI; alert on assertion failure
-```
-- Sample rate increased from daily to hourly.
-- True limit cycle (1-hour) now falls within the sampling window and is detectable.
-- Observability: assertion converts invisible state (freshness) into a measurable signal.
-
+# Reference: Discrete / Sampled Systems & Test Cadence
+
+Book anchor: §10 (discrete control systems — difference equations, sampled data).
+
+## Software runs in discrete steps
+
+Continuous control theory assumes you can act and observe at every instant. Software acts and
+observes only at **sample instants**: function calls, test runs, deploys, metric scrapes,
+human reviews. Between samples the state is *unobserved*.
+
+Consequences:
+- **Sample often enough.** A feedback loop sampled too coarsely (tests only at the end,
+  manual checks weeks apart) cannot stabilize a fast-moving fault. Tighten the loop:
+  unit → integration → typecheck → run, frequently and automatically.
+- **Guard the gap.** Between samples, anything can happen: timeout, partial write, concurrent
+  mutation, crash. Design for the unobserved interval — idempotency, transactions, rollback,
+  heartbeat/lease.
+- **Aliasing instability.** A bug that appears only at certain intervals or scales is a
+  *sampled-system alias* — the true dynamics are faster than your sampling. Vary the
+  sample/scale when testing (small vs large input, fast vs slow clock).
+
+## LLM behavior pattern: Treat cadence as a controlled variable
+
+> "Your feedback cadence is a design variable. Tighten it when you need stability; loosen it only when the system is already robust."
+
+The LLM should recognize that its own test/review cadence is a *sampling rate* that affects
+stability margin. It should not propose changes that rely on coarse-grained verification for
+systems with fast dynamics.
+
+- Tight cadence (fast tests, CI on every commit) → can use higher gain (more aggressive
+  fixes) and still stay stable.
+- Loose cadence (nightly, manual) → must use lower gain (conservative, well-reviewed changes)
+  or it will overshoot.
+
+## Discrete instability signatures (§10)
+
+- **Limit cycle at the sample period**: a fault that recurs every N runs because the
+  correction and the next sample line up badly.
+- **Chattering**: a value flips every sample between two states (Zeno-like behavior in
+  continuous terms) — add hysteresis / deadband so small errors don't trigger action.
+- **Deadbeat vs sluggish**: too much gain overshoots and oscillates; too little never
+  converges. Tune the *discrete* gain (e.g. test frequency, retry backoff curve).
+
+## Anti-pattern: Coarse sampling masks instability
+
+> "A system that passes only when tested weekly may be oscillating daily. The LLM must probe at multiple scales before declaring stability."
+
+The LLM must vary test scale and frequency when assessing stability. A single golden-path
+test at low frequency is not observability; it is a sample that may miss the true dynamics.
+
+## Worked example: weekly test passes, daily test reveals oscillation
+
+**Symptom:** a data pipeline passes end-to-end test when run manually, but downstream teams
+report stale data every morning.
+
+```python
+# pipeline runs once a day; test runs manually on demand
+def run_pipeline():
+    ...
+```
+- Sampling rate: 1× per day (coarse)
+- True dynamics: cache TTL = 1 hour; data freshness degrades within hours → oscillation
+  between "fresh" and "stale" every hour
+- Weekly manual test catches only one sample point — coincidentally fresh — masking the
+  daily limit cycle
+
+**Fix (tighten the loop):**
+```python
+# Hourly CI job + explicit freshness assertion
+def run_pipeline():
+    ...
+    assert freshness_hours() < 2, f"Data stale: {freshness_hours()}h"
+
+# Hourly cron in CI; alert on assertion failure
+```
+- Sample rate increased from daily to hourly.
+- True limit cycle (1-hour) now falls within the sampling window and is detectable.
+- Observability: assertion converts invisible state (freshness) into a measurable signal.
+