# Loop Discovery Reference Loop Discovery decides whether repeated or schedulable engineering work exists and which durable surface should own it. It is a routing gate, not the owner of session mining, Skill design, hook design, automation wiring, or report templates. Use it when `../agent-customize/routing.md`, session evidence, repo entropy, review feedback, CI results, user prompts, or reports suggest recurring work. Do not use it for one-off diagnosis or when the owner is already obvious. ## Chain Position - Start from `../agent-customize/routing.md` when the action form is still unclear. - Use `demand-source-analysis.md` first when the input is a raw demand source, session signal, report row, local entropy hint, or repeated-work suspicion that still needs an evidence pack. - Use `../session-evidence/sessions-diagnostics.md` to gather or inspect Qoder, Codex, Claude, Cursor, or Qwen session evidence. - Return here only to decide whether the evidence proves a loop and who owns it. - Use `../agent-customize/skill-discovery.md` only after the decision is `Create Skill` or `Extend Skill`. - Use `patterns/README.md` after a loop and owner are proven when the result needs a composable scheduled-inspection, event-response, goal-completion, proactive-discovery, or system-improvement operating pattern. - Use `loop-primitives.md` after a loop is proven but the supporting primitive mix is still unclear. - Use `loop-spec-card.md` after a loop is proven and the result needs a compact `WHEN -> SEE -> DO -> CHECK -> STOP -> LEAVE` spec or example. - Use `automation-readiness.md` after the decision is automation, `schedule-ready`, or a scheduled/background follow-up. - Use `loop-state-ledger.md` when the loop spans turns, runs, worktrees, approvals, external systems, or repeated evaluations. - Use `../agent-customize/agent-hooks.md`, commands, scripts, custom agents, MCP, rules, or automation only when this file selects that owner. ## Evidence Contract Bring bounded evidence, not broad transcript dumps: - repeated user intent, prompt cluster, report pattern, CI failure, review feedback, or scheduled/event trigger - configured and observed coverage: Skills, hooks, commands, rules, scripts, agents, MCP, automation, CI, specs, or plugins - stable input context: diffs, logs, sessions, reports, manifests, docs, screenshots, validation output, or detector output - local entropy signal when relevant: stale docs, dependency drift, long or hot files, complexity pressure, missing validation, guardrail drift, secrets, or sensitive boundaries Configured assets prove presence only. Opened session events, command output, reports, CI, scans, or external records prove observed behavior. Example families include Code Health, Security, Documentation, Test, Architecture, Review, and Modernization loops. These are examples, not owners; classify by trigger, input, procedure, verification, stop condition, and risk boundary. ## Runtime-Fit Check Before choosing an owner, decide what kind of loop is actually needed: - **Workflow loop**: the steps are mostly known. Prefer a command, script, hook, rule, Skill-backed playbook, or scheduled `/better-harness` follow-up over an autonomous agent. - **Agent loop**: the work needs flexible planning, tool use, handoffs, or recovery from changing evidence. Require turn limits, tool boundaries, observable traces, and a clear final-output condition. - **Evaluator-optimizer loop**: iterative improvement is useful only when there are explicit evaluation criteria and another pass can measurably improve the output. - **Scheduled or background loop**: a cadence or event trigger exists, inputs are non-interactive, side effects are reversible or gated, and the loop can report completion or `needs more evidence`. Continue to `automation-readiness.md`. - **Human-gated loop**: sensitive edits, shell commands, external writes, secrets, policy decisions, or broad repository changes require approval before the side effect happens. - **Skill-shaped loop**: the durable asset is procedural knowledge for an agent to load. Use `../agent-customize/skill-discovery.md`; do not treat the Skill itself as runtime state, approval, tracing, or scheduling infrastructure. The operating patterns in `patterns/README.md` are orthogonal to these runtime fits and to the owner route. For example, goal completion can be a workflow or agent loop, proactive discovery can start from a schedule or event, and system improvement is usually an evaluator-optimizer loop around an inner loop. Do not replace runtime-fit or owner selection with a pattern name. Do not promote an autonomous agent when a deterministic workflow, static rule, or human review checklist gives tighter control. ## Decision Gate Recommend a durable loop only when most answers are concrete: 1. **Repeated intent**: at least two similar asks, or one costly/high-risk task likely to recur. 2. **Existing coverage**: visible proof that current Skills, hooks, scripts, rules, commands, agents, MCP, automation, CI, or docs do not already cover the work. 3. **Stable input**: the loop can start from repeatable evidence or events. 4. **Repeatable procedure**: steps are reusable, not a fresh investigation each time. 5. **Verification**: success has a check, report, patch, review result, command, or explicit `needs more evidence` boundary. 6. **Stop condition**: the loop can end on a state, score, count, result, or human decision. 7. **Safety boundary**: permissions, secrets, external actions, and broad changes have a human gate where needed. 8. **State contract**: paused or multi-run work has a replayable input, checkpoint, session, artifact, or history pointer; purely stateless loops say why state is unnecessary. 9. **Observability contract**: logs, traces, spans, reports, run directories, or review artifacts show what happened, which tools ran, what changed, and why the loop stopped. 10. **Evaluation contract**: automated checks, LLM/human review, regression fixtures, or comparison criteria are named before iterative refinement is recommended. If these are missing, return `Needs more evidence`; do not promote a loop from file age, line count, churn, cache paths, titles, or counts alone. ## Schedule-Ready Outcome Use `schedule-ready` only when Loop Discovery has a stable target, cadence or event trigger, repeatable `/better-harness` input, validation command, safety boundary, and stop condition. Final harness reports should render this as a row-scoped `Schedule follow-up` handoff using `/schedule /better-harness`, not a standalone global call to action. A generic recommendation to run `/schedule /better-harness` to improve overall engineering quality is not schedule-ready. The handoff must name the concrete loop/finding, selected owner, target path or artifact, cadence or trigger, evidence, validation, risk/safety boundary, acceptance check, and stop condition. If recurring schedules are unsupported or unclear, ask `/schedule` for the next one-time follow-up and state that recurring setup needs user confirmation. Do not use `schedule-ready` for `Needs more evidence`, sensitive human-judgment loops, one-off diagnosis, or candidates without validation and stop conditions. ## Owner Route - **Covered**: existing surface already owns the loop; cite it. - **Skill**: reusable how-to workflow with judgment, steps, outputs, failure modes, and validation. Hand off to `../agent-customize/skill-discovery.md`. - **Automation**: stable trigger, non-interactive inputs, verification, stop condition, reversible or gated action. - **Hook / Rule**: deterministic lifecycle check, warning, block, logging, or policy enforcement. - **Script**: deterministic extraction, validation, transformation, or formatting that supports another owner. - **Command / Prompt**: short fixed manual entrypoint; not broad workflow ownership. - **Custom Agent**: repeatable specialist role needs isolated context, independent judgment, or parallel review. - **MCP-backed Loop**: external data or actions are required; MCP is access, not the whole workflow. - **Skip**: one-off, too broad, too sensitive, speculative, or already handled. - **Needs more evidence**: name the missing proof. Prefer the smallest durable owner. Do not default to Skill or automation. ## Output Keep the answer short: - candidate loop and evidence refs - decision: covered, create/extend Skill, automation, hook/rule, script, command, custom agent, MCP-backed loop, skip, or needs more evidence - proposed owner and handoff file - runtime fit: workflow, agent, evaluator-optimizer, scheduled/background, human-gated, Skill-shaped, or not a loop - state, observability, evaluation, side-effect, stop-condition, and human-gate contract - primitive addendum from `loop-primitives.md` when supporting primitives are needed - selected operating pattern or composition from `patterns/README.md` when the result needs scenario-level orchestration - compact loop card from `loop-spec-card.md` when the output needs a reusable example or report-ready spec - missing evidence, verification, stop condition, and human gate - for schedule-ready outcomes, the exact `Schedule follow-up` prompt slots: target, finding, evidence, cadence/trigger, validation, risk/safety, acceptance check, and stop condition Do not create or wire automation from a Loop Spec until the playbook, verification path, permissions, stop conditions, and human gate are clear. ## Quality Bar - Cite concrete files, commands, sessions, reports, dates, scan output, CI, or external records opened during the task. - Separate local entropy from confirmed defects or required automation. - Separate configured coverage from observed execution. - Treat observed Skill use as coverage unless repeated setup, repair, validation, or schedule handoff is still manual. - Keep recommendations scoped to the selected owner and handoff file. - Prefer explicit workflow orchestration over open-ended autonomy when the route is predictable. - Treat traceability, evaluation, and approval as part of the loop contract, not optional production polish.