loop-it

---
name: loop-it
description: "Automated issue loop with checkpoint/resume: fetch open GitHub issues → dependency-aware topological sort → implement each issue end-to-end → review with /review-it → document with /note-it → ship with /ship-it → repeat. Persists state to .loop-state.json for crash recovery. Triggers on: loop-it, loop issues, auto implement, 批量实现, 循环实现, 实现所有issue, 恢复循环, resume loop."
user-invocable: true
allowed-tools:
  - Bash(gh:*)
  - Bash(git:*)
  - Bash(cat:*)
---

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

Fetch all open GitHub issues, resolve dependency order, implement each through the full pipeline (内联实现 → `/review-it` → `/note-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`、`/note-it`、`/ship-it` 仍是真实 skill，经 Skill 工具调用。

---

## Overview

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

---

## 前置检查

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

### Check 1: gh CLI 认证

```bash
gh auth status
```

失败 → 打印 `❌ gh CLI 未认证。运行: gh auth login`，退出。

### Check 2: Git 仓库

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

失败 → 打印 `❌ 不在 git 仓库中`，退出。

### Check 3: Git 工作树清洁度

```bash
git status --porcelain
```

有输出（dirty）→ 打印 `⚠️ 工作树有未提交的更改`，提供选项：
- A. `git stash` 暂存后继续
- B. 中止，让用户自行处理
- C. 强制继续（不推荐）

默认 B。

### Check 4: 在默认分支上

```bash
git branch --show-current
```

不在 main/master → 打印 `⚠️ 当前在 {branch} 分支`，提供选项：
- A. `git checkout main && git pull` 切换
- B. 继续在当前分支

### Check 5: 远程可达

```bash
git ls-remote --heads origin
```

失败 → 打印 `❌ 无法访问远程仓库。检查网络和权限`，退出。

### Check 6: 状态文件存在？

```bash
cat .loop-state.json
```

存在 → 打印进度摘要，提供选项：
- A. 从检查点恢复
- B. 从头开始（删除状态文件）
- C. 中止

---

## 状态文件

### 位置

`.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"
    }
  }
}
```

### 状态值

`pending` | `in_progress` | `skipped` | `shipped` | `failed` | `blocked`

### 写入规则

- 每次状态转换后立即写入（`pending` → `in_progress`、`in_progress` → `shipped`/`failed`/`skipped` 等）
- 写入使用 `cat > .loop-state.json << 'LOOPSTATE'\n{json}\nLOOPSTATE`
- 如果状态文件已存在但内容损坏（非法 JSON），打印警告，提供从头开始或中止的选项。**绝不自动覆盖损坏文件**
- 循环完成后保留状态文件（作为记录），用户可手动删除

---

## Step 1: Fetch Issues & Build Dependency Graph

Fetch all open issues:

```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:

1. Issues with no dependencies first (sorted by number ascending)
2. Issues whose dependencies are all shipped/closed next
3. Blocked issues (depend on other open issues) last
4. 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.

---

## Step 2: Resume or Initialize

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

1. Read the file
2. Print progress summary:

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

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

### If no state file

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

---

## Step 3: Process Single Issue

For each issue, print a banner:

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

### 3a. Branch Prep

Prepare a clean git environment for this issue:

```bash
# 确认在 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 保持一致）

### 3b. Skip or Implement

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` or `pending` → `blocked`, write checkpoint, run **3h Branch Cleanup**, proceed to next issue.

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

Update state: `pending` → `in_progress`, `phase: "implement"`, write checkpoint.

**由 agent 内联完成实现**（本环境无 `goal` 命令/skill 可调用，必须自己干）：

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

### 3d. Review with /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"`.

### 3e. Document with /note-it

After review, before ship — capture implementation notes:

```
/note-it
```

This creates `docs/issue#XXXX.html` with design decisions, deviations, tradeoffs, and open questions.

**On success:**

```
📝 Issue #{number} notes captured
```

**On failure** (can't determine issue number, etc.) — print warning but **do not block shipping**:

```
⚠️  /note-it failed for Issue #{number}: {reason}. Continuing to ship.
```

Write checkpoint with `phase: "note_done"`.

### 3f. Ship with /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 **3h Branch Cleanup**, proceed to next issue.

### 3g. Checkpoint

After successful ship, update state: `in_progress` → `shipped`, set `completed_at`, write checkpoint.

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

### 3h. Branch Cleanup

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

```bash
# 切回 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.

### Next 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
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

---

## 错误分类与恢复

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

| 错误类别 | 检测信号 | 恢复策略 | 最大重试 |
|----------|---------|---------|---------|
| 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 |

**恢复协议：**

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

---

## 进度可观测性

每完成一个 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
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

---

## 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 |
| 📝 | Notes (/note-it) |
| 🚀 | Ship |
| ⚠️ | Warning / retry |
| 📊 | Progress / summary |

---

## Safety Guards

- **Never force-push to main/master** — always use feature branches
- **Never skip review** — always run `/review-it` before `/ship-it`
- **Never skip notes** — always run `/note-it` before `/ship-it`（best-effort，不阻塞）
- **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` 时不要中止，直接内联实现

---

## 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 | 打印警告，按编号顺序打破循环 |
| `/note-it` can't find issue number | 打印警告，跳过 /note-it，继续 /ship-it |
| `.loop-state.json` is git-tracked | 警告用户添加到 .gitignore，继续 |
| 误以为需要外部 `goal` 命令 | 本环境无此命令；「实现 issue」由 agent 内联完成（读 issue → 写代码 → 测试），不要中止循环 |

---

## Relationship to Other Skills

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

Part of the goal-workflow pipeline:

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