/design-control-loop

name: design-control-loop
description: interview the user to design an agentic control loop (sensor, controller, actuator under disturbances) tailored to their codebase, then build it as locally-runnable components plus a scheduled coding-agent workflow

Design Control Loop

Use this skill when a user wants to drive some property of their codebase toward a target with small, low-risk, reviewable changes on a schedule — an **agentic control loop**.

Your job is to **interview the user, design the loop _with_ them, and then build it for them**. The design must be tailored to *their* codebase and the tooling they already use. There is no fixed toolset and no template to reproduce: propose options grounded in what you find in the repo, discuss trade-offs, agree on a design, then implement it.

The mental model

Borrow from control theory. The codebase is a dynamic system being changed continuously (by teammates, dependencies, and generated code — the **disturbances**). A control loop drives it toward a desired state instead of all at once:

• **Set point** — the desired end state for some property of the codebase.
• **Sensor** — measures the current state, producing the gap to the set point.
• **Controller** — decides the next small, low-risk change from that measurement.
• **Actuator** — a coding agent that applies the change and opens a PR.
• The result feeds back into the next run. A human stays *on* the loop to steer it.

Read `references/control-loop-taxonomy.md` and walk the user through these concepts before designing anything. For one fully worked example, see `references/example-control-loop.md` — treat it as an illustration, not a blueprint.

How to run this skill

• **Read the repo before you ask** (Phase A). Come to the interview with proposals, not a blank form.
• **Tailor every component.** The right sensor, controller, and actuator depend entirely on the user's problem and stack. The lists in the references are examples to spark discussion, never a checklist to push.
• **Make each component runnable locally and standalone before wiring it into CI** (Phase D). The workflow should only orchestrate pieces the user can already run by hand.
• **Capture the agreed design in writing** before building, so the user can correct it cheaply.

Outputs

Create or update these in the target repo, tailored to the agreed design:

• The **sensor** and **controller** as version-controlled commands/scripts the user can run locally.
• `.claude/skills/<skill-name>/SKILL.md` — the **actuator** skill capturing the agent's judgement (path may be `.agents/skills/...` per repo convention).
• The recurring **workflow** that runs the loop and opens a PR (GitHub Actions by default; whatever CI the repo uses).
• A **memory/feedback file** that carries standing feedback between runs.
• Optionally, a **dampener** (regression gate) that keeps the problem from getting worse while the loop improves it.

Workflow

Phase A — Understand the system

**Read the following references:** `references/example-control-loop.md`.

Read before asking setup questions:

• Existing CI: `.github/workflows/*.yml`, `.github/actions/**`, or the repo's non-GitHub CI config — runner, checkout, dependency install, cache, and PR conventions.
• Package manager files (`package.json`, `bun.lock`, `pnpm-lock.yaml`, `yarn.lock`, `package-lock.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, …).
• Existing validation scripts: typecheck, lint, test, quality, format, and package-scoped commands.
• Existing `.claude/skills` / `.agents/skills` and any existing agent loops (workflows, `agent-memory`, where glue scripts live) to mirror conventions instead of inventing new ones.
• The static-analysis, linting, codegen, and test tooling already in the repo — these are the most likely raw material for a sensor.
• Discover packages, services, and repo purpose at a high level.

Completion criterion: you can name the repo's package manager, install command, likely validation commands, CI platform, and any existing loop conventions. You understand the packages/services/applications it contains at a high level.

Phase B — Design the loop with the user

**Read the following references:** `references/control-loop-taxonomy.md`, `references/example-control-loop.md`, `references/agent-runner-templates.md`.

This is an interview. Work through each component below. Start by asking the user questions about the set point. Proposing options grounded in Phase A and surfacing trade-offs rather than mandating any choice. Record the decisions as you go.

1. **Set point.** What property are we driving, and to what target? Examples: an invariant ("no procedures use the old pattern"), a threshold ("test coverage ≥ X in these packages"), or a direction ("reduce occurrences each run"). Also pin the **scope**: which directories/packages the loop may change, and which it may only read.

2. **Sensor.** How will the loop measure the gap to the set point? Inspect the codebase and the user's existing tooling and propose the options that fit *their* stack — a static-analysis or lint tool, a structural/AST search, a test suite, a type checker, a telemetry or error query, a custom script, or even an agent-based check. Discuss the trade-offs that matter to them (stability, cost, repeatability, and whether the measurement can be silently disabled) instead of mandating any property. Aim for a measurement the controller can act on repeatably.

3. **Controller.** How will the loop choose the next increment from the measurement, sized to stay low-risk and reviewable? Design this *with* the user: how to prioritize targets, how big one increment is, and what "one reviewable unit of work" means here. A controller can be anything from fully deterministic (a script that selects the next target) to fully agentic (an agent that decides from natural-language criteria), and it may be **fused** with the sensor or the actuator. The controller is the part you will **tune