Skip to content

Practical patterns, starters & CLI tools for loop engineering with AI coding agents. Design systems that prompt and orchestrate agents (inspired by Addy Osmani and Boris Cherny). Includes loop-audit, loop-init, loop-cost.

Initial commit: loop-engineering reference repo

Cobus Greyling789233c61ae6
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..aed88eb
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,41 @@
+# Dependencies
+node_modules/
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Environment
+.env
+.env.local
+.venv/
+
+# IDE / editor
+.idea/
+.vscode/
+*.swp
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs & temp
+*.log
+tmp/
+temp/
+
+# Build / dist
+dist/
+build/
+*.egg-info/
+
+# State files that should not be committed in examples
+STATE.md
+state.json
+*.state
+
+# Grok / agent specific
+.grok/
+.claude/
+.codex/
+*.session
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..771efae
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cobus Greyling and contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..ae1c1a9
--- /dev/null
+++ b/README.md
@@ -0,0 +1,150 @@
+# Loop Engineering
+
+**Loop engineering is replacing yourself as the person who prompts the agent. You design the system that does it instead.**
+
+A loop is a recursive goal: you define a purpose and the AI iterates (often with sub-agents, verification, and external state) until the goal is complete or the loop decides to hand off to you.
+
+This is the emerging practice of moving from "I prompt → agent responds → I prompt again" to "I design the autonomous system that discovers work, assigns it, verifies results, and drives progress."
+
+## Why This Matters
+
+For years the primary interface was a good prompt plus manual back-and-forth. That model is shifting.
+
+Peter Steinberger:
+> “You shouldn’t be prompting coding agents anymore. You should be designing loops that prompt your agents.”
+
+Boris Cherny (Head of Claude Code at Anthropic):
+> “I don’t prompt Claude anymore. I have loops running that prompt Claude and figuring out what to do. My job is to write loops.”
+
+The leverage point has moved from crafting individual prompts to designing the control systems that orchestrate agents over time.
+
+## The Five Building Blocks + Memory
+
+A robust loop needs these five capabilities, plus persistent external memory (because the model forgets between runs — the repo does not).
+
+| Primitive | Job in the Loop | Why It Matters |
+|--------------------|------------------------------------------|----------------|
+| **Automations / Scheduling** | Discovery + triage on a cadence | Turns one-off runs into recurring systems (`/loop`, scheduled tasks, GitHub Actions, hooks) |
+| **Worktrees** | Safe parallel execution | Multiple agents working on the same repo without file collisions |
+| **Skills** | Persistent project knowledge | `SKILL.md` (or equivalent) so the agent doesn't re-derive conventions, constraints, and "why we do it this way" every run |
+| **Plugins & Connectors** | Reach into your real tools | MCP-based connectors to Linear, Slack, GitHub, databases, APIs so the loop can *act* (open PRs, update tickets, notify) |
+| **Sub-agents** | Maker / checker split | One agent (or team) explores/implements; a different one verifies. Critical when the loop runs while you're not watching |
+
+**+ Memory / State**
+A durable spine outside any single conversation: a markdown file, Linear board, JSON state, or dedicated project tracker. The loop reads what was tried, what passed, what is still open.
+
+Both Claude Code and OpenAI Codex have converged on versions of all five primitives. The shape of a good loop is becoming somewhat tool-agnostic.
+
+## What One Loop Actually Looks Like
+
+A typical daily loop (inspired by patterns described by Addy Osmani and practiced by teams at Anthropic/OpenAI):
+
+1. An automation runs on a schedule (e.g. every morning or every 30m).
+2. It calls a **triage skill** that reads recent CI failures, open issues, commits, Slack threads, etc.
+3. Findings are written to external state (markdown or Linear).
+4. For worthwhile items:
+ - Open an isolated **worktree**.
+ - Spawn a sub-agent (implementer) to draft a fix.
+ - Spawn a second sub-agent (reviewer/verifier) against project skills + tests.
+5. Connectors open/update the PR and ticket.
+6. Anything the loop cannot confidently handle lands in a human triage inbox.
+7. The state file acts as the memory spine for the next run.
+
+You designed the loop once. You are not the one prompting every micro-step.
+
+## Loop Engineering with Grok Build TUI
+
+The Grok TUI already ships excellent native support for these primitives (this is one reason the concept feels natural here).
+
+**Core tools:**
+- `/loop [interval] <prompt>` — the primary user-facing scheduling command (e.g. `/loop 5m Check CI and report new failures`).
+- Lower-level scheduler: `scheduler_create`, `scheduler_list`, `scheduler_delete` (supports `recurring`, `durable`, `fireImmediately`).
+- `monitor` tool — real-time event streaming (the streaming counterpart to discrete `/loop` checks).
+- Background tasks + `Ctrl+G` demote + queue pane (`Ctrl+;`).
+- Subagents with `isolation: "worktree"` for safe parallelism.
+- Skills (`SKILL.md` + scripts/references).
+- MCP servers for connectors.
+- Persistent todos + state files for memory.
+
+**Example Grok-native loops people run today:**
+- PR babysitting: `/loop 5m /pr-babysit check`
+- Continuous test / deploy monitoring
+- Daily triage + self-scheduled follow-ups
+- Post-merge sweepers and stale PR pruners
+
+See the `examples/grok/` directory and the background-tasks documentation in the Grok user guide for patterns.
+
+## Getting Started
+
+1. Identify a recurring pain (CI noise, PR shepherding, daily triage, post-incident fixes, etc.).
+2. Turn the workflow into a **skill** first (write down the intent once).
+3. Wrap it with `/loop` or `scheduler_create`.
+4. Add verification (sub-agent reviewer or explicit "done" condition checked by a separate model).
+5. Add state (a `STATE.md` or Linear integration via MCP).
+6. Add connectors so the loop can act, not just suggest.
+7. Run it. Watch it. Refine the loop design, not the individual prompts.
+
+Start small. One reliable loop that saves you 15 minutes a day is more valuable than an ambitious one that burns tokens and trust.
+
+## Patterns
+
+See the `patterns/` directory for reusable, documented loop patterns:
+
+- `pr-babysitter` — shepherd PRs through review, rebase, CI, and merge
+- `daily-triage` — morning scan of issues, commits, CI, and Slack
+- `ci-sweeper` — react to failing checks and propose minimal fixes
+- `post-merge-cleanup` — tech debt, deprecations, and follow-ups after merges
+
+Each pattern includes:
+- The scheduling primitive
+- Required skills
+- State shape
+- Verification strategy
+- Failure modes and human hand-off
+
+## Caveats (Important)
+
+Loop engineering amplifies judgment — both good and bad.
+
+- **Token costs** can explode with sub-agents and long-running loops. Monitor usage.
+- **Verification is still on you.** "Done" is a claim until a human confirms the code works and is understandable. Unattended loops make unattended mistakes.
+- **Comprehension debt** grows faster. The more code ships without deep human review, the larger the gap between what exists and what you actually grasp.
+- **Cognitive surrender** is the comfortable trap. Designing the loop is the cure when done with judgment; it is the accelerant when used to avoid thinking.
+- Two people can run the exact same loop and get opposite results. The loop doesn't know the difference. You do.
+
+Addy Osmani:
+> “Build the loop. But build it like someone who intends to stay the engineer, not just the person who presses go.”
+
+Prompting agents directly is still effective. The goal is the right balance.
+
+## Philosophy
+
+Loop engineering is not about removing the human. It is about moving the human to the highest-leverage position: designing the system, encoding good judgment into skills and verifiers, and deciding what should remain under human control.
+
+The best loops are boring, reliable, and transparent. They surface interesting work to you instead of hiding it.
+
+## Sources & Further Reading
+
+- Addy Osmani – [Loop Engineering](https://addyosmani.com/blog/loop-engineering/) (primary synthesis this repo draws from)
+- The X thread: https://x.com/addyosmani/status/2064127981161959567
+- Boris Cherny (Anthropic, Head of Claude Code) statements on loops, `/loop`, `/goal`, and "I don't prompt Claude anymore"
+- Related concepts: Agent Harness Engineering and the Factory Model (Osmani)
+
+## Contributing
+
+This repo aims to be the practical, living reference for loop engineering.
+
+- Share real patterns that have run in production (even small ones).
+- Improve the primitives table with new tool capabilities.
+- Add tool-specific guides (Grok, Claude Code, Codex, custom harnesses).
+- Document failure modes and how good loop design mitigates them.
+
+Pull requests and issues that treat this as engineering (not hype) are very welcome.
+
+## License
+
+MIT
+
+---
+
+*This repository was created as a concrete representation of the loop engineering concept discussed in the Addy Osmani thread and related Anthropic commentary. It is intentionally practical and tool-aware.*
diff --git a/docs/primitives.md b/docs/primitives.md
new file mode 100644
index 0000000..0a8105e
--- /dev/null
+++ b/docs/primitives.md
@@ -0,0 +1,97 @@
+# The Five Primitives + Memory
+
+This document expands on the core building blocks of loop engineering.
+
+## 1. Automations / Scheduling
+
+The heartbeat. Without scheduling, you just have a one-off agent run.
+
+**Common realizations**:
+- `/loop` (Grok)
+- Scheduled tasks / cron in Claude Code
+- GitHub Actions + repository dispatch
+- `/goal` (run until a verifiable condition is true)
+- Custom harness schedulers
+
+Key properties: interval, fire-immediately, recurring vs one-shot, durable (survives restarts).
+
+## 2. Worktrees
+
+Parallelism without chaos.
+
+When two agents edit the same files at the same time you get merge hell. Git worktrees (or equivalent isolated checkouts) give each agent its own working directory that shares history but not the working tree.
+
+In Grok: pass `isolation: "worktree"` when spawning subagents, or use `--worktree` / dedicated sessions.
+
+Cleanup is important — loops should delete the worktree when the task is done or handed off.
+
+## 3. Skills
+
+The persistent memory of *intent*.
+
+A skill (usually a `SKILL.md` + optional scripts/references) encodes:
+- Project conventions
+- "We don't do it this way because of X incident"
+- Build/test/lint commands
+- Review standards
+- Domain knowledge
+
+Without skills the loop re-derives everything from scratch on every run (intent debt).
+
+Skills are also the unit of reuse. Package them as plugins to share across repos or teams.
+
+## 4. Plugins & Connectors (MCP)
+
+A loop that can only read the filesystem is limited.
+
+Connectors let the loop:
+- Read and update Linear / Jira tickets
+- Post to Slack / Discord
+- Query databases or internal APIs
+- Create branches and PRs on GitHub
+- Trigger deploys or runbooks
+
+MCP (Model Context Protocol) has become the common substrate, so connectors written for one tool often work in another.
+
+## 5. Sub-agents (Maker / Checker Split)
+
+The single most important structural pattern for reliable loops.
+
+The agent that wrote the code is a terrible judge of its own work. A second agent (sometimes on a stronger model, always with different instructions) performs verification.
+
+Common splits:
+- Explorer → Implementer → Verifier
+- Implementer → Security reviewer
+- Implementer → Test writer + runner
+
+In unattended loops, the verifier is what lets you (the human) walk away with some confidence.
+
+`/goal` in several tools uses a fresh model to decide whether the stopping condition has been met — another application of the maker/checker idea.
+
+## + Memory / State
+
+The model has no long-term memory across separate turns or sessions.
+
+The loop must read from and write to something durable:
+- A `STATE.md` or `LOOP-STATE.json` in the repo
+- A dedicated section of a Linear board or GitHub Project
+- A small database row
+
+Good state answers:
+- What are we currently working on?
+- What did we try last time and what was the outcome?
+- What is waiting for a human?
+
+The state file is often the single most important artifact the loop produces.
+
+## How the Pieces Fit Together
+
+A minimal viable loop usually starts with:
+Scheduling + one skill (triage) + state file.
+
+You then add:
+- Worktree isolation when you start making changes
+- Sub-agent verification when the loop is acting autonomously
+- Connectors when you want it to drive tickets and PRs instead of just suggesting
+
+The best loops are the ones where each new primitive is added only when the previous version has proven its value (and its failure modes).
diff --git a/examples/grok/daily-triage.md b/examples/grok/daily-triage.md
new file mode 100644
index 0000000..49c9e54
--- /dev/null
+++ b/examples/grok/daily-triage.md
@@ -0,0 +1,59 @@
+# Daily Triage Loop (Grok Example)
+
+This is a practical, copy-pasteable example of a morning triage loop using the Grok Build TUI.
+
+## The Command
+
+```bash
+/loop 1d Run the loop-triage skill on the current project. Append high-priority items to STATE.md. For any small, self-contained bugfix or CI failure, open an isolated worktree, draft a minimal fix using the minimal-fix skill, and have a reviewer sub-agent verify it against project skills and tests. Update the PR or ticket via connectors if possible. Anything ambiguous or high-risk should be clearly flagged for human review in STATE.md.
+```
+
+You can also run it on a faster cadence during active periods:
+```bash
+/loop 2h Run triage and act on obvious small wins only.
+```
+
+## Supporting Files You Should Have
+
+- `STATE.md` in the repo root (committed or in a shared location)
+- The `loop-triage` skill installed (copy from `templates/SKILL.md.loop-triage`)
+- A `minimal-fix` skill (or equivalent instructions)
+- Reviewer persona / sub-agent definition
+- MCP connectors configured for your issue tracker and/or GitHub (optional but powerful)
+
+## Typical STATE.md Shape
+
+```markdown
+# Loop State — Project X
+
+Last run: 2026-06-09 08:15 UTC
+
+## High Priority (loop is acting or waiting on human)
+- [ ] #1241 — flaky test in auth flow (CI red on main)
+ Loop action: Opened worktree `fix/flaky-auth-test-1241`. Minimal fix proposed. Reviewer sub-agent approved. Waiting for human to review PR.
+- [ ] Linear ticket ENG-987 — "Add rate limiting to new endpoint"
+ Loop action: None yet (needs design discussion). Flagged for human.
+
+## Watch List
+- PR #1238 has been open 4 days with no activity.
+
+## Recent Noise (ignored this run)
+- Dependabot PRs (handled by separate automation)
+- 3 low-severity lint warnings on experimental branch
+```
+
+## Tips for This Loop in Grok
+
+- Use `isolation: "worktree"` on any sub-agent that will edit code.
+- Make the reviewer sub-agent use a stronger model or higher reasoning effort.
+- After the loop runs, read `STATE.md` yourself the first few times so you can refine the triage skill and the hand-off criteria.
+- Add a `durable: true` scheduler entry if you want the loop to survive session restarts (advanced).
+
+## Evolution Path
+
+1. Start with pure reporting (just append to STATE.md).
+2. Add "act on obvious small wins".
+3. Add connectors that actually open PRs and comment on tickets.
+4. Add self-cleanup logic (the loop deletes its own scheduler entry when there is nothing left to watch).
+
+This pattern is deliberately boring. Boring loops that run reliably are the ones that actually save time.
diff --git a/patterns/README.md b/patterns/README.md
new file mode 100644
index 0000000..bfefe3f
--- /dev/null
+++ b/patterns/README.md
@@ -0,0 +1,26 @@
+# Loop Patterns
+
+This directory contains documented, reusable loop patterns that have been (or can be) run in real environments.
+
+Each pattern answers:
+- What problem it solves
+- Recommended scheduling
+- Required skills / state shape
+- Verification approach
+- Human hand-off strategy
+- Tool-specific notes (Grok, Claude Code, etc.)
+
+## Current Patterns
+
+- [pr-babysitter.md](./pr-babysitter.md) — Shepherd PRs from draft through review, CI, rebase, and merge.
+- (More coming — contributions welcome)
+
+## How to Use a Pattern
+
+1. Copy the relevant skill(s) into your project (or publish as a plugin).
+2. Set up the scheduling command (`/loop`, `scheduler_create`, GitHub Action, etc.).
+3. Create the initial state file or Linear board view.
+4. Start the loop.
+5. Iterate on the loop definition based on what actually happens.
+
+Good loops are boring and reliable. Start with one that runs every few hours or daily before going to sub-minute cadences.
diff --git a/patterns/pr-babysitter.md b/patterns/pr-babysitter.md
new file mode 100644
index 0000000..6d987a6
--- /dev/null
+++ b/patterns/pr-babysitter.md
@@ -0,0 +1,92 @@
+# PR Babysitter Loop
+
+**Goal**: Reduce the human time spent herding pull requests through review, CI, rebase, and merge while keeping the human in the judgment seat.
+
+## Scheduling
+
+**Recommended**:
+- `/loop 5m /pr-babysit check` (Grok TUI)
+- Equivalent scheduled task or GitHub Action in other environments (every 5–15 minutes during working hours is common).
+
+Many teams run a faster "watcher" loop (2–5m) during active review periods and a slower sweeper overnight.
+
+## Required Skills
+
+- `pr-review-triage` — Understands your project's review norms, required checks, and what "ready to merge" means.
+- `minimal-fix` — Produces the smallest possible change that addresses a specific reviewer comment or CI failure.
+- `rebase-and-clean` — Safe rebase + conflict resolution patterns for your repo.
+
+## State
+
+Keep a small `pr-babysitter-state.md` (or a Linear board / GitHub project view) with:
+
+- Watched PRs + current status
+- Last action taken + outcome
+- Human decisions that overrode the loop
+
+Example state entry:
+```markdown
+- #1234 (feat/auth-refresh)
+ Status: Changes requested by @reviewer
+ Last action: Loop proposed minimal diff for comment X
+ Human decision: Approved the diff, asked for one more test
+```
+
+## How the Loop Runs (Typical Cycle)
+
+1. Discover open PRs authored by the team (or all PRs the user cares about).
+2. For each PR:
+ - Run triage skill.
+ - If CI is red → spawn sub-agent with `minimal-fix` skill to address the failure.
+ - If review comments exist and are actionable → propose minimal patches.
+ - If ready (all checks green, approvals present, no blocking comments) → add "ready to merge" label or ping human.
+3. For PRs that have been idle too long → suggest close or hand-off.
+4. Write concise updates back to the PR and to state.
+5. Anything ambiguous or high-risk → surface to human with context.
+
+## Verification Strategy
+
+- Never let the implementer sub-agent mark its own work "done".
+- Use a separate reviewer sub-agent (or a stronger model on higher effort) that must explicitly confirm:
+ - The change addresses the comment/failure.
+ - No unrelated files were touched.
+ - Tests/lint still pass in the worktree.
+- The loop only proposes; a human (or an explicit "auto-merge" allowlist for very safe cases) actually merges.
+
+## Human Handoff Points
+
+- High-risk refactors
+- Changes touching security, payments, auth, or core infrastructure
+- When the loop has proposed > N fixes on the same PR without progress
+- When the state file shows the same PR surfacing for several days
+
+## Tool-Specific Notes
+
+**Grok Build TUI**:
+- The `pr-babysit` skill (if installed) is designed exactly for this.
+- Run with `/loop 5m /pr-babysit check`.
+- Use worktree isolation for any fix attempts.
+- The skill can call `scheduler_delete` on itself when the watchlist is empty.
+
+**Claude Code**:
+- Boris Cherny has publicly described running very similar `/loop 5m /babysit` flows.
+- Combine with `/goal` for "keep working on this PR until CI is green and no blocking comments remain".
+
+**General**:
+- Expose the state file in the repo or a shared doc so the whole team can see what the loop is doing.
+- Make the loop's comments on PRs clearly signed (e.g. "🤖 Loop Engineering — PR Babysitter").
+
+## Failure Modes & Mitigations
+
+- **Loop proposes bad fixes** → Strong reviewer sub-agent + human review gate for anything beyond trivial.
+- **Infinite rebase loops** → Limit number of automated rebase attempts per PR.
+- **Stale state** → The loop should prune closed/merged PRs on every run.
+- **Notification fatigue** → Use selective notifications (only when human action is truly required).
+
+## Success Metrics
+
+- Average time from "ready for review" to merge (for PRs the loop touched).
+- Number of human comments that were purely "LGTM, loop handled the rest".
+- Reduction in "can you rebase?" or "CI is red" pings in Slack/Linear.
+
+Start with one team or one repo. Measure for a week. Then expand.
diff --git a/resources/sources.md b/resources/sources.md
new file mode 100644
index 0000000..3d7b5c8
--- /dev/null
+++ b/resources/sources.md
@@ -0,0 +1,43 @@
+# Sources & Attribution
+
+This repository exists because of public discussion and practice by experienced practitioners. Primary sources:
+
+## Core Definition & Framework
+
+- **Addy Osmani** — [Loop Engineering](https://addyosmani.com/blog/loop-engineering/) (June 2026)
+ The most complete written synthesis of the concept, including the five primitives + memory table and the concrete daily loop example.
+
+- The originating X thread: https://x.com/addyosmani/status/2064127981161959567
+
+## Anthropic / Claude Code Perspective
+
+- **Boris Cherny** (Head of Claude Code at Anthropic)
+ - Public statements: “I don’t prompt Claude anymore. I have loops running that prompt Claude and figuring out what to do. My job is to write loops.”
+ - Practical usage shared in the community: `/loop 5m /babysit`, `/loop 30m /slack-feedback`, `/loop /post-merge-sweeper`, `/pr-pruner`, etc.
+ - Emphasis on turning workflows into skills + loops.
+ - `/loop`, `/goal`, and `/schedule` as first-class primitives in Claude Code.
+
+- Related commentary from the Claude Code team (including @_catwu) highlighting loops as one of the highest-leverage features for long-term agentic work.
+
+## Related Concepts (Osmani)
+
+- Agent Harness Engineering
+- The Factory Model
+- Intent Debt
+- Comprehension Debt
+- Cognitive Surrender
+- Orchestration Tax
+- Code Agent Orchestra / Adversarial Code Review
+
+These provide important context and guardrails for loop design.
+
+## Other Early Signals
+
+- Peter Steinberger: emphasis on designing loops rather than prompting agents directly.
+- Various practitioners experimenting with closed-loop systems, feedback loop engineering, and "routines that prompt the model."
+
+## How This Repo Relates
+
+We treat the above sources as the current best articulation of the idea and aim to turn the abstract framework into practical, copyable patterns, templates, and tool-specific guidance (with special attention to the Grok Build TUI, which has strong native support for the primitives).
+
+If you have additional primary sources, real production loop stories, or corrections, please open an issue or PR.
diff --git a/templates/SKILL.md.loop-triage b/templates/SKILL.md.loop-triage
new file mode 100644
index 0000000..65b4a0c
--- /dev/null
+++ b/templates/SKILL.md.loop-triage
@@ -0,0 +1,54 @@
+---
+name: loop-triage
+description: >
+ Triage recent changes, CI failures, issues, and conversations.
+ Produces a concise, actionable findings report suitable for a loop to consume.
+ Writes structured output to a state file or Linear board.
+user_invocable: true
+---
+
+# Loop Triage Skill
+
+You are an expert engineering triage agent. Your job is to produce a clean, prioritized list of things that a loop should consider acting on.
+
+## Inputs (the loop will provide these)
+- Recent CI / test failures (last 24h)
+- Open issues / Linear tickets assigned to the team
+- Recent commits on main (last 24–48h)
+- Any Slack / chat threads the loop has visibility into
+- The current state file (what the loop already knows about)
+
+## Output Format
+
+Produce a markdown report with these sections:
+
+### 1. High-Priority Items (act on these)
+- Clear, one-line description
+- Why it matters (impact, risk, or customer pain)
+- Suggested next action for the loop (e.g. "draft minimal fix in isolated worktree")
+- Rough effort estimate
+
+### 2. Watch Items (monitor, do not act yet)
+- Same format but lower urgency
+
+### 3. Noise / Ignore
+- Brief list of things the loop looked at and decided were not worth action
+
+### 4. State Updates
+- Any facts the loop should remember for the next run (e.g. "PR #1234 now has 2 approvals")
+
+## Rules
+
+- Be brutally concise. The loop (and the human reading the state) will thank you.
+- Only put something in "High-Priority" if a reasonable engineer would want to know about it today.
+- When in doubt, put it in Watch or Noise rather than creating work.
+- Never propose architectural overhauls during triage — this skill is for signal, not invention.
+- Respect the project's existing skills and conventions (they will be provided in context).
+
+## Example Invocation (in a Grok loop)
+
+```
+/loop 30m Call $loop-triage and append the high-priority items to STATE.md. For any high-priority item that looks like a small bugfix, open a worktree and spawn a minimal-fix sub-agent.
+```
+
+The triage skill should be the "eyes" of the loop. Keep it focused and honest.