loop-it

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

loop-it — 带检查点恢复的自动化 Issue 实现循环

Fetch all open GitHub issues, resolve dependency order, implement each through the full pipeline (内联实现 →

/review-it

→

/ship-it

), persist progress to state file, and resume from checkpoint on crash.

⚠️ 关键前提：实现步骤由 agent 内联自主完成，不依赖任何外部
/goal
命令。本环境中不存在可调用的
goal
命令或 skill。因此「实现 issue」这一步必须由 agent 内联完成：直接读取该 issue 的标题与正文（含其引用的 PRD/SPEC 与验收条件），自主完成"理解需求 → 写/改代码 → 跑测试与 lint → 满足全部验收条件"的闭环，持续工作直到该 issue 的验收条件全部满足且测试/构建通过。不要尝试用 Skill 工具调用
goal
（会报
goal is a UI command, not a skill
），也不要因为找不到
/goal
而中止循环。
/review-it
、
/ship-it
仍是真实 skill，经 Skill 工具调用。loop-it 循环中不调用
/note-it
。

获取所有GitHub开放Issue，解析依赖顺序，通过完整流程实现每个Issue（内联实现 →

/review-it

→

/ship-it

），将进度持久化到状态文件，并在崩溃后从检查点恢复。

⚠️ 关键前提：实现步骤由 agent 内联自主完成，不依赖任何外部
/goal
命令。本环境中不存在可调用的
goal
命令或 skill。因此「实现 issue」这一步必须由 agent 内联完成：直接读取该 issue 的标题与正文（含其引用的 PRD/SPEC 与验收条件），自主完成"理解需求 → 写/改代码 → 跑测试与 lint → 满足全部验收条件"的闭环，持续工作直到该 issue 的验收条件全部满足且测试/构建通过。不要尝试用 Skill 工具调用
goal
（会报
goal is a UI command, not a skill
），也不要因为找不到
/goal
而中止循环。
/review-it
、
/ship-it
仍是真实 skill，经 Skill 工具调用。loop-it 循环中不调用
/note-it
。

Overview

概述

前置检查 → 读取状态文件 → Fetch Issues → 构建依赖图 → 拓扑排序
                                                              |
    ┌───────────────────────────────────────────────────────────┘
    |
    v
┌──────────────── 单 Issue 循环 ────────────────┐
|                                               |
|  从检查点恢复？—— 跳过已完成/失败的             |
|                                               |
|  分支准备 (checkout main, pull, create branch) |
|        |                                      |
|  Skip/Blocked? ── 是 → 标记 skipped/blocked, 写检查点 |
|        |                                      |
|        否                                      |
|        |                                      |
|  内联实现 → 出错？→ 分类 → 恢复 → 重试        |
|        |              |                       |
|        |           失败 → 检查点, 下一个         |
|        |                                      |
|  /review-it → 有问题？→ 修复 → 重跑 review     |
|        |                                      |
|  /ship-it → 出错？→ 分类 → 恢复                |
|        |                                      |
|  分支清理 (checkout main, pull, delete branch) |
|        |                                      |
|  检查点 (标记 shipped)                         |
|        |                                      |
└────────┴──────────────────────────────────────┘
         |
         v
    全部完成 → 最终 Summary

前置检查 → 读取状态文件 → 获取 Issues → 构建依赖图 → 拓扑排序
                                                              |
    ┌───────────────────────────────────────────────────────────┘
    |
    v
┌──────────────── 单 Issue 循环 ────────────────┐
|                                               |
|  从检查点恢复？—— 跳过已完成/失败的             |
|                                               |
|  分支准备 (checkout main, pull, create branch) |
|        |                                      |
|  Skip/Blocked? ── 是 → 标记 skipped/blocked, 写检查点 |
|        |                                      |
|        否                                      |
|        |                                      |
|  内联实现 → 出错？→ 分类 → 恢复 → 重试        |
|        |              |                       |
|        |           失败 → 检查点, 下一个         |
|        |                                      |
|  /review-it → 有问题？→ 修复 → 重跑 review     |
|        |                                      |
|  /ship-it → 出错？→ 分类 → 恢复                |
|        |                                      |
|  分支清理 (checkout main, pull, delete branch) |
|        |                                      |
|  检查点 (标记 shipped)                         |
|        |                                      |
└────────┴──────────────────────────────────────┘
         |
         v
    全部完成 → 最终总结

前置检查

开始循环前，按顺序验证所有前提条件。任何检查失败则停止并打印错误。

Check 1: gh CLI 认证

检查1: gh CLI 认证

bash

gh auth status

失败 → 打印

❌ gh CLI 未认证。运行: gh auth login

，退出。

bash

gh auth status

失败 → 打印

❌ gh CLI 未认证。运行: gh auth login

，退出。

Check 2: Git 仓库

检查2: Git 仓库

bash

git rev-parse --is-inside-work-tree

失败 → 打印

❌ 不在 git 仓库中

，退出。

bash

git rev-parse --is-inside-work-tree

失败 → 打印

❌ 不在 git 仓库中

，退出。

Check 3: Git 工作树清洁度

检查3: Git 工作树清洁度

bash

git status --porcelain

有输出（dirty）→ 打印

⚠️ 工作树有未提交的更改

，提供选项：

A.
```
git stash
```
暂存后继续
B. 中止，让用户自行处理
C. 强制继续（不推荐）

默认 B。

bash

git status --porcelain

有输出（dirty）→ 打印

⚠️ 工作树有未提交的更改

，提供选项：

A.
```
git stash
```
暂存后继续
B. 中止，让用户自行处理
C. 强制继续（不推荐）

默认 B。

Check 4: 在默认分支上

检查4: 在默认分支上

bash

git branch --show-current

不在 main/master → 打印

⚠️ 当前在 {branch} 分支

，提供选项：

A.
```
git checkout main && git pull
```
切换
B. 继续在当前分支

bash

git branch --show-current

不在 main/master → 打印

⚠️ 当前在 {branch} 分支

，提供选项：

A.
```
git checkout main && git pull
```
切换
B. 继续在当前分支

Check 5: 远程可达

检查5: 远程可达

bash

git ls-remote --heads origin

失败 → 打印

❌ 无法访问远程仓库。检查网络和权限

，退出。

bash

git ls-remote --heads origin

失败 → 打印

❌ 无法访问远程仓库。检查网络和权限

，退出。

Check 6: 状态文件存在？

检查6: 状态文件存在？

bash

cat .loop-state.json

存在 → 打印进度摘要，提供选项：

A. 从检查点恢复
B. 从头开始（删除状态文件）
C. 中止

bash

cat .loop-state.json

存在 → 打印进度摘要，提供选项：

A. 从检查点恢复
B. 从头开始（删除状态文件）
C. 中止

状态文件

位置

.loop-state.json

，放在 repo 根目录。必须添加到
.gitignore
。如果文件被 git 跟踪，打印警告并建议用户添加到

.gitignore

。

.loop-state.json

，放在 repo 根目录。必须添加到
.gitignore
。如果文件被 git 跟踪，打印警告并建议用户添加到

.gitignore

。

格式

json

{
  "version": 1,
  "started_at": "2025-06-09T10:00:00Z",
  "updated_at": "2025-06-09T10:30:00Z",
  "repo": "owner/repo-name",
  "total_issues": 8,
  "issues": {
    "3": {
      "status": "shipped",
      "branch": "feat/issue-3-add-priority",
      "started_at": "2025-06-09T10:00:00Z",
      "completed_at": "2025-06-09T10:15:00Z",
      "attempts": 1
    },
    "4": {
      "status": "failed",
      "phase": "goal",
      "error_class": "build_failure",
      "branch": "feat/issue-4-filter-tasks",
      "started_at": "2025-06-09T10:15:00Z",
      "updated_at": "2025-06-09T10:30:00Z",
      "attempts": 3,
      "last_error": "test TestFilterPriority failed: expected 3, got 0"
    },
    "7": {
      "status": "pending"
    }
  }
}

json

{
  "version": 1,
  "started_at": "2025-06-09T10:00:00Z",
  "updated_at": "2025-06-09T10:30:00Z",
  "repo": "owner/repo-name",
  "total_issues": 8,
  "issues": {
    "3": {
      "status": "shipped",
      "branch": "feat/issue-3-add-priority",
      "started_at": "2025-06-09T10:00:00Z",
      "completed_at": "2025-06-09T10:15:00Z",
      "attempts": 1
    },
    "4": {
      "status": "failed",
      "phase": "goal",
      "error_class": "build_failure",
      "branch": "feat/issue-4-filter-tasks",
      "started_at": "2025-06-09T10:15:00Z",
      "updated_at": "2025-06-09T10:30:00Z",
      "attempts": 3,
      "last_error": "test TestFilterPriority failed: expected 3, got 0"
    },
    "7": {
      "status": "pending"
    }
  }
}

状态值

pending

in_progress

skipped

shipped

failed

blocked

pending

in_progress

skipped

shipped

failed

blocked

写入规则

每次状态转换后立即写入（
```
pending
```
→
```
in_progress
```
、
```
in_progress
```
→
```
shipped
```
/
```
failed
```
/
```
skipped
```
等）

写入使用

cat > .loop-state.json << 'LOOPSTATE'\n{json}\nLOOPSTATE

如果状态文件已存在但内容损坏（非法 JSON），打印警告，提供从头开始或中止的选项。绝不自动覆盖损坏文件
循环完成后保留状态文件（作为记录），用户可手动删除

每次状态转换后立即写入（
```
pending
```
→
```
in_progress
```
、
```
in_progress
```
→
```
shipped
```
/
```
failed
```
/
```
skipped
```
等）

写入使用

cat > .loop-state.json << 'LOOPSTATE'\n{json}\nLOOPSTATE

如果状态文件已存在但内容损坏（非法 JSON），打印警告，提供从头开始或中止的选项。绝不自动覆盖损坏文件
循环完成后保留状态文件（作为记录），用户可手动删除

Step 1: Fetch Issues & Build Dependency Graph

步骤1: 获取Issues & 构建依赖图

Fetch all open issues:

bash

gh issue list --state open --json number,title,labels,body --limit 100

获取所有开放Issue:

bash

gh issue list --state open --json number,title,labels,body --limit 100

Parse Dependencies

解析依赖

Read each issue body, look for patterns:

```
Dependencies: #3, #5
```
or
```
Depends on: #3
```
```
depends on #3
```
or
```
requires #3
```
(in body text)

Build a dependency graph. Sort using topological order:

Issues with no dependencies first (sorted by number ascending)
Issues whose dependencies are all shipped/closed next
Blocked issues (depend on other open issues) last
Circular dependencies → print warning
```
⚠️ 循环依赖检测到: #A ↔ #B，按编号顺序处理
```
，break cycle by number order

If no dependency patterns found in any issue body, fall back to number-ascending sort.

Print ordered list:

📋 Found N open issues (topological sort):
  #1: Add priority field (无依赖)
  #3: Display indicator (依赖 #1)
  #5: Add selector (依赖 #1)
  #7: Filter view (依赖 #1, #3)

If no open issues → print

✅ No open issues found. Nothing to do.

and exit.

读取每个Issue正文，查找以下模式:

```
Dependencies: #3, #5
```
或
```
Depends on: #3
```
```
depends on #3
```
或
```
requires #3
```
（正文文本中）

构建依赖图，使用拓扑排序:

无依赖的Issue优先（按编号升序排序）
所有依赖已交付/关闭的Issue次之
被阻塞的Issue（依赖其他开放Issue）最后

循环依赖 → 打印警告

⚠️ 循环依赖检测到: #A ↔ #B，按编号顺序处理

，按编号顺序打破循环

如果所有Issue正文中未找到依赖模式，回退到按编号升序排序。

打印有序列表:

📋 找到N个开放Issue（拓扑排序）:
  #1: 添加优先级字段（无依赖）
  #3: 显示指示器（依赖#1）
  #5: 添加选择器（依赖#1）
  #7: 筛选视图（依赖#1、#3）

如果没有开放Issue → 打印

✅ 未找到开放Issue，无需执行任何操作。

并退出。

Step 2: Resume or Initialize

步骤2: 恢复或初始化

.loop-state.json

exists (from 前置检查 Check 6)

如果存在.loop-state.json（来自前置检查Check 6）

Read the file
Print progress summary:

📊 从检查点恢复 (上次更新: {updated_at})
   ✅ Shipped:  #1, #3
   ⏭️  Skipped:   #2 (question)
   ❌ Failed:    #4 (build_failure — 3 attempts)
   📋 Remaining: #5, #7

For each
```
failed
```
issue: ask user — retry or skip?
For
```
in_progress
```
issues: check if branch exists, changes exist → decide resume from current state or restart
Skip all
```
shipped
```
/
```
skipped
```
issues
Continue from first pending/retryable issue

读取文件
打印进度摘要:

📊 从检查点恢复 (上次更新: {updated_at})
   ✅ 已交付:  #1, #3
   ⏭️ 已跳过:   #2（问题类）
   ❌ 失败:    #4（build_failure — 3次尝试）
   📋 剩余: #5, #7

对于每个
```
failed
```
Issue: 询问用户 — 重试还是跳过?
对于
```
in_progress
```
Issue: 检查分支是否存在、是否有变更 → 决定从当前状态恢复或重新开始
跳过所有
```
shipped
```
/
```
skipped
```
Issue
从第一个待处理/可重试的Issue继续

If no state file

如果没有状态文件

Initialize new state file with all fetched issues as
```
pending
```
Start from first issue in topological order

初始化新状态文件，将所有获取到的Issue标记为
```
pending
```
从拓扑排序的第一个Issue开始

Step 3: Process Single Issue

步骤3: 处理单个Issue

For each issue, print a banner:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔄 Processing Issue #{number}: {title}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

对于每个Issue，打印横幅:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔄 处理Issue #{number}: {title}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

3a. Branch Prep

3a. 分支准备

Prepare a clean git environment for this issue:

bash

undefined

为该Issue准备干净的git环境:

bash

undefined

确认在 main 上

确认在main分支

git checkout main git pull

创建功能分支

git checkout -b feat/issue-{N}-{short-desc}


Branch naming: `feat/issue-N-short-desc` or `fix/issue-N-short-desc`（与 /ship-it 保持一致）

git checkout -b feat/issue-{N}-{short-desc}


分支命名: `feat/issue-N-short-desc` 或 `fix/issue-N-short-desc`（与/ship-it保持一致）

3b. Skip or Implement

3b. 跳过或实现

Read the issue title and body. Decide if it needs code implementation:

Skip if the issue is:

A question / discussion / clarification
Documentation-only (typos, wording)
Already implemented (check codebase)
A duplicate of another issue
Clearly labeled
```
wontfix
```
,
```
question
```
,
```
discussion
```
, or
```
invalid
```
Not actionable (no clear acceptance criteria and cannot infer any)

Skip (blocked) if the issue has unresolved dependencies:

Check the dependency graph from Step 1
If any dependency issue is not
```
shipped
```
(still
```
pending
```
,
```
failed
```
,
```
blocked
```
, or not in state file) → skip as blocked
The dependency issue itself may have failed or been skipped — in either case, this issue cannot proceed safely

When skipping:

⏭️  Skipping Issue #{number}: {title}
   Reason: {why}

When blocked:

🔒 Blocking Issue #{number}: {title}
   Reason: dependency #{dep_number} not shipped ({status})

Update state:

pending

→

skipped

pending

→

blocked

, write checkpoint, run 3g Branch Cleanup, proceed to next issue.

读取Issue标题和正文，判断是否需要代码实现:

以下情况跳过Issue:

问题/讨论/澄清类
仅文档修改（错别字、措辞调整）
已实现（检查代码库）
重复Issue
明确标记为
```
wontfix
```
、
```
question
```
、
```
discussion
```
或
```
invalid
```
无行动性（无明确验收条件且无法推断需求）

以下情况跳过（被阻塞）:

Issue存在未解决的依赖:
检查步骤1的依赖图
如果任何依赖Issue未被
```
shipped
```
（仍为
```
pending
```
、
```
failed
```
、
```
blocked
```
或未在状态文件中）→ 标记为阻塞并跳过
依赖Issue本身可能已失败或被跳过 — 无论哪种情况，该Issue都无法安全推进

跳过时打印:

⏭️  跳过Issue #{number}: {title}
   原因: {why}

被阻塞时打印:

🔒 Issue #{number}被阻塞: {title}
   原因: 依赖#{dep_number}未交付({status})

更新状态:

pending

→

skipped

或

pending

→

blocked

，写入检查点，执行3g分支清理，继续下一个Issue。

3c. Implement (内联自主实现)

3c. 实现（内联自主实现）

Update state:

pending

→

in_progress

phase: "implement"

, write checkpoint.

由 agent 内联完成实现（本环境无

goal

命令/skill 可调用，必须自己干）：

读取该 issue 的标题与正文，提取需求与全部验收条件（Acceptance Criteria）；若正文引用了 PRD/SPEC 文件（如
```
tasks/prd-*.md
```
），一并读取作为上下文
阅读相关现有代码，遵循项目既有风格、命名与依赖约定
实现/修改代码以满足全部验收条件
跑项目的构建、测试与 lint（如
```
go build ./...
```
、
```
go vet ./...
```
、
```
go test ./...
```
）
持续工作直到该 issue 的验收条件全部满足且测试/构建/lint 通过

不要尝试用 Skill 工具调用
goal
（会报
goal is a UI command, not a skill
），也不要因找不到
/goal
而中止——实现就是你自己内联完成的工作。

On success:

✅ Issue #{number} implementation complete

Write checkpoint with

phase: "implement_done"

On failure — classify error (see 错误分类与恢复), apply recovery strategy, retry up to max attempts. If all retries exhausted:

⚠️  Issue #{number} failed: {error_class} after {N} attempts
   Manual intervention required.

Update state:

in_progress

→

failed

, write checkpoint, run 3g Branch Cleanup, proceed to next issue.

更新状态:

pending

→

in_progress

，

phase: "implement"

，写入检查点。

由agent内联完成实现（本环境无

goal

命令/skill可调用，必须自主完成）：

读取该Issue的标题与正文，提取需求与全部验收条件（Acceptance Criteria）；若正文引用了PRD/SPEC文件（如
```
tasks/prd-*.md
```
），一并读取作为上下文
阅读相关现有代码，遵循项目既有风格、命名与依赖约定
实现/修改代码以满足全部验收条件
运行项目的构建、测试与lint（如
```
go build ./...
```
、
```
go vet ./...
```
、
```
go test ./...
```
）
持续工作直到该Issue的验收条件全部满足且测试/构建/lint通过

不要尝试用Skill工具调用
goal
（会报
goal is a UI command, not a skill
），也不要因找不到
/goal
而中止——实现就是你自己内联完成的工作。

成功时:

✅ Issue #{number}实现完成

写入检查点，标记

phase: "implement_done"

。

失败时 — 分类错误（参见错误分类与恢复），应用恢复策略，重试至最大次数。若所有重试均失败:

⚠️  Issue #{number}失败: {error_class}，已尝试{N}次
   需要人工干预。

更新状态:

in_progress

→

failed

，写入检查点，执行3g分支清理，继续下一个Issue。

3d. Review with /review-it

3d. 使用/review-it评审

Write checkpoint with

phase: "review"

/review-it

If review finds actionable issues:

🔍 Review found N issue(s) for #{number}. Fixing...

Fix each accepted finding, re-run

/review-it

. Repeat until clean or max 2 review rounds.

If review is clean:

✅ Review clean for Issue #{number}

Write checkpoint with

phase: "review_done"

写入检查点，标记

phase: "review"

。

/review-it

如果评审发现可修复问题:

🔍 评审发现#{number}存在N个问题，正在修复...

修复每个确认的问题，重新运行

/review-it

。重复至评审通过或最多2轮评审。

如果评审通过:

✅ Issue #{number}评审通过

写入检查点，标记

phase: "review_done"

。

3e. Ship with /ship-it

3e. 使用/ship-it交付

/ship-it

This commits, pushes, creates PR, merges, and closes the issue.

On success:

🚀 Issue #{number} shipped successfully!

On failure — classify error (see 错误分类与恢复), apply recovery. If unresolvable:

⚠️  Issue #{number} ship failed: {error}. Manual merge required.

Update state:

in_progress

→

failed

phase: "ship"

, write checkpoint, run 3g Branch Cleanup, proceed to next issue.

/ship-it

此命令会提交代码、推送、创建PR、合并并关闭Issue。

成功时:

🚀 Issue #{number}成功交付!

失败时 — 分类错误（参见错误分类与恢复），应用恢复策略。若无法解决:

⚠️  Issue #{number}交付失败: {error}，需要人工合并。

更新状态:

in_progress

→

failed

，

phase: "ship"

，写入检查点，执行3g分支清理，继续下一个Issue。

3f. Checkpoint

3f. 检查点

After successful ship, update state:

in_progress

→

shipped

, set

completed_at

, write checkpoint.

Print progress (see 进度可观测性).

成功交付后，更新状态:

in_progress

→

shipped

，设置

completed_at

，写入检查点。

打印进度（参见进度可观测性）。

3g. Branch Cleanup

3g. 分支清理

After each issue (shipped, skipped, or failed):

bash

undefined

每个Issue处理完成后（交付、跳过或失败）:

bash

undefined

切回 main

切回main分支

git checkout main git pull

删除本地功能分支（仅当 shipped 时）

删除本地功能分支（仅当已交付时）

git branch -d feat/issue-{N}-{short-desc}


**For failed issues**: do NOT delete the branch. Keep it for investigation.

git branch -d feat/issue-{N}-{short-desc}


**失败的Issue**: 不要删除分支，保留以供调查。

Next Issue

下一个Issue

Return to Step 3 for the next issue in topological order.

When all issues processed, print final summary:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📊 Loop Complete — Summary
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ✅ Shipped:   N issues  (#1, #3, ...)
  ⏭️  Skipped:   N issues  (#2 — reason, #5 — reason, ...)
  🔒 Blocked:   N issues  (#7 — depends on #4, ...)
  ❌ Failed:    N issues  (#4 — error, ...)
  📋 Total:     N issues
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

返回步骤3处理拓扑排序中的下一个Issue。

所有Issue处理完成后，打印最终总结:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📊 循环完成 — 总结
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ✅ 已交付:   N个Issue  (#1, #3, ...)
  ⏭️ 已跳过:   N个Issue  (#2 — 原因, #5 — 原因, ...)
  🔒 被阻塞:   N个Issue  (#7 — 依赖#4, ...)
  ❌ 失败:    N个Issue  (#4 — 错误信息, ...)
  📋 总计:     N个Issue
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

错误分类与恢复

当错误发生时，先分类，再按策略恢复。

错误类别	检测信号	恢复策略	最大重试
build_failure	编译错误、undefined、类型错误	读错误，修代码，重新构建	3
test_failure	断言失败、test failed	读测试输出，修实现，重跑测试	3
lint_failure	lint 错误、格式问题	自动修复 (lint --fix)，重跑	2
merge_conflict	CONFLICT 标记	rebase origin/main，解决冲突，push	2
ci_failure	gh pr checks 失败	读 CI 日志，本地修复，push	2
auth_failure	403、401、认证错误	停止，告知用户重新认证	0
rate_limit	rate limit、secondary abuse	等待 60s，重试	3
issue_unclear	issue 无验收条件且无法推断需求	跳过，标记 failed	0
network_error	timeout、connection refused	等待 30s，重试	3
unknown	其他情况	记录完整错误，跳过	0

恢复协议：

匹配错误类别
匹配成功 → 应用恢复策略，重试最多 N 次
重试全部失败 → 标记
```
failed
```
，写检查点，继续下一个 issue
无法匹配 → 标记
```
failed
```
（error_class:
```
unknown
```
），继续
绝不无限重试。绝不未经确认 force-push。

当错误发生时，先分类，再按策略恢复。

错误类别	检测信号	恢复策略	最大重试
build_failure	编译错误、undefined、类型错误	读取错误信息，修复代码，重新构建	3
test_failure	断言失败、test failed	读取测试输出，修复实现，重新运行测试	3
lint_failure	lint错误、格式问题	自动修复(lint --fix)，重新运行	2
merge_conflict	CONFLICT标记	基于origin/main变基，解决冲突，推送	2
ci_failure	gh pr checks失败	读取CI日志，本地修复，推送	2
auth_failure	403、401、认证错误	停止，告知用户重新认证	0
rate_limit	rate limit、secondary abuse	等待60秒，重试	3
issue_unclear	Issue无验收条件且无法推断需求	跳过，标记为failed	0
network_error	超时、connection refused	等待30秒，重试	3
unknown	其他情况	记录完整错误，跳过	0

恢复协议：

匹配错误类别
匹配成功 → 应用恢复策略，最多重试N次
全部重试失败 → 标记为
```
failed
```
，写入检查点，继续下一个Issue
无法匹配 → 标记为
```
failed
```
（error_class:
```
unknown
```
），继续
绝不无限重试。绝不未经确认强制推送。

进度可观测性

每完成一个 issue 后，打印结构化进度：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📊 Progress: 3/8 issues (37%)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ✅ Shipped:  #1, #3
  ⏭️  Skipped:   #2 (question), #6 (duplicate)
  🔒 Blocked:   #7 (depends on #4 — failed)
  ❌ Failed:    #4 (build_failure — 3 attempts)
  📋 Remaining: #5, #8
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

每完成一个Issue后，打印结构化进度：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📊 进度: 3/8个Issue (37%)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ✅ 已交付:  #1, #3
  ⏭️ 已跳过:   #2（问题类）, #6（重复）
  🔒 被阻塞:   #7（依赖#4 — 失败）
  ❌ 失败:    #4（build_failure — 3次尝试）
  📋 剩余: #5, #8
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Logging Rules

日志规则

Every key step MUST print a log line with emoji prefix:

Emoji	Meaning
📋	Fetch / list
🔄	Processing issue
⏭️	Skip
🔒	Blocked (dependency not shipped)
✅	Success
❌	Failure
🔍	Review
🚀	Ship
⚠️	Warning / retry
📊	Progress / summary

每个关键步骤必须打印带emoji前缀的日志行:

Emoji	含义
📋	获取/列表
🔄	处理Issue
⏭️	跳过
🔒	阻塞（依赖未交付）
✅	成功
❌	失败
🔍	评审
🚀	交付
⚠️	警告/重试
📊	进度/总结

Safety Guards

安全防护

Never force-push to main/master — always use feature branches
Never skip review — always run
```
/review-it
```
before
```
/ship-it
```
Max retries per error class — 参见错误分类与恢复表，不无限重试
Max 2 review rounds — don't over-polish
Pause on CI failure — log and continue, don't auto-override branch protection
Preserve issue labels — only close issues that were actually shipped
Never auto-delete failed branches — 保留供调查
Checkpoint at every transition — 每次状态变更写检查点，不仅仅在 ship 时
State file integrity — 损坏时警告用户，绝不自动覆盖
State file in .gitignore — 提醒用户添加
```
.loop-state.json
```
Strictly sequential — 一次只处理一个 issue（实现会修改工作树，不能并行）
Skip dependency-blocked issues — 依赖的 issue 未 shipped 时标记
```
blocked
```
实现由 agent 内联完成 — 本环境无
```
goal
```
命令/skill 可调用；「实现 issue」必须由 agent 自己读 issue、写代码、跑测试完成。报
```
goal is a UI command, not a skill
```
时不要中止，直接内联实现

绝不强制推送到main/master分支 — 始终使用功能分支
绝不跳过评审 — 交付前必须运行
```
/review-it
```
按错误类别设置最大重试次数 — 参见错误分类与恢复表，不无限重试
最多2轮评审 — 过度优化
CI失败时暂停 — 记录日志并继续，不自动覆盖分支保护规则
保留Issue标签 — 仅关闭实际已交付的Issue
绝不自动删除失败分支 — 保留供调查
每次状态转换都写入检查点 — 不仅仅在交付时
状态文件完整性 — 损坏时警告用户，绝不自动覆盖
状态文件加入.gitignore — 提醒用户添加
```
.loop-state.json
```
严格串行处理 — 一次只处理一个Issue（实现会修改工作树，无法并行）
跳过依赖阻塞的Issue — 依赖的Issue未交付时标记为
```
blocked
```
实现由agent内联完成 — 本环境无
```
goal
```
命令/skill可调用；「实现Issue」必须由agent自己读取Issue、编写代码、运行测试完成。遇到
```
goal is a UI command, not a skill
```
错误时不要中止，直接内联实现

Edge Cases

边缘情况

Scenario	Handling
No open issues	Print "nothing to do" and exit
All issues are questions	Skip all, report summary
`gh` not authenticated	Print error, suggest `gh auth login` , exit
Issue has no body	Use title only to decide skip/implement
Issue references PRD/SPEC	读取被引用的 PRD/SPEC 作为上下文，agent 内联实现
Multiple issues depend on each other	Topological sort; dependencies already shipped first
Git repo is dirty before starting	前置检查 Check 3: stash/abort/force
State file corrupted (invalid JSON)	警告用户，提供从头开始或中止选项。绝不自动覆盖
State file from different repo	检测 repo 字段不匹配，警告，提供从头开始选项
Issue `in_progress` from previous run	检查分支是否存在、是否有变更 → 恢复或重新开始
User aborts mid-loop	状态文件已包含最新检查点，下次运行可恢复
New issues created during loop	不重新获取。完成当前批次后运行新 `/loop-it`
Circular dependencies	打印警告，按编号顺序打破循环
`.loop-state.json` is git-tracked	警告用户添加到 .gitignore，继续
误以为需要外部 `goal` 命令	本环境无此命令；「实现 issue」由 agent 内联完成（读 issue → 写代码 → 测试），不要中止循环

场景	处理方式
无开放Issue	打印"无需执行任何操作"并退出
所有Issue均为问题类	全部跳过，报告总结
`gh` 未认证	打印错误，建议运行 `gh auth login` ，退出
Issue无正文	仅使用标题判断是否跳过/实现
Issue引用PRD/SPEC	读取被引用的PRD/SPEC作为上下文，agent内联实现
多个Issue相互依赖	拓扑排序；已交付的依赖优先处理
Git仓库启动时处于dirty状态	前置检查Check 3: 暂存/中止/强制继续
状态文件损坏（无效JSON）	警告用户，提供从头开始或中止选项。绝不自动覆盖
状态文件来自其他仓库	检测到repo字段不匹配，警告用户，提供从头开始选项
上次运行遗留 `in_progress` 状态的Issue	检查分支是否存在、是否有变更 → 恢复或重新开始
用户中途中止循环	状态文件已包含最新检查点，下次运行可恢复
循环期间创建新Issue	不重新获取。完成当前批次后运行新的 `/loop-it`
循环依赖	打印警告，按编号顺序打破循环
`.loop-state.json` 被git跟踪	警告用户添加到.gitignore，继续执行
误以为需要外部 `goal` 命令	本环境无此命令；「实现Issue」由agent内联完成（读取Issue → 编写代码 → 测试），不要中止循环

Relationship to Other Skills

与其他Skill的关系

/loop-it
  ├── 内联实现   ← implement each issue（agent 自主读 issue、写代码、测试；非外部命令）
  ├── /review-it  ← review code before shipping（skill）
  └── /ship-it    ← commit, PR, merge, close（skill）

Part of the goal-workflow pipeline:

/prd → /prd-to-spec → /to-issues → /loop-it (→ 内联实现 → /review-it → /ship-it)×N

/loop-it
  ├── 内联实现   ← 实现每个Issue（agent自主读取Issue、编写代码、测试；非外部命令）
  ├── /review-it  ← 交付前评审代码（skill）
  └── /ship-it    ← 提交、创建PR、合并、关闭（skill）

属于goal-workflow流程的一部分:

/prd → /prd-to-spec → /to-issues → /loop-it (→ 内联实现 → /review-it → /ship-it)×N

loop-it

Original

Translation

loop-it — 带检查点恢复的自动化 Issue 实现循环

loop-it — 带检查点恢复的自动化 Issue 实现循环

Overview

概述

前置检查

前置检查

Check 1: gh CLI 认证

检查1: gh CLI 认证

Check 2: Git 仓库

检查2: Git 仓库

Check 3: Git 工作树清洁度

检查3: Git 工作树清洁度

Check 4: 在默认分支上

检查4: 在默认分支上

Check 5: 远程可达

检查5: 远程可达

Check 6: 状态文件存在？

检查6: 状态文件存在？

状态文件

状态文件

位置

位置

格式

格式

状态值

状态值

写入规则

写入规则

Step 1: Fetch Issues & Build Dependency Graph

步骤1: 获取Issues & 构建依赖图

Parse Dependencies

解析依赖

Step 2: Resume or Initialize

步骤2: 恢复或初始化

If .loop-state.json exists (from 前置检查 Check 6)

如果存在.loop-state.json（来自前置检查Check 6）

If no state file

如果没有状态文件

Step 3: Process Single Issue

步骤3: 处理单个Issue

3a. Branch Prep

3a. 分支准备

确认在 main 上

确认在main分支

创建功能分支

创建功能分支

3b. Skip or Implement

3b. 跳过或实现

3c. Implement (内联自主实现)

3c. 实现（内联自主实现）

3d. Review with /review-it

3d. 使用/review-it评审

3e. Ship with /ship-it

3e. 使用/ship-it交付

3f. Checkpoint

3f. 检查点

3g. Branch Cleanup

3g. 分支清理

切回 main

切回main分支

删除本地功能分支（仅当 shipped 时）

删除本地功能分支（仅当已交付时）

Next Issue

下一个Issue

错误分类与恢复

错误分类与恢复

进度可观测性

进度可观测性

Logging Rules

日志规则

Safety Guards

安全防护

Edge Cases

边缘情况

Relationship to Other Skills

与其他Skill的关系

If
`.loop-state.json`
exists (from 前置检查 Check 6)