# Control-Theory Mental Model Documentation in the Design-Control-Loop Skill

> Find detailed control-theory mental model documentation for the design-control-loop skill in the humanlayer/skills repository. Access key markdown files for insights.

- Repository: [HumanLayer/skills](https://github.com/humanlayer/skills)
- Tags: api-reference
- Published: 2026-09-13

---

**The control-theory mental model for the design-control-loop skill is documented in [`control-loop-taxonomy.md`](https://github.com/humanlayer/skills/blob/main/control-loop-taxonomy.md) and [`SKILL.md`](https://github.com/humanlayer/skills/blob/main/SKILL.md), located in the `humanlayer/skills` repository under the `plugins/design-control-loop/skills/design-control-loop/` path.**

The `design-control-loop` skill in the HumanLayer skills repository treats software repositories as dynamic systems governed by feedback loops. By applying classic control-theory concepts, the skill creates an **agentic control loop** that continuously measures, compares, and adjusts codebase states. The complete mental-model description spans two primary reference files that map control-theory terminology to software engineering workflows.

## Primary Documentation Files

The control-theory mental model is split between the skill definition and the detailed taxonomy.

### SKILL.md: The Entry Point

Located at [`plugins/design-control-loop/skills/design-control-loop/SKILL.md`](https://github.com/humanlayer/skills/blob/main/plugins/design-control-loop/skills/design-control-loop/SKILL.md), this file introduces the mental model in the "The mental model" section. It provides a high-level workflow overview and directs practitioners to the taxonomy file for deeper architectural study. This document serves as the primary entry point for understanding how the skill conceptualizes autonomous code maintenance.

### control-loop-taxonomy.md: The Deep Reference

The complete technical specification lives in [`plugins/design-control-loop/skills/design-control-loop/references/control-loop-taxonomy.md`](https://github.com/humanlayer/skills/blob/main/plugins/design-control-loop/skills/design-control-loop/references/control-loop-taxonomy.md). This file defines the five core components of the feedback system and includes a Mermaid diagram illustrating the feedback flow between them. Lines 66-76 of this file contain specific design questions that ensure the resulting loop remains **observable**, **bounded**, and **reviewable**.

## The Five Components of the Control Loop

The taxonomy treats the codebase as a dynamic system with five interacting components:

- **Set point**: The desired target state (e.g., "test coverage ≥ 80%").
- **Sensor**: Measures the current state and quantifies the gap between reality and the set point.
- **Controller**: Transforms the measurement into a concrete, executable next step.
- **Actuator**: A coding agent (such as Claude or Codex) that applies the change and opens a pull request.
- **Disturbance**: External factors—such as team commits, dependency updates, or previously generated code—that push the system away from the set point.

Together, these components create a closed-loop system where the sensor continuously feeds the controller information about the gap, and the actuator works to minimize that gap despite ongoing disturbances.

## Implementing the Mental Model

The taxonomy provides theoretical grounding, but the skill includes concrete implementation patterns for each component.

### Visualizing the Feedback Loop

The [`control-loop-taxonomy.md`](https://github.com/humanlayer/skills/blob/main/control-loop-taxonomy.md) file contains the following Mermaid diagram that illustrates how signals flow through the system:

```mermaid
flowchart LR
  SetPoint[Set point] --> Compare((Compare))
  Measured[Measured output] --> Compare
  Compare --> Error[Measured error]
  Error --> Controller[Controller]
  Controller --> Actuator[Actuator]
  Actuator --> System[System / Repository]
  Disturbance[Disturbance] --> System
  System --> Output[System output]
  Output --> Sensor[Sensor]
  Sensor --> Measured

```

### Sensor Implementation

The sensor acts as the measurement device. An illustrative sensor script might use static analysis tools to report the current state:

```bash
#!/usr/bin/env node

# sensor.js – example placeholder for a static-analysis sensor

npx eslint . --format json | jq '.[] | {file:.filePath, errors:.messages|length}'

```

This script outputs structured data that the controller can consume to determine the next action.

### Controller Logic

The controller processes sensor output to select targets. A minimal TypeScript controller demonstrates deterministic selection:

```typescript
// controller.ts – deterministic controller example
import { readFileSync } from "fs";

type Finding = { file: string; errors: number };
const findings: Finding[] = JSON.parse(readFileSync("sensor-output.json", "utf8"));
const target = findings.find(f => f.errors > 0);
if (target) console.log(`Patch ${target.file}`); else console.log("No work");

```

This component bridges the gap between raw measurement and actionable work items.

### Actuator Configuration

The actuator executes the actual work. A GitHub Actions workflow excerpt shows how to invoke a coding agent as an actuator:

```yaml

# .github/workflows/control-loop.yml (excerpt)

jobs:
  act:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run Claude Code
        run: |
          claude-code apply --target ${{ steps.select.outputs.file }} \
            --prompt "@./references/prompt-template.md" \
            --output /tmp/pr-body.md

```

This pattern demonstrates how the control loop integrates with CI/CD infrastructure to create autonomous pull requests.

## Complete Reference File Structure

Beyond the primary taxonomy and skill definition, the `humanlayer/skills` repository contains several supporting reference files:

| File | Purpose | Link |
|------|---------|------|
| [`SKILL.md`](https://github.com/humanlayer/skills/blob/main/SKILL.md) | Skill definition, workflow overview, and mental model entry point. | [SKILL.md](https://github.com/humanlayer/skills/blob/main/plugins/design-control-loop/skills/design-control-loop/SKILL.md) |
| [`control-loop-taxonomy.md`](https://github.com/humanlayer/skills/blob/main/control-loop-taxonomy.md) | Full control-theory taxonomy, component definitions, design questions, and feedback diagram. | [control-loop-taxonomy.md](https://github.com/humanlayer/skills/blob/main/plugins/design-control-loop/skills/design-control-loop/references/control-loop-taxonomy.md) |
| [`example-control-loop.md`](https://github.com/humanlayer/skills/blob/main/example-control-loop.md) | Worked example of a complete production-ready loop. | [example-control-loop.md](https://github.com/humanlayer/skills/blob/main/plugins/design-control-loop/skills/design-control-loop/references/example-control-loop.md) |
| [`agent-runner-templates.md`](https://github.com/humanlayer/skills/blob/main/agent-runner-templates.md) | Templates for invoking various coding agents (Claude, Codex, GPT-4). | [agent-runner-templates.md](https://github.com/humanlayer/skills/blob/main/plugins/design-control-loop/skills/design-control-loop/references/agent-runner-templates.md) |
| [`workflow-template.yml`](https://github.com/humanlayer/skills/blob/main/workflow-template.yml) | Skeleton GitHub Actions workflow connecting all components. | [workflow-template.yml](https://github.com/humanlayer/skills/blob/main/plugins/design-control-loop/skills/design-control-loop/references/workflow-template.yml) |

## Summary

- The **control-theory mental model** for the design-control-loop skill is defined in [`SKILL.md`](https://github.com/humanlayer/skills/blob/main/SKILL.md) and detailed in [`control-loop-taxonomy.md`](https://github.com/humanlayer/skills/blob/main/control-loop-taxonomy.md) within the `humanlayer/skills` repository.
- The model consists of **five components**: set point, sensor, controller, actuator, and disturbance.
- **Design questions** in the taxonomy file (lines 66-76) ensure loops are observable, bounded, and reviewable.
- The **Mermaid diagram** in [`control-loop-taxonomy.md`](https://github.com/humanlayer/skills/blob/main/control-loop-taxonomy.md) provides a visual reference for signal flow.
- Supporting files include implementation templates for **sensors**, **controllers**, and **actuators** that transform theory into autonomous workflows.

## Frequently Asked Questions

### Where exactly is the control-theory mental model documented in the repository?

The documentation is split between two locations in the `humanlayer/skills` repository. The high-level introduction resides in [`plugins/design-control-loop/skills/design-control-loop/SKILL.md`](https://github.com/humanlayer/skills/blob/main/plugins/design-control-loop/skills/design-control-loop/SKILL.md), while the complete technical specification—including component definitions and design questions—is located at [`plugins/design-control-loop/skills/design-control-loop/references/control-loop-taxonomy.md`](https://github.com/humanlayer/skills/blob/main/plugins/design-control-loop/skills/design-control-loop/references/control-loop-taxonomy.md).

### What distinguishes the sensor from the actuator in this mental model?

The **sensor** is a read-only component that measures the current state of the system (such as test coverage or lint errors) and reports the gap between reality and the set point. The **actuator** is a write-capable agent that modifies the system state, typically by generating code changes and opening pull requests. The sensor observes; the actuator alters.

### Can this control loop work with AI agents other than Claude?

Yes. While the examples reference Claude Code, the [`agent-runner-templates.md`](https://github.com/humanlayer/skills/blob/main/agent-runner-templates.md) file provides adapter patterns for various coding agents including OpenAI Codex and GPT-4. The control-theory mental model is agent-agnostic; the actuator component can invoke any tool capable of applying patches to the repository.

### Why does the taxonomy include a "disturbance" component?

The **disturbance** component acknowledges that software repositories are not closed systems. External factors—such as human commits, dependency updates, or infrastructure changes—continuously push the codebase away from the desired set point. Explicitly modeling disturbances ensures the control loop accounts for environmental chaos rather than assuming static conditions.