# 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 

…