Loop Builder

intent

turn a loosely described task into the smallest controllable workflow that can make progress, use evidence, stop safely, and preserve human judgment. use this skill when a user asks to automate a repeated task, repair ci through bounded iteration, reproduce a ui from screenshots, turn a workflow into a reusable agent or skill, or decide whether the right artifact is a prompt, checklist, human-in-the-loop flow, full loop package, specialized agent, or skill. the skill extracts required context, stops when decision evidence is missing, requires explicit workflow confirmation before generating executable artifacts, derives iteration limits, defines feedback and circuit breakers, and preserves human approval for risky actions.

inputs

• natural language task request (one sentence minimum, any length accepted)
• existing samples, screenshots, logs, or repository state (when available; missing samples block context gate)
• user's preferred language for output artifacts (defaults to english for reusable skill packages and english for clawhub metadata)
• environment authorization state (must be checked before any irreversible action like merge, publish, or deletion)
• task metadata: allowed/forbidden actions, time/cost budget, iteration budget, tools available, success signal definition
• reference materials accessed at runtime:
  • references/loop-patterns.md (loop pattern selection logic)
  • references/skill-generation-contract.md (specialized skill design)
  • references/agent-package.md (business-bound agent design)
  • references/templates.md (reusable artifact templates)
  • references/checklists.md (final validation checklists)
  • references/scenarios.md (task-type defaults)

no external api connections, databases, or oauth scopes required to run loop-builder itself. the skill designs workflows; it does not execute them.

procedure

1. parse the natural-language request

accept the user's one-sentence task request without requiring a form. extract what is already known:

inputs: user's raw request text

outputs: extracted fields: task goal, desired outcome, concrete inputs or samples, current failure or friction point, success signal, allowed and forbidden actions, tools and environment constraints, time/cost/iteration budget, whether any action is irreversible, desired reuse scope

do not invent missing details. flag them for the context gate.

2. run the context gate

classify each missing item:

• required now: changes workflow design, risk model, feedback mechanism, or iteration limit
• safe default: reversible assumption can be stated and applied
• runtime input: required when the workflow runs, not needed to design it
• optional: useful for optimization but not decision-critical

inputs: extracted fields from step 1, task type inferred from request

outputs: context sufficiency classification, list of missing required items (if any), list of safe defaults (if any), list of runtime inputs

reference the typical evidence table below by task type:

task type	decision evidence usually required
UI reproduction	target screenshots, current implementation or page, viewport constraints, allowed tech stack, visual acceptance signal or threshold
CI repair	failing job output or logs, repository state at failure point, safe validation commands, change boundary (files/tests/deployment scope)
content production	source material or brief, audience definition, target platform, quality gate or factuality check method
data review	dataset or schema, metric definition, comparison baseline or threshold
skill maintenance	current skill package code, requested behavior change, validation command, publishing or installation boundary
workflow automation	current manual steps (numbered), trigger condition, stopping condition, feedback or approval points

if required evidence is missing, output a blocking context card and stop at state WAITING_FOR_CONTEXT:

## Status
- current stage: WAITING_FOR_CONTEXT
- stop reason: required context or decision evidence is missing
- resume condition: provide the required items below

## required context
1. <question> - affects: <design decision>
2. <question> - affects: <design decision>

## safe defaults
- <item>: <default assumption and reversibility note>

## runtime inputs
- <item>: <why not required for design>

continue without real samples only when the user explicitly asks for a generic framework or accepts an uncalibrated design. mark complexity, risk, and iteration counts as general ranges in that case.

3. build the task card

when context is sufficient, synthesize the card for the user:

inputs: extraction from step 1, classification from step 2, inferred task type

outputs: task card (markdown table or structured summary)

field	content
original request	the user's exact wording
recognized scenario	task class (ui reproduction, ci repair, content production, data review, skill maintenance, workflow automation, custom)
goal	observable outcome (what success looks like)
inputs	available samples, data, or runtime inputs (separated)
success signal	evidence that distinguishes improvement from no change
allowed actions	reversible, in-scope changes the workflow can make
forbidden actions	unsafe or out-of-scope changes (irreversible, requires external approval, etc.)
human decisions	gates the system cannot cross without explicit approval
recommended artifact	smallest useful deliverable (prompt, checklist, human-in-the-loop, loop package, specialized agent, specialized skill)

do not make the user reconstruct information already present in the request.

4. decide whether a loop fits

inputs: task card from step 3, success signal definition, allowed actions, feedback latency

outputs: conclusion: exactly one of (full loop, human-in-the-loop, loop-ready structured workflow, not a loop, read-only scout first)

choose based on loop validity criteria:

a valid full loop requires all of:

• a repeatable action the workflow can execute
• an observable feedback signal independent of the action
• a permitted correction action in response to feedback
• progress that can be compared across iterations (not just yes/no)
• a stopping rule derived from the task (not arbitrary)
• a circuit breaker to prevent runaway cost or risk

if any item is missing, select a lighter artifact:

• full loop: objective feedback supports repeated correction without human judgment
• human-in-the-loop: feedback exists but key decisions require human judgment at gates
• loop-ready structured workflow: useful structure and phases, but no safe automatic correction cycle yet (requires manual review between iterations)
• not a loop: a one-time prompt or checklist is sufficient
• read-only scout first: design depends on repository, database, or environment evidence not yet inspected (recommend a read-only exploration step before committing to loop design)

5. select the smallest artifact

inputs: conclusion from step 4, task card, user's explicit artifact request (if any)

outputs: recommended artifact type and rationale

task shape	default artifact
one-time task with no objective feedback	one-time prompt
goal exists, quality is primarily human judgment	checklist
feedback exists, risky steps require approval	human-in-the-loop flow
feedback supports bounded correction	full loop package
repeated within one business context	specialized loop agent
reused across projects or teams	specialized skill

if the user requests a specific artifact and it is heavier (higher risk or complexity) than necessary, explain the mismatch and recommend the lighter option. do not block; offer the heavier option if the user accepts the trade-off.

6. select a loop pattern

if artifact is a loop or human-in-the-loop, choose one primary pattern:

inputs: task goal, feedback signal, allowed actions, risk model

outputs: primary loop pattern and rationale

choose one:

• retry loop: repeat a stable action after transient or localized failure (e.g., network timeout, rate limit, temporary unavailability). best when failure is not systemic.
• plan-execute-verify: decompose goal into substeps, execute each, verify against expected output, adjust plan if verification fails. best for complex or phased tasks.
• explore-narrow: collect candidates or options, compare evidence, narrow scope iteratively. best for search, optimization, or selection tasks.
• human-in-the-loop: execute, pause at human judgment gates or irreversible-action gates, resume after approval. best when feedback is subjective or action is risky.
• lifecycle loop: revisit a long-lived artifact (code, document, configuration) as external conditions change; periodic re-evaluation and adjustment. best for maintenance workflows.

explain why the primary pattern fits, why close alternatives do not, and what stops the loop (iteration limit, success condition, circuit breaker). if the distinction is subtle, refer to references/loop-patterns.md.

7. model specialized workflows

if artifact is a specialized agent or skill, answer these before proposing:

inputs: task goal, allowed actions, feedback mechanism, reuse scope

outputs: workflow model (prose or structured table)

answer:

• what professional role owns the real task?
• what does an expert analyze or decide before acting?
• which inputs are required, optional, or runtime-only?
• what are the phases, entry conditions, outputs, and checks?
• where do generator, evaluator, and human responsibilities differ?
• where does feedback come from (user, external system, internal validation)?
• which uncertainty must remain explicit in the artifact?
• which actions must never run automatically (e.g., deletion, billing change, production deployment)?
• when should the workflow continue, stop, roll back, or escalate to a human?

for a specialized skill, use references/skill-generation-contract.md. for a business-bound agent, use references/agent-package.md. summarize findings in the workflow model.

8. derive the iteration limit

do not use a scenario-specific magic number. derive the limit from task and resource constraints:

inputs: task complexity, feedback latency and cost, risk and reversibility of changes, size of allowed change per iteration, available time/compute budget, likelihood that another iteration can produce new evidence

outputs: iteration limit (integer or range), rationale, early-stop rules

decision rule: continue the next iteration only if all are true:

• next iteration is allowed by workflow permissions and budget
• next iteration can produce new evidence (not repeating failed attempt)
• expected value of new evidence exceeds cost and risk of iteration
• no circuit breaker is active (repeated failure class, missing permission, expanding scope, exhausted budget, timeout)

always add explicit early-stop conditions:

• no improvement in feedback signal over last N iterations
• same failure class repeated (e.g., same validation error three times)
• missing permission or budget exhaustion
• scope expanding beyond original goal
• latency or cost exceeding threshold

9. produce the logic confirmation card

before generating any executable prompt, checklist, loop package, agent package, or skill, output this confirmation card:

inputs: task card, loop fit decision, artifact selection, pattern choice, iteration limit, stop rules

outputs: structured confirmation card (markdown)

## Status
- current stage: WAITING_FOR_LOGIC_CONFIRMATION
- stop reason: workflow logic requires user approval
- resume condition: explicit approval or requested revisions

## workflow confirmation
- goal: <observable target>
- non-goals: <what the workflow will not do>
- inputs and boundaries: <material, budget, permissions, constraints>
- recommended artifact: <type and rationale>
- primary loop pattern: <pattern name and why>
- execution phases: <numbered sequence of phases>
- feedback signal: <what the evaluator measures>
- derived maximum iterations: <number or range and derivation>
- stopping rules: <success, no progress, cost, risk, time>
- human decision points: <gates requiring approval>
- forbidden actions: <what the workflow cannot do>
- final deliverables: <what the user receives after confirmation and execution>

stop and wait for explicit approval. a user request to "create the artifact" or "generate the workflow" counts as approval only if it clearly follows this card or explicitly accepts the proposed workflow.

10. generate the confirmed artifact

after explicit confirmation from the user, generate only the selected artifact type.

inputs: confirmed workflow model, selected artifact type, user's preferred language

outputs: executable artifact (prompt, checklist, loop package, agent package, or skill)

every generated artifact must contain:

• task goal and non-goals
• input contract (required, optional, runtime inputs)
• state location when state is needed (file, database, api, environment variable)
• actor and evaluator roles
• feedback signal definition
• allowed correction actions
• derived iteration limit and rationale
• stopping rules and circuit breakers
• human approval points (explicit pause gates)
• forbidden actions and boundaries
• evidence-based completion criteria
• recovery instructions (what to do if the workflow fails or is interrupted)

for reusable templates, consult references/templates.md. for final checks, consult references/checklists.md. for scenario-specific defaults, consult references/scenarios.md.

do not include the confirmation card or pre-generation analysis in the final artifact. the artifact should be standalone and executable.

11. require action-specific approval

workflow approval (step 9) does not authorize irreversible actions. pause again before executing or committing:

inputs: artifact, target location or system, nature of the action

outputs: action confirmation card (if action is irreversible or high-risk)

pause at state WAITING_FOR_ACTION_CONFIRMATION before:

• modifying a global skill installation or overwriting an existing reusable asset
• committing, pushing, merging, or opening a release to a repository
• publishing to an external platform or registry
• changing production data, permissions, billing, credentials, or api keys
• deleting material data or archive
• writing secrets, account data, private thresholds, or business records into a reusable artifact

name the exact action, target system, scope of impact, and recovery or rollback path. require explicit approval from the user before proceeding.

12. close with reuse judgment

after the main artifact is generated and executed (or approved for execution), always classify reuse potential:

inputs: artifact performance, observed stability, reuse scope, feedback quality, known exceptions

outputs: reuse classification and recommendation

classify as exactly one:

• recommend skillization: artifact is stable, reusable, well-scoped, and solves a recurring pattern; propose as a candidate for skill package creation
• observe one more run: artifact is promising but needs validation across one or more additional runs before skillization; collect specific evidence
• do not skillize yet: artifact is too specific, contains project secrets, depends on external state, or has unresolved exceptions; not ready for reuse

support the result with:

• observed stability (number of runs, error rate, manual adjustments needed)
• reuse scope (one project, multiple teams, cross-company, open source)
• feedback quality (automated, reliable, unambiguous vs. subjective, noisy, ambiguous)
• known exceptions or edge cases that constrain reuse
• suggested skill name and slug (if recommending skillization)
• next evidence to collect (if observing one more run)

never create, install, overwrite, or publish a skill from this recommendation alone. treat the recommendation as input to a separate skillization decision.

decision points

context gate (step 2)

if required evidence is missing (blocking the decision) then output context card at state WAITING_FOR_CONTEXT and stop. do not proceed to task card or loop-fit analysis.

else proceed to task card.

loop fit decision (step 4)

if all five loop criteria are met (repeatable action, observable feedback, permitted correction, comparable progress, stopping rule, circuit breaker) then consider full loop as the primary option.

else if feedback exists but decisions are subjective or actions are risky then recommend human-in-the-loop.

else if structure and phases are useful but no safe automatic correction cycle exists yet then recommend loop-ready structured workflow.

else if design depends on environmental evidence not yet inspected (e.g., repository state, database schema, api behavior) then recommend read-only scout first as a precursor step.

else recommend not a loop (one-time prompt or checklist).

artifact selection (step 5)

if user explicitly requests a specific artifact type and that type is heavier than the recommended option then offer the user's choice with a risk/complexity warning. do not block.

else recommend the smallest artifact that fits the task shape.

human-in-the-loop gates (step 9 and 11)

if the action is irreversible (deletion, merge, publish, credential change, billing) or the decision is subjective (design approval, content quality, risk acceptance) then require explicit human approval at a named gate before execution.

else if the action is reversible and the feedback is objective then no human gate required; the loop runs autonomously.

specialized agent or skill (step 7)

if reuse scope is across projects or teams and the workflow is stable and well-defined then model as a specialized skill using references/skill-generation-contract.md.

else if reuse scope is within one business context and workflow depends on project-specific state then model as a specialized loop agent using references/agent-package.md.

else embed the workflow in the loop package without separate skill or agent.

iteration limit derivation (step 8)

if feedback latency is high (hours or days per iteration) then use a tighter iteration limit (3-5) to avoid unbounded cost.

else if feedback latency is low (seconds or minutes) then iteration limit can be higher (10-20) if other constraints allow.

if each iteration is costly or risky then limit to 3-5 iterations and use strict early-stop rules.

if reversibility is uncertain or scope is expanding then stop immediately and escalate to human judgment rather than continuing.

output contract

before confirmation (steps 1-9)

output only these sections in order:

1. status block (current stage, stop reason, resume condition)
2. intake summary (extracted task, recognized scenario)
3. context sufficiency check (required items, safe defaults, runtime inputs)
4. task card (goal, inputs, success signal, allowed/forbidden actions, recommended artifact)
5. loop fit analysis (conclusion and reasoning)
6. artifact selection rationale
7. loop pattern selection (if applicable) and why alternatives do not fit
8. workflow confirmation card (goal, inputs, phases, feedback, iteration limit, stop rules, human gates, deliverables)

do not include executable prompt bodies, task commands, code, or file-writing instructions. do not output the artifact itself.