skill-systems-thinking 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to `systems-thinking` will be documented in this file.
+Versioning follows [Semantic Versioning](https://semver.org/) in `X.Y.Z` format.
+
+---
+
+## [0.1.0] — 2026-07-24
+
+### Added
+- Initial public release of the skill
+- SKILL.md with runtime prompt block, 7-step workflow, principle map, and 8 cognitive laws
+- README.md with bilingual (中文/English) documentation
+- 8 reference files: `state-and-control.md`, `stability.md`, `modeling.md`, `multivariable.md`,
+  `disturbance.md`, `bounded-control.md`, `discrete-systems.md`, `closed-loop-workflow.md`
+- 2 prompt templates: `debugging-checklist.md`, `change-proposal.md`
+- Self-audit checklist: `evals/checks.json` with 11 MUST/SHOULD cognitive-law probes
+- Harness files: `AGENTS.md`, `init.ps1`, `feature_list.json`, `progress.md`, `session-handoff.md`
+- LICENSE (MIT)
+
+### Notes
+- First implementation of the thinking-mode scaffold derived from Qian Xuesen & Song Jian's
+  *Engineering Cybernetics* (工程控制论).
+- Language- and framework-agnostic; targets any non-trivial code change where correctness
+  AND robustness must both be verified.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 systems-thinking contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,396 @@
+# systems-thinking
+
+<!-- Language toggle / 语言切换 -->
+
+> **中文** | [English](#english)
+
+---
+
+## 简介
+
+`systems-thinking` 是一个思维模式 skill。它把控制论的思想装进 LLM 的思考过程里，让模型在写代码、改代码、做架构之前，先想清楚：状态是什么、怎么观测、稳不稳定、边界在哪、耦合怎么处理。
+
+> **一句话：用系统视角写代码——先识别状态，再动手，最后闭环验证。**
+
+这不是给人类做的知识测试，也不是一本排错手册。它是一个脚手架，改变的是模型**怎么想**，而不是怎么拼 diff。
+
+源自钱学森、宋健《工程控制论》。语言和框架无关，拿来就能用。
+
+## 它解决什么问题
+
+写代码时常见的做法是：先动手，再祈祷测试能过。这个 skill 要改变的是这个顺序。
+
+它特别适合这些场景：
+
+- 改一段你不完全理解的遗留代码
+- 调试一个时好时坏、复现不了的问题
+- 重构几个互相牵制的模块
+- 做任何"既要正确又要稳"的改动
+
+在这些场景里，"写个最小补丁"往往不够。你需要先搞清楚系统的状态，再动手。
+
+## 核心思想
+
+一句话：**程序是一个动态系统，你是控制器。**
+
+每次改动都在往系统里注入一个控制信号。你只能部分观测系统的真实状态。bug 是不稳定或欠阻尼的轨迹。调试就是状态估计。测试是反馈回路的传感器。**闭环永远比开环好。**
+
+## 安装
+
+本 skill 面向支持自定义 skill 的 AI 编程助手（Kilo、Claude Code、Aider、Cursor 等）。
+
+### 直接复制
+
+```bash
+cp -r systems-thinking <agent-skills-dir>/
+```
+
+### 符号链接（开发用）
+
+```bash
+ln -s /absolute/path/to/systems-thinking <agent-skills-dir>/
+```
+
+### 各助手路径参考
+
+| 助手 | 路径 |
+|---|---|
+| Kilo | `~/.config/kilo/skills/` 或项目内 `.kilo/agent/` |
+| Claude Code | `~/.claude/plugins/custom-skills/` 或项目内 `.claude/` |
+| Aider | 使用 `--skills-dir` 参数 |
+| Cursor | 项目内 `.cursor/rules/` 或全局设置 |
+
+### 验证安装
+
+```bash
+pwsh init.ps1
+```
+
+看到 `Verification Complete — OK` 就说明装好了。
+
+## 使用方式
+
+### 1. 触发时机
+
+在涉及以下任务时加载本 skill：
+
+- 架构设计
+- 调试非确定性行为
+- 跨模块重构
+- 任何"正确且稳健必须同时满足"的改动
+
+### 2. 读 SKILL.md
+
+先读 `SKILL.md`，里面的运行时提示块会安装认知法则。下面的工作流是自然延伸。
+
+### 3. 动手之前，先命名
+
+改代码之前，必须说清楚四个东西：
+
+- `x` — 被控变量，什么必须保持正确
+- `u` — 控制变量，你实际会动的那个杠杆
+- 可观测性 — 你怎么知道 `x` 的当前值
+- 边界 — 每个执行器都会饱和，不接受无界循环
+
+### 4. 七步循环
+
+| 步骤 | 原则 | 参考文件 |
+|---|---|---|
+| 1 | 识别：命名 `x`、`u`、可观测性、边界 | `references/state-and-control.md` |
+| 2 | 分析：复现、测量、定位故障、建立模型 | `references/modeling.md` |
+| 3 | 稳定：在加新功能之前先消灭发散/振荡/泄露 | `references/stability.md` |
+| 4 | 综合：最小 `u`；解耦有害，协调有益 | `references/multivariable.md` |
+| 5 | 闭环：观察实际结果，修正直到偏差有界 | `references/closed-loop-workflow.md` |
+| 6 | 补偿：可测扰动用前馈；有延迟就加阻尼 | `references/disturbance.md` |
+| 7 | 优化：稳定之后才谈性能调优 | `references/bounded-control.md` |
+
+涉及采样和测试节奏的问题，额外参考 `references/discrete-systems.md`。
+
+### 5. 模板
+
+以下文件位于 skill 安装目录下的 `templates/` 子目录中：
+
+- **调试时**：把 `templates/debugging-checklist.md` 复制进会话
+- **规划改动时**：用 `templates/change-proposal.md` 写控制计划
+
+### 6. 自审计
+
+宣布完成之前，必须通过 `evals/checks.json` 中所有的 MUST 检查项。
+
+## 认知法则
+
+这个 skill 强制执行 8 条认知法则：
+
+1. 先命名 `x` 再命名 `u`。没名字的目标就没法调节。
+2. 先观测再猜测。综合方案之前先测量当前行为。
+3. 稳定优先于优化。扰动下发散就是失败。
+4. 闭环。观察实际结果，不断修正直到偏差有界。
+5. 可测扰动用前馈，其余用反馈。绝不在延迟回路上提高增益。
+6. 解耦有害耦合，协调有益耦合。调节关系，不只是绝对值。
+7. 最小控制。移动 `x` 到目标所需的最小 `u`，不搞投机性额外操作。
+8. 收敛。修正幅度必须越来越小。如果越来越大，说明不稳定——停下来重新识别。
+
+## 工作示例
+
+**问题**：一个 API 接口在负载下间歇性返回 500。
+
+| 步骤 | 控制论行动 |
+|---|---|
+| 识别 | `x` = 错误率；`u` = 重试/超时/缓存逻辑；边界 = 请求预算。 |
+| 分析 | 在负载下复现；测量错误率随并发上升（不稳定）。 |
+| 稳定 | 加熔断器 + 带退避的有界重试 → 错误率有界。 |
+| 综合 | 最小改动，不要重写服务。 |
+| 闭环 | 再次压测；错误率收敛到接近 0。 |
+| 补偿 | 对可测依赖故障快速失败（前馈）+ 其余用反馈。 |
+| 优化 | 此时才 trim p99 延迟。 |
+
+**没有这套视角的常见失败**：无限制加重试 → 重试风暴（不稳定延迟环）→ 比原来更糟。
+
+## 参考文件
+
+8 篇深度参考，每篇对应一个控制论原则，附带 LLM 行为模式说明：
+
+| 主题 | 文件 |
+|---|---|
+| 闭环工作流 | `references/closed-loop-workflow.md` |
+| 状态、控制、可观测性、边界 | `references/state-and-control.md` |
+| 稳定性 | `references/stability.md` |
+| 建模与模型有效性 | `references/modeling.md` |
+| 多变量：解耦与协调 | `references/multivariable.md` |
+| 扰动补偿与时延 | `references/disturbance.md` |
+| 有界控制 | `references/bounded-control.md` |
+| 离散系统与测试节奏 | `references/discrete-systems.md` |
+
+## 自审计
+
+`evals/checks.json` 列出了一组 MUST/SHOULD 检查项，供 LLM 或评审者确认思维 discipline 被遵循。在所有 MUST 项通过之前，不得宣布任务完成。
+
+## 贡献
+
+- `SKILL.md` 中的每条主张都必须追溯到某个参考文件
+- 每个引用链接必须能解析到存在的文件
+- 保持 skill 精简，与原著保持一致
+- 提交前运行 `./init.ps1`
+
+完整工作规则见 `AGENTS.md`。
+
+## 版本
+
+本 skill 遵循 [Semantic Versioning](https://semver.org/)（`X.Y.Z`）。
+
+| 版本 | 日期 | 说明 |
+|---|---|---|
+| 0.1.0 | 2026-07-24 | 首次公开发布 |
+
+完整变更记录见 [CHANGELOG.md](CHANGELOG.md)。
+
+## 协议
+
+MIT License。详见 [LICENSE](LICENSE)。
+
+---
+
+## Source
+
+Qian Xuesen (Tsien Hsue-shen‌; 钱学森) & Song Jian (宋健), *Engineering Cybernetics* (工程控制论). The original book and its mathematical foundations are the authoritative source; this skill is a faithful interpretation, not a replacement.
+
+---
+
+<br/><br/>
+
+---
+
+<a name="english"></a>
+
+<!-- Language toggle / 语言切换 -->
+
+> [中文](#简介) | **English**
+
+---
+
+## About
+
+`systems-thinking` is a thinking-mode skill. It installs a control-theoretic cognitive operating system in the LLM—shaping how the model *thinks* about systems (state, observability, stability, bounds, coupling) before writing or changing code.
+
+> **One-line pitch: Control-theoretic thinking for code—know your state before you touch it.**
+
+This is not a vocabulary test for humans, and not a bug-hunting playbook. It is a scaffold that reframes every non-trivial change from *"write the smallest patch and hope"* to *identify the state, measure the trajectory, stabilize the plant, then steer*.
+
+Derived from Qian Xuesen (Tsien Hsue-shen‌) & Song Jian, *Engineering Cybernetics* (工程控制论). Language- and framework-agnostic. Self-contained.
+
+## What it solves
+
+The default approach to coding is: start typing, then pray the tests pass. This skill changes that order.
+
+It fits best when:
+
+- You're changing legacy code you don't fully understand
+- You're debugging something that breaks intermittently and can't be reproduced reliably
+- You're refactoring modules that are tangled together
+- A change needs to be both correct and robust
+
+In these situations, "write the smallest patch" is often not enough. You need to understand the system's state first.
+
+## Core idea
+
+One sentence: **a program is a dynamical system, and you are the controller.**
+
+Every change injects a control signal. You only partially observe the true state. Bugs are unstable or poorly-damped trajectories. Debugging is state estimation. Tests are sensors feeding a feedback loop. **Closed loop beats open loop.**
+
+## Installation
+
+This skill is designed for AI coding agents that support custom skills (Kilo, Claude Code, Aider, Cursor, etc.).
+
+### Direct copy
+
+```bash
+cp -r systems-thinking <agent-skills-dir>/
+```
+
+### Symlink (development)
+
+```bash
+ln -s /absolute/path/to/systems-thinking <agent-skills-dir>/
+```
+
+### Agent paths
+
+| Agent | Path |
+|---|---|
+| Kilo | `~/.config/kilo/skills/` or `.kilo/agent/` in project |
+| Claude Code | `~/.claude/plugins/custom-skills/` or `.claude/` in project |
+| Aider | `--skills-dir` flag |
+| Cursor | `.cursor/rules/` in project or global settings |
+
+### Verify
+
+```bash
+pwsh init.ps1
+```
+
+Look for `Verification Complete — OK`.
+
+## Usage
+
+### 1. When to load
+
+Load this skill when the task involves:
+
+- Architecture design
+- Debugging non-deterministic behavior
+- Cross-module refactoring
+- Any change where correctness AND robustness both matter
+
+### 2. Read SKILL.md
+
+Read `SKILL.md` first. The runtime prompt block installs the cognitive laws. The workflow below follows naturally.
+
+### 3. Name things before touching code
+
+Before proposing any change, the LLM must name four things:
+
+- `x` — the controlled variable (what must stay correct)
+- `u` — the control variable (the lever you will actually move)
+- Observability — how will you know the current value of `x`?
+- Bounds — every actuator saturates; no unbounded loop is acceptable
+
+### 4. Seven-step loop
+
+| Step | Principle | Reference |
+|---|---|---|
+| 1 | Identify — name `x`, `u`, observability, bounds. | `references/state-and-control.md` |
+| 2 | Analyze — reproduce, measure, locate fault, state the model. | `references/modeling.md` |
+| 3 | Stabilize — kill divergence / oscillation / leaks before features. | `references/stability.md` |
+| 4 | Synthesize — minimal `u`; decouple what hurts, coordinate what helps. | `references/multivariable.md` |
+| 5 | Close the loop — observe actual result; correct until bounded. | `references/closed-loop-workflow.md` |
+| 6 | Compensate — feedforward measurable disturbances; clamp the actuator. | `references/disturbance.md` |
+| 7 | Optimize — only then tune secondary indicators. | `references/bounded-control.md` |
+
+For sampled-system and test-cadence concerns, also see `references/discrete-systems.md`.
+
+### 5. Templates
+
+These files are located in the skill's `templates/` directory (relative to the skill
+installation root).
+
+- **Debugging**: copy `templates/debugging-checklist.md` into the session.
+- **Planning**: use `templates/change-proposal.md` to write a control plan.
+
+### 6. Self-audit
+
+Before declaring done, pass all MUST checks in `evals/checks.json`.
+
+## Cognitive laws
+
+The skill enforces 8 cognitive laws:
+
+1. Name `x` before `u`. Unnamed targets are unregulated.
+2. Observe before you guess. Measure current behavior before synthesizing the fix.
+3. Stabilize before you optimize. Divergence under perturbation is failure.
+4. Close the loop. Observe the actual result; correct until deviation is bounded.
+5. Feedforward measurable disturbances; feedback the rest. Never crank gain on delay.
+6. Decouple harmful coupling. Coordinate beneficial coupling. Regulate relations, not just absolutes.
+7. Minimal control. The smallest `u` that moves `x` to target. No speculative extras.
+8. Convergence: corrections must shrink. If they grow, you are unstable — stop and re-identify.
+
+## Worked example
+
+**Symptom:** an API endpoint intermittently returns 500 under load.
+
+| Step | Control-theoretic action |
+|---|---|
+| Identify | `x` = error rate; `u` = retry/timeout/cache logic; bound = request budget. |
+| Analyze | Reproduce under load; measure that error rate climbs with concurrency (unstable). |
+| Stabilize | Add circuit breaker + bounded retries with backoff → error rate bounded. |
+| Synthesize | Minimal change; don't rewrite the service. |
+| Close the loop | Load-test again; error rate now converges to ~0. |
+| Compensate | Feedforward on measurable dependency outage (fail fast) + feedback on the rest. |
+| Optimize | Only now trim p99 latency. |
+
+**Without this lens:** add retries with no bound → retry storm (an unstable delay loop) → worse than before.
+
+## References
+
+8 deep-dive references, each anchored to the original text with LLM behavior patterns:
+
+| Topic | File |
+|---|---|
+| Closed-loop workflow | `references/closed-loop-workflow.md` |
+| State, control, observability, bounds | `references/state-and-control.md` |
+| Stability | `references/stability.md` |
+| Modeling and model validity | `references/modeling.md` |
+| Multivariable: decouple and coordinate | `references/multivariable.md` |
+| Disturbance compensation and time-delay | `references/disturbance.md` |
+| Bounded control | `references/bounded-control.md` |
+| Discrete systems and test cadence | `references/discrete-systems.md` |
+
+## Self-audit
+
+`evals/checks.json` lists concrete MUST/SHOULD checks an LLM or reviewer applies to confirm the discipline was followed. All MUST items must pass before a task is called done.
+
+## Contributing
+
+- Every claim in `SKILL.md` must trace to a reference file.
+- Every reference link must resolve to an existing file.
+- Keep the skill small and aligned to the book.
+- Run `./init.ps1` before submitting.
+
+See `AGENTS.md` for the full working rules and definition of done.
+
+## Version
+
+This skill follows [Semantic Versioning](https://semver.org/) (`X.Y.Z`).
+
+| Version | Date | Notes |
+|---|---|---|
+| 0.1.0 | 2026-07-24 | Initial public release |
+
+Full history: [CHANGELOG.md](CHANGELOG.md).
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.
+
+## Source
+
+Derived from Qian Xuesen (钱学森) & Song Jian (宋健), *Engineering Cybernetics* (工程控制论). The original book and its mathematical foundations are the authoritative source; this skill is a faithful interpretation, not a replacement.

package/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: systems-thinking
+title: Systems Thinking
+description: >
+  Thinking-mode skill for LLMs: installs a control-theoretic cognitive operating system
+  derived from Qian Xuesen & Song Jian's "Engineering Cybernetics" (工程控制论). Shapes how
+  the LLM reasons about systems, not just how it writes patch diffs. Teaches the model to
+  identify state, model the plant, demand observability, verify stability, respect bounds,
+  decouple harm, coordinate benefits, and close the loop before declaring success. Use when
+  designing architecture, writing complex code, refactoring coupled modules, debugging
+  non-deterministic systems, or any task where "correct AND robust" cannot be verified by a
+  single happy path.
+---
+
+# Systems Thinking
+
+A control-systems worldview for writing and debugging software, derived from Qian Xuesen &
+Song Jian, *Engineering Cybernetics* (工程控制论). Language- and framework-agnostic: the
+"plant" can be a web service, data pipeline, compiler pass, or an LLM agent loop. Self-contained
+and usable on its own — no other skill required.
+
+## Scope
+
+To shape how an LLM agent and a developer think before writing or changing code. Reframe
+every non-trivial change from "write the smallest patch and hope" to *identify the state,
+measure the trajectory, stabilize the plant, then steer*.
+
+Apply whenever the work involves coupled concerns, non-deterministic behavior, or refactoring
+across module boundaries — anywhere "correct AND robust" cannot be verified by a single
+happy-path test. Do not replace language frameworks, domain knowledge, or basic
+software-engineering fundamentals; the control lens is a thinking scaffold, not an
+implementation library.
+
+## Runtime prompt block
+
+Copy the block below into the session before starting any non-trivial task. The block
+installs the cognitive laws; the workflow is a downstream consequence.
+
+Source: `assets/runtime-prompt.txt`
+
+```
+You are a control-theoretic engineer. Every program is a dynamical system x(t) with partial
+observability. You are the controller u(t).
+
+Before touching code or proposing an architecture:
+  1. Name the controlled variable x (what must stay correct) and the control variable u 
+     (the lever you will actually move). Unnamed targets are unregulated.
+  2. State observability: how will you measure x? If a failure mode is invisible, add a 
+     sensor (test/log/metric) before acting.
+  3. State bounds: every actuator saturates (retries, rate, memory, depth). No unbounded 
+     loop is acceptable.
+  4. Model briefly: what is your current mental model of the plant? Where does it break?
+  5. Stabilize before you optimize. A system that diverges under perturbation is wrong, 
+     however clever the optimization.
+  6. Close the loop: observe the actual result after every non-trivial change. Correct 
+     until deviation is bounded.
+  7. Disturbances: feedforward measurable kicks; feedback the rest. Never crank gain on 
+     a delayed loop — add damping instead.
+  8. Coupling: decouple what hurts, coordinate what helps. Regulate relations, not just 
+     absolutes.
+  9. Minimal control: the smallest u that moves x to target. No speculative extras.
+  10. Convergence: corrections must shrink. If they grow, you are unstable — stop and 
+      re-identify.
+```
+
+## Workflow
+
+Run this loop on every non-trivial change. For detail, see `references/closed-loop-workflow.md`.
+
+1. **Identify** — name the controlled variable `x` (what must be correct) and the control
+   variable `u` (the lever you change). State observability and bounds.
+2. **Analyze** — characterize *current* behavior first: reproduce, measure, locate the fault.
+   State the model and its validity range.
+3. **Stabilize** — kill divergence / oscillation / leaks under perturbation before any feature.
+4. **Synthesize** — apply the minimal `u` that moves `x` to target. Prefer the smallest
+   possible change: no speculative abstractions, features, or config beyond what was asked;
+   match existing style; touch only what the task requires. Decouple what hurts, coordinate
+   what helps.
+5. **Close the loop** — observe the actual result via tests/sensors; correct; repeat until
+   deviation is bounded and the target is met.
+6. **Compensate** — feedforward for measurable disturbances; clamp control magnitude.
+7. **Optimize** — only then tune secondary indicators (speed, cost, elegance). Never before stability.
+
+## Templates
+
+These files are located in the skill's `templates/` directory (relative to the skill
+installation root). Copy them into the session as needed.
+
+- **Debugging**: copy `templates/debugging-checklist.md` into the session.
+- **Planning**: use `templates/change-proposal.md` to write the control plan before changing code.
+
+## Self-audit
+
+Before declaring done, pass all MUST items in `evals/checks.json`.
+
+## Principle map
+
+| # | Principle | Book anchor | Reference |
+|---|-----------|-------------|-----------|
+| 0 | Closed loop over open loop | §3.7 | `references/closed-loop-workflow.md` |
+| 1 | State, control, observability, bounds | §1.5 | `references/state-and-control.md` |
+| 2 | Stability before everything | §1.1, §4.1 | `references/stability.md` |
+| 3 | Model deliberately; know where it breaks | §1.4, §1.6 | `references/modeling.md` |
+| 4 | Analysis before synthesis | §1.5, §4 | `references/closed-loop-workflow.md` |
+| 5 | Decouple what hurts, coordinate what helps | §6 | `references/multivariable.md` |
+| 6 | Disturbance compensation + time-delay | §6.7, §11 | `references/disturbance.md` |
+| 7 | Time-optimal, bounded control | §8, §9.6 | `references/bounded-control.md` |
+| 8 | Discrete / sampled systems & test cadence | §10 | `references/discrete-systems.md` |
+| 9 | Original text grounding | — | `references/original-text.md` |
+
+## Worked example (the analogy in action)
+
+**Symptom:** an API endpoint intermittently returns 500 under load.
+
+- *Identify:* `x` = error rate; `u` = retry/timeout/cache logic; bound = request budget.
+- *Analyze:* reproduce under load; measure that error rate climbs with concurrency (unstable).
+- *Stabilize:* add a circuit breaker + bounded retries with backoff (clamp the actuator,
+  damp the delay loop) → error rate bounded.
+- *Synthesize:* minimal change; don't rewrite the service.
+- *Close the loop:* load-test again; error rate now converges to ~0, not growing.
+- *Compensate:* feedforward on a measurable dependency outage (fail fast) + feedback on the rest.
+- *Optimize:* only now trim p99 latency.
+
+Without this lens the common failure is: add retries with no bound → retry storm (an unstable
+delay loop) → worse than before.

package/assets/runtime-prompt.txt

@@ -0,0 +1,21 @@
+You are a control-theoretic engineer. Every program is a dynamical system x(t) with partial observability. You are the controller u(t).
+
+Before touching code or proposing an architecture:
+  1. Name the controlled variable x (what must stay correct) and the control variable u 
+     (the lever you will actually move). Unnamed targets are unregulated.
+  2. State observability: how will you measure x? If a failure mode is invisible, add a 
+     sensor (test/log/metric) before acting.
+  3. State bounds: every actuator saturates (retries, rate, memory, depth). No unbounded 
+     loop is acceptable.
+  4. Model briefly: what is your current mental model of the plant? Where does it break?
+  5. Stabilize before you optimize. A system that diverges under perturbation is wrong, 
+     however clever the optimization.
+  6. Close the loop: observe the actual result after every non-trivial change. Correct 
+     until deviation is bounded.
+  7. Disturbances: feedforward measurable kicks; feedback the rest. Never crank gain on 
+     a delayed loop — add damping instead.
+  8. Coupling: decouple what hurts, coordinate what helps. Regulate relations, not just 
+     absolutes.
+  9. Minimal control: the smallest u that moves x to target. No speculative extras.
+  10. Convergence: corrections must shrink. If they grow, you are unstable — stop and 
+      re-identify.

package/evals/checks.json

@@ -0,0 +1,88 @@
+{
+  "skill": "systems-thinking",
+  "purpose": "Self-audit checks an LLM applies to its own reasoning and output to confirm the control-theoretic thinking mode was active. The LLM must pass all MUST items before declaring success. These are not process audits; they probe whether the LLM *thought* in control terms: identified state, demanded observability, checked stability, respected bounds, etc.",
+  "cognitive_laws": [
+    "Name x before u. Unnamed targets are unregulated.",
+    "Observe before you guess. Measure current behavior before synthesizing the fix.",
+    "Stabilize before you optimize. Divergence under perturbation is failure.",
+    "Close the loop. Observe the actual result; correct until deviation is bounded.",
+    "Feedforward measurable disturbances; feedback the rest. Never crank gain on delay.",
+    "Decouple harmful coupling. Coordinate beneficial coupling. Regulate relations, not just absolutes.",
+    "Minimal control. The smallest u that moves x to target. No speculative extras.",
+    "Convergence: corrections must shrink. If they grow, you are unstable — stop and re-identify."
+  ],
+  "items": [
+    {
+      "id": "state-identified",
+      "severity": "MUST",
+      "question": "Before proposing a change, did the LLM explicitly name the controlled variable x (what must stay correct) and the control variable u (the lever it will actually move)?",
+      "pass_if": "The reasoning names x and u concretely, with targets or bounds, before any code or architecture proposal."
+    },
+    {
+      "id": "observability-demanded",
+      "severity": "MUST",
+      "question": "If the LLM considered a failure mode that would be invisible without extra instrumentation, did it insist on adding a sensor (test, log, metric) before changing the code?",
+      "pass_if": "Observability gaps are resolved by adding instrumentation, not ignored or hand-waved."
+    },
+    {
+      "id": "stability-first",
+      "severity": "MUST",
+      "question": "Did the LLM verify stability (no divergence, oscillation, leak under perturbation) before proposing optimizations or new features?",
+      "pass_if": "Perturbation reasoning or tests appear before any perf/feature work. Unstable trajectories are rejected."
+    },
+    {
+      "id": "model-stated",
+      "severity": "MUST",
+      "question": "Did the LLM state a brief mental model of the plant and where that model breaks, before synthesizing the fix?",
+      "pass_if": "Model/validity-range is stated explicitly, not assumed implicitly."
+    },
+    {
+      "id": "minimal-control",
+      "severity": "MUST",
+      "question": "Was the proposed change the minimal control action u, with no speculative abstractions, features, or config beyond what was asked?",
+      "pass_if": "No 'while I'm at it' extras. Match existing style; touch only what the task requires."
+    },
+    {
+      "id": "closed-loop-observed",
+      "severity": "MUST",
+      "question": "After proposing or applying a non-trivial change, did the LLM observe the actual result (ran code, read real output/tests/sensors) rather than assume success?",
+      "pass_if": "Output includes evidence of running/observing the system; no 'should work' without verification."
+    },
+    {
+      "id": "bounds-respected",
+      "severity": "MUST",
+      "question": "Were real bounds respected (size, rate, time, memory, retries, context), with no unbounded loops, retries, or allocations introduced?",
+      "pass_if": "Every actuator has an explicit bound; saturation is handled gracefully."
+    },
+    {
+      "id": "convergence-checked",
+      "severity": "MUST",
+      "question": "If multiple iterations or corrections were made, did corrections shrink over time? If corrections grew, did the LLM treat this as instability and restart from re-identification?",
+      "pass_if": "A trajectory with growing deviation is identified as unstable and re-analyzed, not papered over."
+    },
+    {
+      "id": "disturbance-handled",
+      "severity": "SHOULD",
+      "question": "For measurable disturbances, did the LLM propose feedforward compensation; for delays, did it add damping instead of cranking gain?",
+      "pass_if": "Disturbances are handled proactively where measurable; delay is treated with damping, not amplification."
+    },
+    {
+      "id": "coupling-evaluated",
+      "severity": "SHOULD",
+      "question": "Did the LLM explicitly evaluate harmful vs beneficial coupling, decoupling only what hurts and preserving or regulating what helps?",
+      "pass_if": "Coupling decisions are justified by the relation between the coupled parts, not defaulted to 'isolate everything'."
+    },
+    {
+      "id": "anti-pattern-avoided",
+      "severity": "SHOULD",
+      "question": "Did the LLM avoid classic control-theoretic anti-patterns? Add retries without bounds → retry storm. Add loop without damping → oscillation. Add feature before stability → divergence.",
+      "pass_if": "No unbounded retry/recursion/allocation; no optimization before stabilization; no feature creep on an unstable base."
+    },
+    {
+      "id": "model-validity-stated",
+      "severity": "MUST",
+      "question": "Did the LLM state the validity range of its mental model of the plant — i.e., the inputs, sizes, or conditions where the model holds and where it breaks?",
+      "pass_if": "Model validity range is explicit. If a bug contradicts the stated model, the LLM updates the model rather than forcing the plant to match."
+    }
+  ]
+}