# What is the Purpose of /iterate PR Comments in Loop Skills?

> Understand the purpose of /iterate PR comments in Loop Skills. This control signal directs feedback to the correct workflow instance, allowing code refinement without new PRs.

- Repository: [HumanLayer/skills](https://github.com/humanlayer/skills)
- Tags: internals
- Published: 2026-09-12

---

**The `/iterate` comment serves as a control signal that routes maintainer feedback to the specific workflow instance that created a pull request, enabling continuous refinement of code without spawning new PRs.**

The `humanlayer/skills` repository implements **loop skills**—agentic coding workflows that generate pull requests and iteratively improve them based on human direction. These workflows, documented in [`plugins/build-iterated-agentic-loop/skills/build-iterated-agentic-loop/SKILL.md`](https://github.com/humanlayer/skills/blob/main/plugins/build-iterated-agentic-loop/skills/build-iterated-agentic-loop/SKILL.md) and [`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), rely on `/iterate` PR comments to transform static pull requests into living conversation threads. When a maintainer posts a comment beginning with `/iterate`, the system triggers a new execution cycle that gathers the full PR context, invokes the LLM agent, and commits updates directly to the existing branch.

## Control Signal Routing Through Hidden Markers

When a loop skill such as **design-control-loop** or **build-iterated-agentic-loop** creates a PR, it embeds a hidden marker in the PR body that ties the artifact to its originating workflow instance. This marker enables the system to route subsequent comments to the correct workflow even when multiple agents operate simultaneously in the same repository.

### The Hidden Marker System

According to the `humanlayer/skills` source code, the PR body contains an HTML comment marker with the exact format:

```

<!-- codelayer-agent:workflow=<id>;memory=<path>;… -->

```

This hidden marker persists in the PR description and contains the workflow identifier and path to the persistent memory file. The marker ensures that when a maintainer subsequently comments on the PR, the system can extract the workflow ID and memory location necessary to reconstruct the agent's context.

### Workflow Identification Logic

In [`plugins/design-control-loop/skills/design-control-loop/references/workflow-template.yml`](https://github.com/humanlayer/skills/blob/main/plugins/design-control-loop/skills/design-control-loop/references/workflow-template.yml), the workflow filters incoming `issue_comment` events using a strict prefix check:

```yaml
startsWith(github.event.comment.body, '/iterate')

```

Only comments beginning with `/iterate` trigger the iteration steps. This prefix requirement prevents accidental triggering while allowing maintainers to write normal comments without interrupting the agent workflow. Upon detecting the command, the workflow extracts the hidden marker from the PR body before proceeding to the checkout step.

## The Iteration Pipeline: Building Context and Applying Changes

Once the system identifies an `/iterate` command, it executes a structured pipeline defined in [`agent-iteration.ts`](https://github.com/humanlayer/skills/blob/main/agent-iteration.ts). This script operates in two distinct modes: **footer** generation when creating the PR, and **prompt** generation when processing feedback.

### Generating the Footer with agent-iteration.ts

When initially creating a PR, the workflow invokes the script with the `--command footer` flag:

```bash
bun .github/scripts/agent-iteration.ts \
  --command footer \
  --workflow $WORKFLOW_ID \
  --memory .github/agent-memory.json

```

As implemented in [`plugins/design-control-loop/skills/design-control-loop/references/agent-iteration.ts`](https://github.com/humanlayer/skills/blob/main/plugins/design-control-loop/skills/design-control-loop/references/agent-iteration.ts) (lines 45-53), the footer mode appends both visible instructions (the `/iterate <feedback>` hint) and the hidden marker to the PR body. This ensures future maintainers understand how to interact with the agent while preserving the technical metadata required for workflow routing.

### Building the Full Context Prompt

When processing an actual `/iterate` comment, the workflow switches to `--command prompt` mode:

```bash
bun .github/scripts/agent-iteration.ts \
  --command prompt \
  --workflow $WORKFLOW_ID \
  --memory .github/agent-memory.json \
  --repo humanlayer/skills \
  --pr-number 42 \
  --comment-body "/iterate Fix the naming ..."

```

In this mode, the script gathers the PR title, body, complete comment threads, the current diff, and the persistent memory file. As defined in lines 65-71 of [`agent-iteration.ts`](https://github.com/humanlayer/skills/blob/main/agent-iteration.ts), it constructs a comprehensive prompt that provides the LLM agent with full historical context, enabling it to generate changes that account for previous iterations and accumulated feedback.

### Applying Changes and Persistent Memory

After the LLM generates suggested modifications, the agent applies these changes to the PR branch, commits them, and pushes the updates. Simultaneously, the system distills any durable guidance—such as coding standards or architectural decisions—into the memory file specified in the hidden marker. This file, typically located at [`.github/agent-memory.json`](https://github.com/humanlayer/skills/blob/main/.github/agent-memory.json), remains human-readable and ensures the agent retains critical context across workflow runs without ballooning the prompt size with redundant historical data.

## Practical Implementation Examples

The complete interaction follows a three-phase pattern. First, when creating the PR, the workflow generates the footer:

```bash

# Add the iteration footer when the workflow creates the PR

bun .github/scripts/agent-iteration.ts \
  --command footer \
  --workflow $WORKFLOW_ID \
  --memory .github/agent-memory.json

# → prints the markdown snippet that the workflow appends to the PR body

```

Second, the maintainer triggers refinement by commenting directly on the PR:

```bash

# Trigger an iteration from a maintainer comment

#    (write this as a comment on the PR)

/iterate Fix the naming of the utility function and add a unit test

```

Third, the workflow detects the comment and executes the iteration cycle:

```bash

# The same workflow, when it receives the comment, runs:

bun .github/scripts/agent-iteration.ts \
  --command prompt \
  --workflow $WORKFLOW_ID \
  --memory .github/agent-memory.json \
  --repo humanlayer/skills \
  --pr-number 42 \
  --comment-body "/iterate Fix the naming ..."

# → prints a full prompt that is sent to the LLM agent; the agent then

#   commits changes, updates the memory file, and posts a summary comment.

```

## Summary

- **The `/iterate` comment** serves as a specialized control signal that converts standard PR comments into agentic workflow triggers, filtered by the `startsWith` check in the GitHub Actions workflow template.
- **Hidden HTML markers** embedded in PR bodies store workflow IDs and memory file paths, enabling precise routing of comments to their originating workflow instances without cross-contamination.
- **The [`agent-iteration.ts`](https://github.com/humanlayer/skills/blob/main/agent-iteration.ts) script** operates in dual modes: **footer** mode initializes PRs with interaction instructions and metadata (lines 45-53), while **prompt** mode constructs comprehensive LLM prompts from PR diffs, comments, and persistent memory (lines 65-71).
- **Persistent memory files** store distilled knowledge across iterations, allowing the agent to maintain context and improve continuously while keeping individual prompts concise and relevant.

## Frequently Asked Questions

### How does the system prevent accidental triggering of agent iterations?

The workflow explicitly checks that the comment body begins with the `/iterate` string using the condition `startsWith(github.event.comment.body, '/iterate')` in [`workflow-template.yml`](https://github.com/humanlayer/skills/blob/main/workflow-template.yml). This prefix requirement ensures that only intentionally formatted commands trigger the agent, while regular discussion comments on the PR are ignored by the automation.

### What information is included in the hidden PR marker?

The hidden marker follows the format `<!-- codelayer-agent:workflow=<id>;memory=<path>;… -->` and contains the unique workflow identifier, the path to the agent memory file (typically [`.github/agent-memory.json`](https://github.com/humanlayer/skills/blob/main/.github/agent-memory.json)), and additional metadata required to reconstruct the agent's context. This marker resides in the PR body as an HTML comment, remaining invisible to human readers while providing machine-readable routing data.

### Can multiple loop skills operate on the same repository simultaneously?

Yes, because each workflow instance writes its own unique hidden marker containing a distinct workflow ID. When an `/iterate` comment arrives, the system extracts the marker and routes the signal only to the specific workflow that created that particular PR, allowing multiple **design-control-loop** and **build-iterated-agentic-loop** instances to coexist without interference.

### What happens to feedback across multiple /iterate cycles?

Durable feedback gets distilled into the persistent memory file specified in the hidden marker. According to the implementation in [`agent-iteration.ts`](https://github.com/humanlayer/skills/blob/main/agent-iteration.ts), the system updates this memory file after each successful iteration, ensuring that guidance such as naming conventions, architectural decisions, and debugging fixes accumulates across runs. This approach maintains a concise, human-readable knowledge base that the agent references in subsequent iterations without requiring full replay of comment history.