skill-systems-thinking 0.1.0 → 0.1.1

package/references/original-text.md

@@ -1,58 +1,58 @@
-# Reference: Original Text — Engineering Cybernetics
-
-Direct excerpts from Qian Xuesen (钱学森) & Song Jian (宋健), *Engineering Cybernetics*
-(工程控制论). Used here under fair use for scholarship and skill development. The original
-book and its mathematical foundations are the authoritative source; this skill is a faithful
-interpretation, not a replacement.
-
----
-
-## §1.1 稳定性的基本要求（节选）
-
-> 对于控制工程来说，稳定性是第一个要求。一个系统即使能在某些工作点给出正确
-> 的输出，但在扰动下发散、振荡或泄漏，这个系统就是**不稳定**的——无论其设计
-> 多么巧妙，都是没有实用价值的。
-
-This is the anchor for the law "Stability before everything." An LLM must verify
-perturbation behavior before proposing any feature or optimization.
-
----
-
-## §1.5 控制量与受控量（节选）
-
-> 受控量 x 是必须保持正确的量；控制量 u 是我们有自由施加作用的量。线性
-> 调节理论假定变量无界——但物理系统都有界。忽略边界会使"过渡过程时间与
-> 步长无关"这一结论在实践中不成立。
-
-This is the anchor for the principle "Name x before u; respect bounds." Every actuator
-saturates; every loop must have an explicit bound.
-
----
-
-## §3.7 反馈的基本作用（节选）
-
-> 反馈同时提高了准确度和响应速度。开环系统没有从误差中恢复的路径；闭环
-> 系统通过"作用→观测→校正"实现收敛。
-
-This is the anchor for "Closed loop beats open loop." After every non-trivial change,
-observe the actual state before declaring success.
-
----
-
-## §6.3 多变量控制的解耦（节选）
-
-> 当两个变量之间不应相互干扰时，应当使交叉项为零——隔离、单一职责、纯函数、
-> 无共享可变状态。一旦对角化，每个子系统就可以作为独立的单变量系统设计，
-> 从而大幅简化问题。
-
-This is the anchor for "Decouple what hurts, coordinate what helps."
-
----
-
-## §11 时滞系统（节选）
-
-> 时滞是稳定性的敌人。在回路延迟很大时，提高增益往往不是解决滞后响应的
-> 方法——它会 pushing the system toward instability。应当降低回路增益，或添加
-> 阻尼，或缩短回路。
-
-This is the anchor for "Never crank gain on a delayed loop; add damping instead."
+# Reference: Original Text — Engineering Cybernetics
+
+Direct excerpts from Qian Xuesen (钱学森) & Song Jian (宋健), *Engineering Cybernetics*
+(工程控制论). Used here under fair use for scholarship and skill development. The original
+book and its mathematical foundations are the authoritative source; this skill is a faithful
+interpretation, not a replacement.
+
+---
+
+## §1.1 稳定性的基本要求（节选）
+
+> 对于控制工程来说，稳定性是第一个要求。一个系统即使能在某些工作点给出正确
+> 的输出，但在扰动下发散、振荡或泄漏，这个系统就是**不稳定**的——无论其设计
+> 多么巧妙，都是没有实用价值的。
+
+This is the anchor for the law "Stability before everything." An LLM must verify
+perturbation behavior before proposing any feature or optimization.
+
+---
+
+## §1.5 控制量与受控量（节选）
+
+> 受控量 x 是必须保持正确的量；控制量 u 是我们有自由施加作用的量。线性
+> 调节理论假定变量无界——但物理系统都有界。忽略边界会使"过渡过程时间与
+> 步长无关"这一结论在实践中不成立。
+
+This is the anchor for the principle "Name x before u; respect bounds." Every actuator
+saturates; every loop must have an explicit bound.
+
+---
+
+## §3.7 反馈的基本作用（节选）
+
+> 反馈同时提高了准确度和响应速度。开环系统没有从误差中恢复的路径；闭环
+> 系统通过"作用→观测→校正"实现收敛。
+
+This is the anchor for "Closed loop beats open loop." After every non-trivial change,
+observe the actual state before declaring success.
+
+---
+
+## §6.3 多变量控制的解耦（节选）
+
+> 当两个变量之间不应相互干扰时，应当使交叉项为零——隔离、单一职责、纯函数、
+> 无共享可变状态。一旦对角化，每个子系统就可以作为独立的单变量系统设计，
+> 从而大幅简化问题。
+
+This is the anchor for "Decouple what hurts, coordinate what helps."
+
+---
+
+## §11 时滞系统（节选）
+
+> 时滞是稳定性的敌人。在回路延迟很大时，提高增益往往不是解决滞后响应的
+> 方法——它会 pushing the system toward instability。应当降低回路增益，或添加
+> 阻尼，或缩短回路。
+
+This is the anchor for "Never crank gain on a delayed loop; add damping instead."

package/references/stability.md

@@ -1,97 +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?
+# 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

@@ -1,84 +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)
-
+# 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

@@ -1,51 +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
+# 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