skill-systems-thinking 0.1.0 → 0.1.2

package/references/disturbance.md

@@ -1,98 +1,98 @@
-# Reference: Disturbance Compensation & Time-Delay
-
-Book anchors: §6.7 (third method: disturbance compensation / invariance), §11 (systems with
-time lag / delay).
-
-## Two ways to reject a disturbance
-
-Outside forces push your system off-target: flaky networks, load spikes, other teams'
-services, GC pauses, clock drift.
-
-1. **Feedback (reactive).** Observe the deviation `ε = x* − x` and correct. Robust, but *lags*
-   — by the time you measure and act, the disturbance has already moved you.
-2. **Feedforward / disturbance compensation (proactive, §6.7).** If the disturbance is
-   *measurable*, compensate for it directly so the **relationship** stays invariant. Combine
-   both → *composite control*: accuracy from feedforward, stability from feedback.
-
-## LLM behavior pattern: Feedforward when measurable, never crank gain on delay
-
-> "For measurable disturbances, compensate proactively. For delayed loops, add damping, not gain. Never crank gain on a delayed loop — it drives the system unstable."
-
-The LLM must explicitly evaluate whether disturbances are measurable and whether the feedback
-loop involves delay. If it proposes increasing retries/logic frequency without addressing the
-delay, it is an unstable control action.
-
-- Apply invariance to the **coordination relation**, not just one variable (§6.7): compensate
-  so the *relation* holds under the measurable kick.
-- For *unmeasurable* disturbances, you can only fall back to feedback — so maximize
-  observability of likely kicks.
-
-## Time-delay systems (§11)
-
-Many software loops have intrinsic delay: network round-trips, async pipelines, batch jobs,
-human-in-the-loop. Delay is the enemy of stability.
-
-- Expect **reduced stability margin** and **oscillation** when loop delay is large relative to
-  the dynamics (§11: delay systems need special stability criteria).
-- **Do not crank up gain** to compensate for a slow/delayed loop — that pushes it unstable
-  (cf. §4/§5 phase margin). Instead:
-  - reduce effective loop gain or add damping;
-  - shorten the loop (tighter sampling, §10);
-  - predict/delay-compensate if the delay is known and measurable.
-- Watch for limit cycles that appear *only* because of the delay (e.g. a retry that fires
-  exactly when the late response arrives).
-
-## Worked example: flaky dependency → feedforward + feedback
-
-**Before (feedback only):**
-```python
-def call_external():
-    for attempt in range(5):
-        try:
-            return requests.get(EXTERNAL_URL, timeout=2)
-        except Exception:
-            time.sleep(1)     # fixed backoff — no knowledge of cause
-```
-If the dependency is down for 30 seconds, every call burns 5×2 seconds and still fails.
-The disturbance (dependency outage) is *measurable* — we have a health endpoint — but we
-do not use it. Pure feedback on a delayed, unmeasured disturbance: unstable under load.
-
-**After (composite control):**
-```python
-_healthy = None
-
-def call_external():
-    global _healthy
-    if _healthy is False:
-        raise CircuitBreakerOpen()    # feedforward: fail fast on known outage
-    try:
-        resp = requests.get(EXTERNAL_URL, timeout=2)
-        _healthy = True
-        return resp
-    except Exception:
-        _healthy = False
-        time.sleep(2 ** attempt + random.uniform(0, 0.1))
-        raise
-```
-
-- Feedforward: health check measured at startup and on every failure; known outage → open
-  loop immediately (invariance from the disturbance).
-- Feedback: backoff on transient errors still corrects the trajectory.
-- Composite control: accuracy from invariant relation, stability from feedback.
-
----
-
-## Retry storms are unstable delay loops
-
-A retry-without-backoff is a high-gain, zero-damping controller on a delayed plant →
-oscillation that grows. Fix: bounded retries + backoff (damping) + jitter (break sync) +
-circuit breaker (open the loop before it diverges).
-
-## LLM anti-pattern detection
-
-When a system has a delay, the LLM must not propose:
-- More retries (increasing gain)
-- Shorter timeouts without backoff (reducing delay margin)
-- Any change that amplifies the loop before reducing the delay or adding damping
-
-These are textbook unstable trajectories. The skill must prevent them.
+# Reference: Disturbance Compensation & Time-Delay
+
+Book anchors: §6.7 (third method: disturbance compensation / invariance), §11 (systems with
+time lag / delay).
+
+## Two ways to reject a disturbance
+
+Outside forces push your system off-target: flaky networks, load spikes, other teams'
+services, GC pauses, clock drift.
+
+1. **Feedback (reactive).** Observe the deviation `ε = x* − x` and correct. Robust, but *lags*
+   — by the time you measure and act, the disturbance has already moved you.
+2. **Feedforward / disturbance compensation (proactive, §6.7).** If the disturbance is
+   *measurable*, compensate for it directly so the **relationship** stays invariant. Combine
+   both → *composite control*: accuracy from feedforward, stability from feedback.
+
+## LLM behavior pattern: Feedforward when measurable, never crank gain on delay
+
+> "For measurable disturbances, compensate proactively. For delayed loops, add damping, not gain. Never crank gain on a delayed loop — it drives the system unstable."
+
+The LLM must explicitly evaluate whether disturbances are measurable and whether the feedback
+loop involves delay. If it proposes increasing retries/logic frequency without addressing the
+delay, it is an unstable control action.
+
+- Apply invariance to the **coordination relation**, not just one variable (§6.7): compensate
+  so the *relation* holds under the measurable kick.
+- For *unmeasurable* disturbances, you can only fall back to feedback — so maximize
+  observability of likely kicks.
+
+## Time-delay systems (§11)
+
+Many software loops have intrinsic delay: network round-trips, async pipelines, batch jobs,
+human-in-the-loop. Delay is the enemy of stability.
+
+- Expect **reduced stability margin** and **oscillation** when loop delay is large relative to
+  the dynamics (§11: delay systems need special stability criteria).
+- **Do not crank up gain** to compensate for a slow/delayed loop — that pushes it unstable
+  (cf. §4/§5 phase margin). Instead:
+  - reduce effective loop gain or add damping;
+  - shorten the loop (tighter sampling, §10);
+  - predict/delay-compensate if the delay is known and measurable.
+- Watch for limit cycles that appear *only* because of the delay (e.g. a retry that fires
+  exactly when the late response arrives).
+
+## Worked example: flaky dependency → feedforward + feedback
+
+**Before (feedback only):**
+```python
+def call_external():
+    for attempt in range(5):
+        try:
+            return requests.get(EXTERNAL_URL, timeout=2)
+        except Exception:
+            time.sleep(1)     # fixed backoff — no knowledge of cause
+```
+If the dependency is down for 30 seconds, every call burns 5×2 seconds and still fails.
+The disturbance (dependency outage) is *measurable* — we have a health endpoint — but we
+do not use it. Pure feedback on a delayed, unmeasured disturbance: unstable under load.
+
+**After (composite control):**
+```python
+_healthy = None
+
+def call_external():
+    global _healthy
+    if _healthy is False:
+        raise CircuitBreakerOpen()    # feedforward: fail fast on known outage
+    try:
+        resp = requests.get(EXTERNAL_URL, timeout=2)
+        _healthy = True
+        return resp
+    except Exception:
+        _healthy = False
+        time.sleep(2 ** attempt + random.uniform(0, 0.1))
+        raise
+```
+
+- Feedforward: health check measured at startup and on every failure; known outage → open
+  loop immediately (invariance from the disturbance).
+- Feedback: backoff on transient errors still corrects the trajectory.
+- Composite control: accuracy from invariant relation, stability from feedback.
+
+---
+
+## Retry storms are unstable delay loops
+
+A retry-without-backoff is a high-gain, zero-damping controller on a delayed plant →
+oscillation that grows. Fix: bounded retries + backoff (damping) + jitter (break sync) +
+circuit breaker (open the loop before it diverges).
+
+## LLM anti-pattern detection
+
+When a system has a delay, the LLM must not propose:
+- More retries (increasing gain)
+- Shorter timeouts without backoff (reducing delay margin)
+- Any change that amplifies the loop before reducing the delay or adding damping
+
+These are textbook unstable trajectories. The skill must prevent them.

package/references/modeling.md

@@ -1,87 +1,87 @@
-# Reference: Modeling & Engineering Approximation
-
-Book anchors: §1.4 (almost every real system is nonlinear; linearize deliberately), §1.6
-(model identification: analytic, experimental, statistical).
-
-## Deliberate simplification (§1.4)
-
-> Almost any physical system is nonlinear if analyzed precisely enough. We call a system
-> "linear" only when, *for the question being asked*, a linear system represents it precisely
-> enough that the difference is irrelevant.
-
-- Don't reach for the full-complexity model first. Build the **simplest model that answers the
-  current question**, and **state its validity range**.
-- **Pick the model to the question:**
-  - Near a stable equilibrium → linearize, ignore nonlinearity (§1.4, Lyapunov first
-    approximation).
-  - Studying oscillation / self-excited vibration / limit cycles → the nonlinearity *is* the
-    cause; keep it. Linearizing would delete the very phenomenon you're investigating.
-- This is the control-theoretic twin of the simplicity rule: simplify, but **know where
-  the simplification breaks** — and say so.
-
-## LLM behavior pattern: State the model and its limits
-
-> "I model the plant as X. This model holds under conditions Y. It breaks when Z."
-
-The LLM must explicitly state its mental model of the system and where it breaks, before
-synthesizing a fix. Implicit models lead to implicit breakage.
-
-- If a bug contradicts your model, **the model was wrong, not the bug**. Update the model.
-- Distinguish the *model you use to decide* from the *plant that actually runs*. The gap
-  between them is where instability hides.
-
-## Model identification: you don't know the plant exactly (§1.6)
-
-You rarely have a perfect model of the system you're editing. Three ways to get one:
-
-1. **Analytic** — decompose into units, model each, compose. Works *only* when decomposition
-   is faithful. Beware emergent behavior at the seams: a component's model in isolation can
-   differ qualitatively from its behavior inside the system.
-2. **Experimental (preferred for code)** — inject a known input `u`, record the output `x`,
-   infer the model. *This is exactly running the code and observing.* Let behavior, not
-   assumption, teach you the plant.
-3. **Statistical** — when the plant is too complex for clean analytic or single-shot
-   experimental identification, use frequency/statistical probing (§1.6: sine sweep →
-   amplitude/phase → transfer function).
-
-## Treat the model as approximate and updatable
-
-- After a surprise during debugging, **update your mental model** of the plant. A bug that
-  contradicts your model means the model was wrong, not the bug.
-- Distinguish the *model you use to decide* from the *plant that actually runs*. The gap
-  between them is where instability hides.
-
-## Worked example: linear model breaks at scale
-
-**Scenario:** a list-merging function works for n=10 but segfaults at n=10^7.
-
-```python
-def merge(a, b):
-    return a + b          # model: O(n) concatenation, works for small n
-```
-
-**Analysis:**
-- Mental model: "concatenation is cheap; I can use it anywhere"
-- This model breaks at n=10^7 because `a + b` allocates a new list of size `len(a)+len(b)`.
-- Memory spikes → OOM → crash. The model assumed linear cost; reality is linear *coefficient*
-  with a fixed allocation overhead that dominates at scale.
-
-**Correct model (stated validity range):**
-```
-x = memory usage; model = O(n) allocation per merge; valid for n << cache size.
-Breaks when n approaches memory limit.
-```
-
-**Fix informed by correct model:**
-```python
-def merge(a, b, out=None):
-    if out is None:
-        out = []
-    out.extend(a)
-    out.extend(b)           # in-place; model remains valid at scale
-    return out
-```
-
-- Model validity range is now explicit.
-- Bug informed the model update; model informed the fix.
-
+# Reference: Modeling & Engineering Approximation
+
+Book anchors: §1.4 (almost every real system is nonlinear; linearize deliberately), §1.6
+(model identification: analytic, experimental, statistical).
+
+## Deliberate simplification (§1.4)
+
+> Almost any physical system is nonlinear if analyzed precisely enough. We call a system
+> "linear" only when, *for the question being asked*, a linear system represents it precisely
+> enough that the difference is irrelevant.
+
+- Don't reach for the full-complexity model first. Build the **simplest model that answers the
+  current question**, and **state its validity range**.
+- **Pick the model to the question:**
+  - Near a stable equilibrium → linearize, ignore nonlinearity (§1.4, Lyapunov first
+    approximation).
+  - Studying oscillation / self-excited vibration / limit cycles → the nonlinearity *is* the
+    cause; keep it. Linearizing would delete the very phenomenon you're investigating.
+- This is the control-theoretic twin of the simplicity rule: simplify, but **know where
+  the simplification breaks** — and say so.
+
+## LLM behavior pattern: State the model and its limits
+
+> "I model the plant as X. This model holds under conditions Y. It breaks when Z."
+
+The LLM must explicitly state its mental model of the system and where it breaks, before
+synthesizing a fix. Implicit models lead to implicit breakage.
+
+- If a bug contradicts your model, **the model was wrong, not the bug**. Update the model.
+- Distinguish the *model you use to decide* from the *plant that actually runs*. The gap
+  between them is where instability hides.
+
+## Model identification: you don't know the plant exactly (§1.6)
+
+You rarely have a perfect model of the system you're editing. Three ways to get one:
+
+1. **Analytic** — decompose into units, model each, compose. Works *only* when decomposition
+   is faithful. Beware emergent behavior at the seams: a component's model in isolation can
+   differ qualitatively from its behavior inside the system.
+2. **Experimental (preferred for code)** — inject a known input `u`, record the output `x`,
+   infer the model. *This is exactly running the code and observing.* Let behavior, not
+   assumption, teach you the plant.
+3. **Statistical** — when the plant is too complex for clean analytic or single-shot
+   experimental identification, use frequency/statistical probing (§1.6: sine sweep →
+   amplitude/phase → transfer function).
+
+## Treat the model as approximate and updatable
+
+- After a surprise during debugging, **update your mental model** of the plant. A bug that
+  contradicts your model means the model was wrong, not the bug.
+- Distinguish the *model you use to decide* from the *plant that actually runs*. The gap
+  between them is where instability hides.
+
+## Worked example: linear model breaks at scale
+
+**Scenario:** a list-merging function works for n=10 but segfaults at n=10^7.
+
+```python
+def merge(a, b):
+    return a + b          # model: O(n) concatenation, works for small n
+```
+
+**Analysis:**
+- Mental model: "concatenation is cheap; I can use it anywhere"
+- This model breaks at n=10^7 because `a + b` allocates a new list of size `len(a)+len(b)`.
+- Memory spikes → OOM → crash. The model assumed linear cost; reality is linear *coefficient*
+  with a fixed allocation overhead that dominates at scale.
+
+**Correct model (stated validity range):**
+```
+x = memory usage; model = O(n) allocation per merge; valid for n << cache size.
+Breaks when n approaches memory limit.
+```
+
+**Fix informed by correct model:**
+```python
+def merge(a, b, out=None):
+    if out is None:
+        out = []
+    out.extend(a)
+    out.extend(b)           # in-place; model remains valid at scale
+    return out
+```
+
+- Model validity range is now explicit.
+- Bug informed the model update; model informed the fix.
+

package/references/multivariable.md

@@ -1,112 +1,112 @@
-# Reference: Multivariable — Decouple What Hurts, Coordinate What Helps
-
-Book anchors: §6.2–§6.3 (multi-variable control, non-interaction / diagonalization),
-§6.7 (coordination control: coordination error, internal setpoint, disturbance compensation).
-
-## Codebases are multivariable
-
-Real systems have many modules and concerns coupled through shared state, APIs, and data.
-The control question (§6.3) is: *which cross-terms must be zero, and which may stay?*
-
-### Decoupling (§6.3, "non-interacting control")
-
-- When two concerns must not interfere, drive the cross-terms to zero: isolate, single
-  responsibility, pure functions, no shared mutable state, explicit interfaces.
-- Once diagonalized, each subsystem can be designed as its own single-variable system —
-  dramatically simpler (§6.3). This is the control-theory justification for modular design.
-
-## LLM behavior pattern: Evaluate coupling before changing structure
-
-> "Decouple harmful coupling; keep beneficial coupling. Do not default to 'isolate everything'."
-
-When proposing a refactor or architecture change, the LLM **must** distinguish:
-- **Harmful coupling**: cross-terms that cause instability, race conditions, or incorrect results
-  under perturbation. These must be driven to zero.
-- **Beneficial coupling**: synchronization, shared invariants, backpressure that keeps the
-  system coherent. Removing these creates residual coupling elsewhere.
-
-Blindly removing all coupling: complicates the system (more sensors/actuators to fake the
-lost natural coupling); leaves residual coupling that *worsens* quality because the real plant
-is uncertain.
-
-## Coordination (§6.7) — do NOT over-decouple
-
-> Non-interacting control is not the only design principle. Often subsystems must *cooperate*
-> and stay in a coordination relation, not be independent.
-
-- Some coupling is **beneficial**: forced synchronization, shared invariants, mechanical
-  coupling that keeps things in lockstep.
-- Keep helpful coupling; cancel only the **harmful** cross-talk (§6.7: use controller coupling
-  to offset harmful plant coupling, preserve beneficial plant coupling).
-
-## Coordination error (协调偏差) — control the relation, not just absolutes
-
-- For coupled subsystems, regulate the **relation** between variables (e.g. "these two must
-  stay consistent / proportional / in sync"), not only each variable's absolute value.
-- Use an **internal setpoint**: when one subsystem moves, re-derive the others' targets from
-  the *actual* state, so the whole returns to coordination. External fixed setpoints alone
-  cannot hold a coordination relation under disturbance.
-- Example mappings: distributed cache + DB (consistency relation); producer/consumer queues
-  (backpressure relation); replicated services (quorum/sync relation).
-
-## Worked example: shared mutable state → harmful coupling / beneficial coupling
-
-**Harmful coupling (before):**
-```python
-# module_a.py
-_counter = 0
-
-def increment():
-    global _counter
-    _counter += 1
-
-# module_b.py  
-from module_a import _counter
-
-def report():
-    return _counter        # reads mutable state module_a owns
-```
-`module_b.report()` correctness depends on `module_a` execution order. Under concurrency
-this is a race condition — the cross-term is nonzero and causes instability. Decouple with
-explicit interface:
-
-**After (decoupled):**
-```python
-# module_a.py
-_state = {"count": 0}
-
-def increment(state):
-    state["count"] += 1
-    return state
-
-# module_b.py — no knowledge of module_a internals
-def report(state):
-    return state["count"]
-```
-
-**Beneficial coupling (preserved):**
-```python
-# Producer/consumer with backpressure (keep this coupling)
-queue = asyncio.Queue(maxsize=100)
-
-async def producer():
-    for item in source():
-        await queue.put(item)     # natural back pressure
-
-async def consumer():
-    while True:
-        item = await queue.get()  # consumption rate regulates production rate
-```
-Removing the queue and calling producer/consumer independently destroys the natural
-coordination. Regulate the *relation* (producer rate ≤ consumer rate), not just each
-absolute.
-
----
-
-## Decision rule
-
-- Will interference cause incorrectness or instability? → **decouple** (diagonalize).
-- Must subsystems move together or hold a ratio/invariant? → **coordinate** (internal
-  setpoint + relation feedback), keep beneficial coupling.
-- Uncertain which? Prefer the simpler structure, then *test the coupling* under disturbance
-  before adding decoupling machinery.
+# Reference: Multivariable — Decouple What Hurts, Coordinate What Helps
+
+Book anchors: §6.2–§6.3 (multi-variable control, non-interaction / diagonalization),
+§6.7 (coordination control: coordination error, internal setpoint, disturbance compensation).
+
+## Codebases are multivariable
+
+Real systems have many modules and concerns coupled through shared state, APIs, and data.
+The control question (§6.3) is: *which cross-terms must be zero, and which may stay?*
+
+### Decoupling (§6.3, "non-interacting control")
+
+- When two concerns must not interfere, drive the cross-terms to zero: isolate, single
+  responsibility, pure functions, no shared mutable state, explicit interfaces.
+- Once diagonalized, each subsystem can be designed as its own single-variable system —
+  dramatically simpler (§6.3). This is the control-theory justification for modular design.
+
+## LLM behavior pattern: Evaluate coupling before changing structure
+
+> "Decouple harmful coupling; keep beneficial coupling. Do not default to 'isolate everything'."
+
+When proposing a refactor or architecture change, the LLM **must** distinguish:
+- **Harmful coupling**: cross-terms that cause instability, race conditions, or incorrect results
+  under perturbation. These must be driven to zero.
+- **Beneficial coupling**: synchronization, shared invariants, backpressure that keeps the
+  system coherent. Removing these creates residual coupling elsewhere.
+
+Blindly removing all coupling: complicates the system (more sensors/actuators to fake the
+lost natural coupling); leaves residual coupling that *worsens* quality because the real plant
+is uncertain.
+
+## Coordination (§6.7) — do NOT over-decouple
+
+> Non-interacting control is not the only design principle. Often subsystems must *cooperate*
+> and stay in a coordination relation, not be independent.
+
+- Some coupling is **beneficial**: forced synchronization, shared invariants, mechanical
+  coupling that keeps things in lockstep.
+- Keep helpful coupling; cancel only the **harmful** cross-talk (§6.7: use controller coupling
+  to offset harmful plant coupling, preserve beneficial plant coupling).
+
+## Coordination error (协调偏差) — control the relation, not just absolutes
+
+- For coupled subsystems, regulate the **relation** between variables (e.g. "these two must
+  stay consistent / proportional / in sync"), not only each variable's absolute value.
+- Use an **internal setpoint**: when one subsystem moves, re-derive the others' targets from
+  the *actual* state, so the whole returns to coordination. External fixed setpoints alone
+  cannot hold a coordination relation under disturbance.
+- Example mappings: distributed cache + DB (consistency relation); producer/consumer queues
+  (backpressure relation); replicated services (quorum/sync relation).
+
+## Worked example: shared mutable state → harmful coupling / beneficial coupling
+
+**Harmful coupling (before):**
+```python
+# module_a.py
+_counter = 0
+
+def increment():
+    global _counter
+    _counter += 1
+
+# module_b.py  
+from module_a import _counter
+
+def report():
+    return _counter        # reads mutable state module_a owns
+```
+`module_b.report()` correctness depends on `module_a` execution order. Under concurrency
+this is a race condition — the cross-term is nonzero and causes instability. Decouple with
+explicit interface:
+
+**After (decoupled):**
+```python
+# module_a.py
+_state = {"count": 0}
+
+def increment(state):
+    state["count"] += 1
+    return state
+
+# module_b.py — no knowledge of module_a internals
+def report(state):
+    return state["count"]
+```
+
+**Beneficial coupling (preserved):**
+```python
+# Producer/consumer with backpressure (keep this coupling)
+queue = asyncio.Queue(maxsize=100)
+
+async def producer():
+    for item in source():
+        await queue.put(item)     # natural back pressure
+
+async def consumer():
+    while True:
+        item = await queue.get()  # consumption rate regulates production rate
+```
+Removing the queue and calling producer/consumer independently destroys the natural
+coordination. Regulate the *relation* (producer rate ≤ consumer rate), not just each
+absolute.
+
+---
+
+## Decision rule
+
+- Will interference cause incorrectness or instability? → **decouple** (diagonalize).
+- Must subsystems move together or hold a ratio/invariant? → **coordinate** (internal
+  setpoint + relation feedback), keep beneficial coupling.
+- Uncertain which? Prefer the simpler structure, then *test the coupling* under disturbance
+  before adding decoupling machinery.