skill-systems-thinking 0.1.0 → 0.1.2

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

package/templates/debugging-checklist.md

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