Configures Claude Code hooks and Codex hooks.json/notify. Use when adding PreToolUse guards, Stop hooks, managed hooks, format-on-save, preflight, audits, or worktree/budget hooks.
日本語の概要は準備中です。原文の説明を表示しています。
PID/MPC/Kalman/anti-windup control primitives for feedback loops. Use when an autoscaler flaps, a controller overshoots after saturation, or budget pacing overspends at peak.
インストールする前に、エージェントに与えられる指示の中身を確認できます。
Use the primitive table to diagnose delay, noise, saturation, and conflicting actuator commands before choosing gains.
| Primitive | Problem It Solves | Key Parameters |
|---|---|---|
| PID Control | Drive output to setpoint despite steady-state error and disturbances | Kp, Ki, Kd; tune from plant response and validate margins |
| Feedback vs. Feedforward | Reactive-only loops ignore predictable disturbances | Plant model accuracy; disturbance measurability |
| Observability & Controllability | States you cannot see or reach make the loop fail silently | Controllability matrix rank; observability matrix rank |
| Lyapunov Stability | No proof that a loop converges; may oscillate or diverge | Lyapunov function V(x); dV/dt < 0 condition |
| MPC | One-step control ignores future constraints and couplings | Horizon N; cost matrices Q, R; constraint bounds |
| Kalman Filter | Noisy measurements degrade controller and monitoring accuracy | Process noise Q; measurement noise R; model (A, B, C) |
| Dead-Time Compensation | Transport lag causes oscillation or instability | Dead time L; plant model (delay-free) |
| Anti-Windup | Integrator saturates during limit-clamping → overshoot on release | Actuator min/max; tracking constant T_t |
| Gain Scheduling | Single fixed-gain controller fails across operating regimes | Scheduling variable σ; per-regime gain tables |
| Circuit Breaker & Backpressure | Cascading failure; unbounded queue growth | Failure threshold; timeout; half-open probe logic |
| Rate Limiting / Token Bucket | Bursts and retry storms overload downstream; 429s cascade | Fill rate r; burst capacity b; per-request cost s |
| DeePC / Behavioral Systems | MPC without a plant model — unknown dynamics make model-based prediction impossible | Hankel matrix T (data length); regularization λ_g, λ_y; persistency-of-excitation order |
Apply control-theory when:
Skip and use simpler alternatives when:
L/T above ~0.3, a diagnostic heuristic) — assess achievable bandwidth and margins; it is not proof PID is insufficientEach primitive above is expanded in references/primitives-overview.md and covered by standalone playbooks under assets/templates/control-theory/. Use references/formal-theory-map.md when the task needs stability assumptions, state-space reasoning, or robustness boundaries.
| Theory Area | Use When | Applied Primitives It Grounds |
|---|---|---|
| State-space systems | Need A/B/C/D models, poles, modes, controllability, observability | #3, #4, #5, #6 |
| Classical feedback | Need loop shaping, root locus, Bode/Nyquist, margins, PID tuning | #1, #2, #7, #8 |
| Stability theory | Need Lyapunov, input-to-state stability, passivity, bounded-input bounded-output | #4, #10, #11 |
| Optimal control | Need LQR/LQG, dynamic programming, constrained optimization, MPC | #5, #6 |
| Robust control | Need uncertainty margins, H-infinity, mu-synthesis, delay robustness | #4, #7, #9 |
| Adaptive/nonlinear control | Need parameter drift, operating regimes, saturation, nonlinear dynamics | #8, #9 |
| Stochastic estimation | Need Kalman assumptions, noise covariance, filtering vs smoothing | #6 |
| Networked/distributed control | Need queueing, backpressure, admission control, cascading-failure boundaries | #10, #11 |
| Behavioral systems / Willems' Fundamental Lemma | Need MPC without a parametric model; replace explicit prediction with data-driven Hankel matrix; unknown or nonlinear plant | #12 (DeePC) |
| Advanced regulatory control (ARC) | Need to decompose a multi-loop or multi-agent system into scoped elements with deterministic conflict resolution (selectors, split-range) rather than negotiation | #4, #5, #9 |
| Anti-Pattern | Control Theory Diagnosis | Fix |
|---|---|---|
| P-only autoscaler oscillates around target | Gain, delay, sampling, or saturation may be producing an underdamped loop | Identify the plant and total delay first; reduce gain or add phase lead/filtered derivative only if the response supports it (#1, #7, #8) |
| Integrator windup at actuator limit | Integral accumulates during saturation; releases as large overshoot | Anti-windup on every PID with bounded actuator (#8) — this is always required |
| Reactive controller ignores predictable patterns (load spikes, business hours) | Feedback-only; no model of known disturbances | Add feedforward schedule component (#2) |
| Observability gap: slow-changing state invisible to aggregate metric | Unobservable state mode in measurement design | Observability rank test (#3); add direct sensor or redesign C matrix |
| MPC tuned on stale system model | Model–reality mismatch degrades constraint handling and prediction | Retrain model online; add Kalman filter for state estimation (#6) |
| Dead time treated as additional plant gain | Transport lag misidentified → wrong tuning; oscillation | Smith Predictor (#7); estimate L via step test; never increase Kp to compensate |
| Retry storm after circuit re-closes | All blocked callers retry simultaneously; re-triggers failure | Token bucket with jitter (#11); stagger retries; half-open probe first (#10) |
| Agent loop with no convergence proof | No potential function that decreases per step | Define Lyapunov potential (e.g., remaining uncertainty); add hard step limit as fallback (#4) |
| Run-to-run divergence, a claim of "chaos", or an early-warning alert request | Lyapunov exponent (perturbation growth) is not the Lyapunov function (#4); noise sources and false alarms are unmeasured | Load references/nonlinear-dynamics-checks.md before measuring or alerting |
| Gain scheduled without bumpless transfer | Abrupt gain switch causes transient at boundary | Interpolate gains smoothly (#9); transfer integral state during switch |
| Backpressure signal not honored by producer | Queue grows despite signal | Enforce at ingress; drop or block if producer ignores signal (#10) |
| Multi-agent system resolves constraint conflicts by LLM negotiation | Conflict resolution delegated to a stochastic component; no deterministic priority order | Structural priority: MIN/MAX selectors for competing controlled variables, split-range for competing actuators; orchestrator resolves deterministically regardless of model output (#4, #5) |
| Retries amplify a partial failure into a full outage | Retry-driven positive feedback pushes loop gain above 1 (metastable failure) | Not owned here — see qa-resilience/references/cascading-failure-prevention.md (metastable failures) for the shedding response; pair with #10/#11 for the admission-side control |
| Misuse | Why It Is Wrong | Required Correction |
|---|---|---|
| Tuning PID by folklore constants | Ziegler-Nichols is an aggressive historical starting point, not a diagnosis or guarantee | Identify response, sample rate, delay, noise, and saturation; test gain/phase margins and re-tune on the actual plant |
| Ignoring actuator saturation | Integral windup creates overshoot and instability | Add anti-windup to bounded actuators |
| Treating delay as lower gain | Dead time changes phase and can destabilize loops | Estimate delay and use compensation or lower bandwidth |
| Claiming Kalman optimality outside assumptions | Kalman is optimal for linear Gaussian systems | Use EKF/UKF/particle filters with caveats |
| Applying MPC without model validation | Bad model makes constrained optimization confidently wrong | Validate model error and add robust margins. When plant model is unknown: use DeePC (#12) for a model-free alternative, a formulation with verified terminal, feasibility and model-error conditions if a stability certificate is required (Schimperna et al. 2025), or physics-informed sysid if partial domain knowledge exists (Sivaranjani et al. 2025, arXiv:2512.06315). |
| Using circuit breakers without backpressure | Fail-fast alone can shift overload elsewhere | Pair breakers with queues, rate limits, and admission control |
| Calling an agent loop stable because it has max steps | Max steps bound cost, not convergence | Define a potential function or monotone progress metric. For self-correction loops, iterate only while the error-correction rate over the error-introduction rate exceeds Acc/(1−Acc) (Liu & Meng 2026, arXiv:2604.22273; single preprint, treat as a heuristic) |
Visible oscillation is the late symptom. By the time replica count or bid multiplier is swinging, margin was gone cycles earlier. Earlier signals, roughly in order of how early they appear:
u (replicas added/removed, bid delta) is getting noisier while the error it's responding to is not, gain margin is shrinking — the loop is amplifying noise it used to damp. This shows up in stddev(Δu) well before it shows up in the tracked metric.Dead time is not just physical (network RTT, pod boot, replication lag). The measurement pipeline adds its own, and it is the one teams forget to model:
W-second window adds roughly W/2 seconds of effective dead time on top of the true delay — a 60 s Prometheus rate() window plus a 30 s scrape interval can add 45–60 s of lag the PID was never told about.It is rarely bad arithmetic. Nearly every production PID-like autoscaler, pacer, or admission controller that misbehaves is missing one or more of three universal preconditions, and most are missing all three at once:
The fix for each is well-known (Kalman/low-pass filtering, Smith Predictor, anti-windup) and documented in this skill — the expert judgment is diagnosing which of the three is actually dominant before reaching for a fix, since applying the wrong one (e.g., adding derivative gain to a problem that is really unmodeled dead time) makes the loop worse.
Closed-loop control is not free — it costs a measurement, a delay, and a risk of instability. Prefer open-loop (feedforward-only, or a scheduled/static policy) when:
L/T (dead time over dominant time constant, the same ratio as the 0.3 diagnostic above) above ~0.5 is where dead-time compensation or feedforward-first is worth the cost (template 07); it is an illustrative threshold, not a universal cutoff. If the disturbance is highly predictable and the loop's only job is to react to something already known in advance, feedback control is fighting a battle it starts already behind. Feedforward-first, feedback-as-trim is the correct architecture, not "add more gain."L/T above ~0.3 is a diagnostic heuristic)? → Dead-time compensation (#7)Use these stacks as starting designs. Validate the plant model, sensor quality, actuator bounds, and disturbance profile before production deployment.
Failure: HPA oscillates — adds pods, overshoots, removes pods, undershoots.
The Kubernetes HPA itself is not a PID controller: it applies a ratio rule, desiredReplicas = ceil(currentReplicas × currentMetricValue / desiredMetricValue), skips scaling when the ratio is within a tolerance of 1.0, and damps scale-down with a stabilization window that selects the highest recent desired-replica recommendation. It has no integral term, so there is no HPA windup to fix. Tune an HPA through its tolerance, stabilization windows, and scaling policies; check the kubernetes.io HPA page for current defaults. The PID stack below is for a custom controller that replaces or drives the HPA.
Data-driven variant (no plant model): DeePC (#12) or Koopman-MPC (kEDMD) can replace model-based MPC (#5) when system dynamics are unknown but input-output data is available. The exact DeePC LTI theorem requires input excitation of order T_ini+N+n and T_ini at least system lag; Koopman learning has its own representation/data/error assumptions. Compare tracking and smoothness locally; a stability certificate requires verified terminal/robustness conditions, not a method preference (see 12-deepc-behavioral.md).
For discrete units, output mapping, an illustrative latency example, and the replay helper, load references/discrete-controller-contract.md.
Failure: Agentic loop runs tool calls without bounded cost or convergence guarantee.
Finite action catalogs alone do not prove stability. Prinos et al. (arXiv:2605.03034) certify ISS for a specific cyber-defense architecture using its dynamics, observer, tools, and Lyapunov assumptions; verify analogous conditions for another loop.
Failure: Kubernetes HPA oscillates or lags — scales on CPU/memory while the actual bottleneck is KV-cache saturation and queue depth.
Reference implementation: WVA (Malvankar et al. 2026, arXiv:2603.09730). The paper reports gains over HPA; figures are in data/sources.json (single preprint, direction only).
Choose metrics that observe the identified bottleneck. KV-cache and queue depth can reveal inference saturation that CPU utilization misses; verify their relationship to the workload SLO.
Failure: Reactive HPA/KEDA lags behind demand — startup latency means pods arrive after the load spike, causing transient latency degradation.
When to prefer over PID-dominant autoscaling: Load pattern is predictable (periodic, trending) AND startup lag is the dominant latency contributor. If the load is unpredictable or bursty, fall back to the PID-dominant recipe above.
Contrast with PID-dominant recipe: PID-dominant is feedback-corrective (best for unpredictable disturbances); feedforward-dominant is anticipatory (best when load pattern is predictable and startup lag dominates the error budget).
Empirical reference: Tymoshenko, Maraschi & Collina (2026, arXiv:2604.19705) report lower median latency than KEDA and HPA under a steady ramp load on Node.js/Kubernetes (figures in data/sources.json). Rule: with predictable load and startup lag as the main error, feed forward. Caveat: Node.js-specific; generalizability to other runtimes unverified.
Failure: Several agents each defend a different objective (cost, latency, safety, quota) and conflicts are resolved by letting the models negotiate — so the resolution is nondeterministic, unauditable, and changes with prompt or temperature.
The advanced-regulatory-control (ARC) decomposition replaces negotiation with structure. Each feedback loop becomes one scoped agent carrying its own control-theoretic context (controlled variable, setpoint, chain priority, selector kind); an orchestrator encodes the priority order and resolves every conflict deterministically, outside the model.
Key insight: the safety property comes from the arbitration topology, not from the model. Constraint conflicts resolve identically regardless of what any agent outputs, which is what makes the trajectory auditable.
Reference: Nogueira & Skogestad (2026, arXiv:2606.30877). Evaluated on a dairy-barn ventilation loop with a small open-weight LLM; contribution is the architecture and auditable trajectories, not a benchmark win.
Failure: Ad spend oscillates — underspends overnight, overspends at peak, jams at bid cap.
data/sources.json and the reference files before deploying at scale. Stability-margin targets, sampling-rate rules and Smith-predictor limits are not stated here; take them from Åström & Murray (https://fbsbook.org), not from memory.Feedback system failure
-> Classify symptom: oscillation, windup, delay, overload, cascade, unobserved state
-> Map symptom to control primitive
-> Model loop, signal, actuator, delay, and constraint
-> Choose controller or protection pattern
+-- unstable or unobservable -> add measurement or redesign loop
+-- stable enough -> tune and simulate
-> Deploy with monitored thresholds and rollback criteria
data/sources.jsonWhen prior decisions or pitfalls are relevant, consult learnings.consolidated.md if present; use learnings.md only for needed history or as the available fallback. Otherwise skip both.
After applying it, if you encountered a pattern worth remembering, a mistake worth preventing, or a domain fact that surprised you, append one dated bullet to learnings.md via agents-skills-feedback-loop/scripts/append_learning.py. Do not modify SKILL.md itself.
まだレビューはありません。使ってみた感想をお寄せください。
概要と使いどころ
Configures Claude Code hooks and Codex hooks.json/notify. Use when adding PreToolUse guards, Stop hooks, managed hooks, format-on-save, preflight, audits, or worktree/budget hooks.
日本語の概要は準備中です。原文の説明を表示しています。
Configures and hardens Claude Code and Codex MCP servers. Use when connecting databases, APIs, SaaS, building servers, or serving a clearance-filtered knowledge base.
日本語の概要は準備中です。原文の説明を表示しています。
Owns instruction files: AGENTS.md, CLAUDE.md, personal and repo rules. Use when writing, pruning, auditing them, sharing rules across Claude and Codex, or fixing ignored rules.
日本語の概要は準備中です。原文の説明を表示しています。
Creates and audits agent skills: SKILL.md, references, scripts, runtime metadata. Use when writing, validating, or security-reviewing a skill, or fixing truncated skill listings.
日本語の概要は準備中です。原文の説明を表示しています。
Adds per-skill learnings loops for dated patterns, mistakes, and domain facts. Use when wiring skill memory, consolidation, or drift audits.
日本語の概要は準備中です。原文の説明を表示しています。
Chooses subagent, team, workflow, or debate and launches it on Claude Code or Codex. Use when delegating, running agent review boards, or installing shared agents.
日本語の概要は準備中です。原文の説明を表示しています。