Control-Theory Mental Model in Design-Control-Loop: Set Point, Sensor, Controller, Actuator, Disturbance, and Dampener Explained

The design-control-loop skill applies classical control-theory concepts to software engineering by treating the codebase as a dynamic system that uses feedback loops to automatically drive toward desired target states.

This control-theory mental model originates from the humanlayer/skills repository, where it reimagines code maintenance as a closed-loop control system. By separating measurement from decision-making and execution, the model enables automated, iterative improvements to codebases while maintaining human oversight.

Core Components of the Control-Theory Model

The control-loop-taxonomy.md file in the repository formally defines six essential components that map directly to classical control systems engineering.

Set Point: The Target Condition

The set point represents the desired state or target condition for a specific property of the codebase. Defined in SKILL.md, this is the reference value that the entire system attempts to maintain or achieve.

Examples of set points include:

• "Test coverage ≥ 80%"
• "No deprecated pattern imports remain"
• "All functions have type annotations"

The set point acts as the reference input against which the current system state is compared.

Sensor: State Measurement and Error Detection

The sensor obtains the current state (measured output) of the codebase and computes the error relative to the set point. According to control-loop-taxonomy.md, sensors can be implemented as:

• Lint tools (ESLint, Pylint)
• Static analysis scripts
• Test suites
• Custom database queries
• AI agents scanning for patterns

The sensor produces a measurable signal—such as a JSON array of lint violations or a coverage percentage—that quantifies the deviation from the set point.

Controller: Decision Logic

The controller transforms the error signal into a concrete, low-risk change plan (controller output). This component bridges the gap between measurement and action.

Controllers in the design-control-loop skill can be:

• Deterministic: Script-based logic that follows fixed rules
• Agentic: LLM-driven systems that interpret context and generate nuanced fixes

The controller's output specifies exactly what change should be made to reduce the error between the current state and the set point.

Actuator: Execution Mechanism

The actuator executes the change within the repository. In the humanlayer/skills implementation, this typically involves:

• A coding agent (such as Claude Code) modifying source files
• Automated refactoring tools
• Script-based transformations

The actuator opens pull requests containing the proposed changes, effectively applying the controller's calculated output to the system.

Disturbance: External Perturbations

Disturbance represents external factors that modify the codebase outside the control loop. As documented in control-loop-taxonomy.md, these include:

• Teammate commits introducing new code
• Dependency updates changing APIs
• Generated code from templates or scaffolding
• Merge conflicts and integration changes

Disturbances continuously push the system away from the set point, necessitating the feedback loop's corrective action.

Dampener: Regression Prevention

The dampener (also called the regression gate) serves as an optional safeguard that prevents the measured problem from worsening while the loop iterates. This component compares current sensor output against a baseline and blocks pull requests that would increase error magnitude.

The dampener ensures bounded, safe iteration by preventing runaway changes or negative feedback that could destabilize the codebase.

How the Feedback Loop Works in Practice

The control-theory mental model implements a classic negative feedback loop. The system architecture follows this flow:

Set Point ──► Compare ──► Measured Error ──► Controller ──► Actuator ──► System (repo)
      ▲                                                            │
      │                                                            ▼
 Disturbance ────────────────────────────────────────► System Output
          (external changes)                                 │
                                                            Sensor

The sensor continuously monitors the system output (current codebase state) and calculates the error (difference between set point and measurement). The controller processes this error to determine corrective action, which the actuator applies to the repository. The new state becomes the updated system output, feeding back into the sensor for the next iteration.

Human-in-the-Loop Integration

Unlike fully automated control systems, the design-control-loop skill explicitly maintains human oversight. After each iteration:

• Reviewers can adjust the memory-template.md file to guide future controller decisions
• Comments containing /iterate on pull requests trigger additional controller cycles
• Human feedback effectively tunes the controller parameters, similar to how human operators adjust PID controllers in industrial settings

This hybrid approach combines the consistency of automated feedback loops with the contextual judgment of human engineers.

Implementing the Control Loop in Code

The repository provides concrete implementation patterns for each component.

Python Pseudocode Implementation

This example illustrates the logical flow between components:

# 1️⃣ Sensor – measure current state

def sensor():
    # Example: run a lint rule and return list of violations

    result = subprocess.check_output(["eslint", "--format=json", "src/"])
    return json.loads(result)

# 2️⃣ Controller – decide next target

def controller(measurements, set_point):
    # Simple deterministic controller: pick the first violation above threshold

    for v in measurements:
        if v["severity"] > set_point["max_severity"]:
            return v["file"], v["line"]
    return None

# 3️⃣ Actuator – apply change via coding agent

def actuator(target):
    if not target:
        return
    file, line = target
    # Use a headless coding agent (e.g., Claude Code) to fix the issue

    subprocess.run([
        "claude-code", "--skill", "design-control-loop",
        "--file", file, "--line", str(line)
    ])

# 4️⃣ Loop driver

def run_loop():
    set_point = {"max_severity": 1}
    measurements = sensor()
    target = controller(measurements, set_point)
    actuator(target)

if __name__ == "__main__":
    run_loop()

The actual repository implementation stores these components as separate scripts under conventional paths like scripts/sensor.sh and scripts/controller.js, maintaining clean separation of concerns.

GitHub Actions Workflow

The workflow-template.yml demonstrates production deployment:

name: Design Control Loop
on:
  schedule: [cron: '0 2 * * *']   # daily run

  workflow_dispatch:

jobs:
  loop:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run sensor
        id: sensor
        run: ./scripts/sensor.sh > sensor.json
      - name: Run controller
        id: controller
        run: ./scripts/controller.js sensor.json > target.txt
      - name: Run actuator
        if: steps.controller.outputs.target != ''
        run: |
          ./scripts/actuator.sh $(cat target.txt)
      - name: Open PR
        uses: peter-evans/create-pull-request@v5
        with:
          commit-message: "Control‑loop update"
          branch: control-loop/${{ github.run_id }}

This workflow runs the complete feedback loop on a schedule, automatically creating pull requests when the controller detects deviations from the set point.

Why Control Theory Matters for Codebase Maintenance

Applying the control-theory mental model to software engineering provides distinct operational advantages:

• Observability: Separating measurement (sensor) from decision (controller) creates clear audit trails showing exactly why specific changes were proposed
• Boundedness: Each iteration produces small, reviewable changes rather than monolithic refactors, preventing runaway modifications
• Resilience: The continuous feedback mechanism automatically corrects for disturbances (such as dependency updates or team commits) that would otherwise drift the codebase away from standards
• Scalability: Multiple control loops can operate simultaneously on different set points (lint rules, coverage, security scans) without interference

Summary

• The set point defines target codebase conditions (e.g., coverage thresholds), stored conceptually in SKILL.md
• The sensor measures current state and calculates error using tools like linters or static analyzers, as defined in control-loop-taxonomy.md
• The controller converts error signals into specific corrective actions, implemented via deterministic scripts or LLM agents
• The actuator executes changes through coding agents and opens pull requests to modify the repository
• Disturbances represent external changes (commits, dependencies) that push the system away from the set point
• The dampener acts as a regression gate, preventing worsening conditions during iteration cycles
• The complete system forms a closed feedback loop that drives the codebase toward desired states while maintaining human oversight through memory-template.md and /iterate commands

Frequently Asked Questions

What is the control-theory mental model in software development?

The control-theory mental model treats a codebase as a dynamic system that requires continuous regulation to maintain desired properties. It adapts concepts from electrical and mechanical engineering—set points, sensors, controllers, and actuators—to automate code maintenance tasks like enforcing lint rules, maintaining test coverage, or migrating deprecated patterns.

How does the sensor component work in the design-control-loop skill?

The sensor executes measurement tools (ESLint, test runners, or custom scripts) to quantify the current codebase state relative to a target set point. It returns structured data—typically JSON—representing the error or deviation that needs correction. According to control-loop-taxonomy.md, sensors can be deterministic tools or AI agents capable of complex pattern recognition.

What is the difference between a controller and an actuator in this model?

The controller decides what change to make based on the error signal, while the actuator executes that decision in the repository. The controller is the "brain" that plans the fix (e.g., "replace deprecated import on line 42"), and the actuator is the "hands" that modify the file, typically through a coding agent or automated script. This separation allows the controller to be tested and versioned independently from execution mechanics.

Why is a dampener necessary in the control loop?

The dampener prevents oscillation or runaway conditions where the controller might make the codebase worse rather than better. By comparing current measurements to baselines and blocking regressions, it ensures that each iteration moves the system closer to the set point. This safety mechanism is particularly important when using LLM-based controllers that might generate unpredictable changes.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}