auto-iterate

Skill: auto-iterate

Role: single-step governance executor — the paired execution layer of plan-next WHAT: each call executes 1 plan-next routing suggestion, emits continuation_signal for /loop to drive iteration forward HOW: internally calls plan-next → picks the highest-priority card → human gate judgment → executes the sub-skill → post-execution verification → outputs a report Difference: different from plan-next(read-only diagnosis, does not execute); different from /loop(only schedules, does not execute business logic); different from automate-repair(fixes code defects, does not advance the governance layer)

Purpose

Turn plan-next's routing suggestions into one executable governance action, making fully automatic autopilot (/loop /auto-iterate) possible.

plan-next can only diagnose and suggest; the user must manually execute each suggestion. auto-iterate fills this execution gap, and together with /loop achieves three-layer orthogonal automation:

Layer	Skill	Responsibility
Schedule	`/loop`	Triggered once every N minutes
Drive	auto-iterate	Read routing → execute 1 step → report
Diagnose	`plan-next`	Inventory + identify gaps + routing suggestions (read-only)

Core Objectives

Primary objective: each call executes exactly 1 governance action, and clearly reports the execution result and whether to continue via IterationStepReport.

Success criteria(all must be met):

✅ Single-step execution: each call executes exactly 1 routing action
✅ Stuck detection: the same routing card fingerprint appears 2 consecutive times within a session and the target has not advanced, triggering the stalled signal
✅ Post-execution verification: after executing the sub-skill, rerun plan-next to confirm whether the target card has disappeared
✅ Human gate: strategic/creative skills (define-mission, design-strategic-goals, etc.) must pause and inform the user before execution
✅ Explicit continue signal: each call must output one of the continuation_signal five values in IterationStepReport

Acceptance test: after execution completes, does IterationStepReport clearly state what was executed, what the result was, and whether the next step is to continue or requires human intervention?

Scope Boundaries

This skill is responsible for：

Internally calling plan-next to obtain routing
Selecting the highest-priority card from "what to do now" (紧急 > 重要 > 缓）
Stuck detection (fingerprint comparison within a session)
Human gate judgment
Executing 1 sub-skill
Lightweight post-execution verification
Outputting IterationStepReport

This skill is not responsible for：

Governance diagnosis and routing generation → plan-next
Loop scheduling → /loop(built into Claude Code)
Code defect fix loop → automate-repair
Strategic/creative decision content (mission, vision, strategic goal content) → requires human
Work item tracking and status maintenance → align-work-item-manifest

Handoff point：

continuation_signal: done → governance ready, inform the user, stop
continuation_signal: blocked | stalled | error → Manual intervention required, stop and explain the reason

Use cases

"Continue advancing governance until complete" → /loop /auto-iterate
"Execute the next governance action" → /auto-iterate
"Fully automatic autopilot, advance once every 30 minutes" → /loop /auto-iterate 30m
"Only view what will be executed next (without executing)" → Use /plan-next

Behavior

Step 0: Pre-check

Read the governance document path (defaults to the same as plan-next's docs_root, or explicitly provided by the caller).

Step 1: Call plan-next

Internally call /plan-next, capture the routing output. If the caller provided pre_run_output, use it directly and skip this step.

Recordtarget card fingerprint(for stuck detection):

指纹 = 主题字段 + "||" + 治理上下文字段

Step 2: Parse routing

Take the single highest-priority item from "what to do now" (紧急 → 重要 → 缓 → 待执行）。

Three-state determination(do not mistake "awaiting execution" for "completed"):

plan-next output	continuation_signal	Meaning
Has routing cards (urgent/important/deferred)	Proceed to Step 3 to continue	Governance has gaps, sub-skills can be executed
Contains only "pending execution" cards (task already split, awaiting development)	`blocked`	Governance ready, awaiting external execution
Completely empty (all target status=done and L1 KPI achieved)	`done`	Governance + acceptance both achieved

Key constraints：

"What to do now" being empty ≠ done. Must first confirm whether plan-next determined this after the L1 acceptance KPI check + L5 pending-execution branch
If the plan-next output does not contain the L1 acceptance KPI status field → treat the plan-next call as non-compliant, output error + prompt to upgrade plan-next
Strategic goal status = approved but acceptance not achieved → plan-next will necessarily return routing (establish KPI or pending-execution cards), should not be empty

Step 3: Stuck detection

Compare this fingerprint with thefingerprint of the last executionwithin the session:

Same → continuation_signal: stalled, indicating "the target card did not advance after the last execution", stop
Different (or first call) → continue

Step 4: Manual gate

In the following situations, must pause, output an explanation, set continuation_signal: blocked：

Recommended skill belongs to the creative/strategic category:define-mission、design-strategic-goals、define-vision、define-north-star、define-strategic-pillars
Routing card completion marker contains "when blocked, return to plan-next for re-evaluation" and it has currently been triggered
Routing card label is 待执行: governance ready, requires external development execution, no governance skill can be invoked
The first routing item is to establish the L1 acceptance KPI data sourceand the recommended skill belongs to the design/architecture category: manual confirmation of the monitoring plan is required, do not execute automatically

Step 5: Execute

Invoke the "recommended skill" command in the routing card (format:/skill-name [聚焦点]）。

Execution fails and there is no recovery path → continuation_signal: error, output the report, stop.

Step 6: Post-execution verification

Force re-run /plan-next(cannot be skipped), check whether the target card has disappeared from "what to do now". done The only legitimate source of the signal is the verification result of this step—it is forbidden to substitute the model's own inference.

Result	Action
Card disappears, "what to do now" still has entries	`continuation_signal: advance`
Card disappears, "what to do now" is empty	`continuation_signal: done`
Card still exists	Update the stuck counter; if the count reaches 2 → `continuation_signal: stalled`

Step 7: Output IterationStepReport

Interaction mode with /loop (important)

/loop There are two modes, and the way continuation_signal is consumed is completely different:

/loop mode	Trigger method	Signal consumption	Recommended usage
Dynamic	No interval (self-scheduling ScheduleWakeup)	Read `continuation_signal`: done/blocked/stalled/error will stop the loop	✅ Recommended：`/loop /auto-iterate`(without interval)
Fixed-interval (cron)	Has interval (e.g. `5m`）	Not read `continuation_signal`: cron keeps triggering, signals are ignored	⚠️ Not recommended for auto-stop scenarios; the user must manually CronDelete

Forced behavior：

When fixed-interval cron mode is detected (via the presence of a CronCreate record in the session context with prompt=/auto-iterate), the first IterationStepReport must warn the user: "Currently in cron mode, signals are ignored; if you do not want continuous triggering, switch to dynamic /loop or CronDelete after receiving stalled/blocked/done"
stalled When the signal appears for the 2nd consecutive time, the IterationStepReport must explicitly state "Strongly recommend immediate CronDelete " and provide the job ID

Solution: When the user wants "auto-stop after governance is ready", they should use /loop /auto-iterate(no interval, dynamic mode), not /loop 1m /auto-iterate。

Input and Output

Input

Parameter	Required	Default	Description
`docs_root`	No	auto	Governance document root directory; auto uses the same default path as plan-next
`pre_run_output`	No	—	Pre-run plan-next output; when provided, skip the internal call

Output: IterationStepReport

## 这次自动推进做了什么

- **做了什么**：[用文件名/功能名说明；禁用"路由卡片""治理层级"等词]
- **为什么要修**：[发现了什么具体问题；首次新建文件时省略]
- **改了什么**（有文件变更时）：
  - 修改前：...
  - 修改后：...
- **结果**：成功 ✅ | 需要你来决定 ⚠️ | 出错了 ❌
- **下一步**：继续自动推进 | 全部完成，无需继续 | 需要你决定：[说明] | 卡住了：[说明]
- _（内部）继续信号：advance | done | blocked | stalled | error_

continuation_signal semantics

Value	Meaning	/loop behavior
`advance`	Action completed, governance still has work	Continue triggering next time
`done`	After Step 6 reruns plan-next, "what to do now" is empty;It is forbidden to output this value based on the model's own inference	Stop the loop
`blocked`	Requires human decision or external dependency	Stop the loop, wait for user intervention
`stalled`	The same routing card has no progress for 2 consecutive times	Stop the loop, report the reason for being stuck
`error`	Sub-skill execution failed and there is no recovery path	Stop the loop, report the error

Limitations

Hard Boundaries

Rule 1: Each call MUST NOT execute more than 1 action

Verification: In IterationStepReport, the 调用技能 field has only 1 entry
Consequence: REJECT (violates the single-step semantics of the three-layer model)

Rule 2: Strategic creative skills MUST trigger a human gate and must not be executed directly

Verification: When the recommended skill is define-mission etc., the report shows blocked
Consequence: REJECT (strategic decisions should not be automated)

Rule 3: each invocation MUST output a valid continuation_signal

Verification: IterationStepReport contains the 继续信号 field and its value is within the five-value enum
Consequence: REJECT (/loop relies on this signal to decide whether to continue)

Rule 4：done signal MUST come from the step 6 plan-next rerun result, and MUST NOT come from the model's own inference

Verification: IterationStepReport notes do not contain self-assessment language such as "governance layer fully ready" or "all currently executable ... have been created";done is output only after step 6 confirms that "what should be done now" is empty
Consequence: REJECT (the model replaced plan-next in making the routing decision, breaking the responsibility boundaries of the three-layer model)

Rule 5：done MUST satisfy all three simultaneously: "plan-next output contains a declaration that the L1 acceptance KPI has been achieved" AND "what should be done now is empty" AND "no cards pending execution"

Verification: when IterationStepReport outputs done , it cites the KPI status field from the plan-next governance context (e.g., "citation visibility rate 85% ≥ 80% (achieved)"); as long as the KPI is not achieved, or data is missing, or there are cards marked "pending execution", done
Consequence: REJECT (mistaking "strategic objective status=approved" for acceptance achievement, causing /loop to stop when it should not)

Rule 6: upon detecting a card labeled "pending execution", MUST output blocked, and MUST NOT attempt to execute or mark it done

Verification: in IterationStepReport, selected_skill is empty or N/A, and next_step contains wording such as "governance ready, pending external execution"
Consequence: REJECT

Skill Boundaries

Does not do the following(handled by other skills):

Governance diagnosis and routing → plan-next
Loop scheduling → /loop
Code fix loop → automate-repair
Document evaluation → assess-docs
Work item status maintenance → align-work-item-manifest

Anti-patterns

✅ Correct: single-step execution + post-verification + continue signal

1. plan-next → 2 条路由：breakdown-tasks（缓）、analyze-requirements（缓）
2. 取最高优先级：breakdown-tasks
3. 人工闸门：非创意类 → 继续
4. 执行 /breakdown-tasks
5. 重跑 plan-next → breakdown-tasks 卡片消失
6. 报告 continuation_signal: advance

Why it is correct: single-step execution preserves the orthogonality of the three-layer model; post-verification confirms real progress; /loop naturally drives the next step.

❌ Wrong: executing two routes at once

1. plan-next → 2 条路由
2. auto-iterate 执行 breakdown-tasks AND analyze-requirements

Problem analysis: violates single-step semantics; if the second one fails, it is difficult to determine the rollback scope; breaks /loop's granularity control.

❌ Wrong: bypassing the human gate

1. plan-next 路由：/design-strategic-goals
2. auto-iterate 直接执行，不暂停

Problem analysis: strategic objective content requires human judgment; automatic execution produces low-quality strategy documents, and the user is unaware.

❌ Wrong: skipping post-execution verification and directly reporting advance

1. 执行 /breakdown-tasks 完成
2. 直接报告 continuation_signal: advance
3. 实际上文件未成功写入

Problem analysis: the lack of post-verification leads to false advance; the next plan-next still gives the same route, triggering stalled.

❌ Wrong: judging "governance complete" on its own instead of rerunning plan-next in step 6

1. 执行子技能成功
2. 模型推断"当前可执行的治理文档均已创建，其余依赖开发者执行层"
3. 直接输出 continuation_signal: done，未重跑 plan-next

Problem analysis: the model has seized the authority to judge "governance layer vs developer execution layer"—this is plan-next's responsibility, not auto-iterate's. Blocked nodes (such as T48/T52 depending on T47/T49) should be routed by plan-next and trigger the blocked signal, rather than the model declaring "governance complete" on its own.done has only one legitimate source: after step 6 reruns plan-next, "what should be done now" is empty.

❌ Wrong: treating `战略目标 status=approved` as acceptance achieved → outputting done

1. plan-next: G1 status=approved，验收 KPI「引用可见率」无监控数据
2. auto-iterate 取空"现在该做"（plan-next 实际应返回路由，但此例假定 plan-next 也漏判）
3. 输出 done，/loop 停止
4. 实际上 G1 远未达成；下次唤醒检查时陷入 stalled 死循环

Problem analysis: Violates Rule 5 — you must first confirm the plan-next output contains the L1 acceptance KPI status field and that the KPI has been achieved; otherwise, even if "what to do now" is empty, it should not be done.approved only represents decision approval; when acceptance has not been achieved, you should continue to push forward, and the output should be blocked (waiting for execution + waiting for KPI data).

❌ Error: Inferring done from intermediate-layer (M5/task) status

1. plan-next 报：M5 任务全部 pending、设计 ADR 完备、需求文件完备
2. 模型推断"治理层无缺口" → 输出 done
3. 未回到战略目标 G1 验收检查

Problem analysis: Scanning from the intermediate layer loses the causal chain of "why this task matters." The starting point for auto-iterate's determination must be "whether the L1 acceptance KPI has been achieved," not "whether the intermediate-layer documents are complete." This is consistent with the direction of plan-next's goal-tree traversal — the root node is the acceptance criterion for the strategic objective.

❌ Error: In cron mode, continuously outputting done without alerting the user

1. /loop 1m /auto-iterate 注册 cron
2. 首次 plan-next 返回空 → 输出 done（错误）
3. cron 不读信号，继续每分钟触发，陷入 done 空转
4. 用户不知 cron 在空转

Problem analysis: Violates the constraint in the "Interaction mode with /loop" section. In cron mode, signals are ignored, and the skill must proactively alert the user to switch to dynamic /loop or suggest CronDelete.

Example

Example 1: Happy path — task breakdown succeeds

Scenario: plan-next routes to task breakdown for design D1b; first call; sub-skill succeeds.

Execution process：

Internal call to plan-next → topic: "break down executable tasks for design D1b", recommended skill:/breakdown-tasks, priority: low
Stall detection: first call, no historical fingerprint → continue
Human gate:breakdown-tasks non-creative → continue
Execute /breakdown-tasks 基于设计 D1b 拆解任务清单，参考 D1a 拆解粒度
Post-execution verification: rerun plan-next → the D1b card disappears, "what to do now" still has 1 item → advance

IterationStepReport：

## 这次自动推进做了什么

- **做了什么**：为 D1b 设计拆解了可执行任务清单
- **为什么要修**：design/D1b.md 已完成但对应任务清单文件缺失，无法进入执行阶段
- **改了什么**：
  - 修改前：tasks/ 目录下无 D1b 相关任务文件
  - 修改后：新增 tasks/D1b-tasks.md，含拆解后的可执行任务列表
- **结果**：成功 ✅
- **下一步**：继续自动推进（还有 1 条待处理项）
- _（内部）继续信号：advance_

Example 2: Human gate blocks — strategic objective pending definition

Scenario: plan-next routes design-strategic-goals(strategic creative type); auto-iterate must pause.

Execution process：

Internal call to plan-next → recommended skill:/design-strategic-goals, priority: important
Stall detection: first call → continue
Human gate:design-strategic-goals belongs to the strategic creative type → trigger pause

IterationStepReport：

## 这次自动推进做了什么

- **做了什么**：识别到战略目标文档缺失，需要补充
- **为什么要修**：docs/strategic-goals.md 不存在，无法推进后续路线图规划
- **结果**：需要你来决定 ⚠️
- **下一步**：需要你决定：战略目标内容需要人工判断与确认，请手动运行 `/design-strategic-goals`，完成后重新运行 `/auto-iterate`
- _（内部）继续信号：blocked_

Example 3 (edge case): Stall detection — sub-skill did not advance

Scenario: last time /analyze-requirements after execution the requirements document was not successfully written; this time plan-next routes to the same card.

Execution process：

Internal call to plan-next → fingerprint = "analyze requirements for roadmap node N1||strategic objective 'Objective A' → roadmap 'N1' currently: requirements layer"
Stall detection: same as last fingerprint → trigger stalled

IterationStepReport：

## 这次自动推进做了什么

- **做了什么**：尝试分析路线图 N1 的需求，但检测到连续 2 次未推进
- **为什么要修**：requirements/N1-requirements.md 在上次 `/analyze-requirements` 后未成功写入
- **结果**：出错了 ❌
- **下一步**：卡住了：同一任务连续 2 次无进展，可能原因：需求文件未写入、路径配置错误、或技能执行有误。建议手动运行 `/analyze-requirements` 并检查输出文件是否存在，解决后重新运行 /auto-iterate
- _（内部）继续信号：stalled_

AI reconstruction instructions

Problem 1: Multiple routes were executed

Identification sign: IterationStepReport contains multiple 调用技能 entries
Correction steps：
1. Identify the multiple routes that were executed
2. Keep only the 1 with the highest priority (紧急 > 重要 > 缓）
3. Re-output IterationStepReport, reporting only 1 action

Problem 2: Missing continuation_signal

Identification sign: IterationStepReport is missing the internal continuation signal field, or its value is not within the five-value enum
Correction steps：
1. Check the execution result and fill it in according to the following logic:
  - Sub-skill succeeded + route still exists → advance
  - Sub-skill succeeded + no route → done
  - Manual gate triggered → blocked
  - Fingerprint duplicated → stalled
  - Sub-skill failed → error
2. In 下一步 field, explain the reason

Issue 3: Reporting advance after skipping post-execution verification

Identification sign: The report shows advance but plan-next was not rerun to confirm
Correction steps：
1. Rerun /plan-next, check whether the target card has disappeared
2. If it has disappeared → confirm advance is correct
3. If it still exists → update the stuck count; if it occurs for the 2nd time → correct it to stalled

Issue 4: Judging completion status on your own and skipping step 6

Identification sign：下一步 The field contains self-assessment language such as "the governance layer is fully ready", "all currently executable ... have been created", "belongs to the developer execution layer", and there is no record of rerunning plan-next in step 6
Correction steps：
1. Rerun /plan-next
2. If "what to do now" is empty → done is correct, and the report does not need modification
3. If "what to do now" contains only blocked entries → correct it to the internal continuation signal blocked，下一步 explain the blocking reason
4. If "what to do now" still has executable entries → correct it to the internal continuation signal advance, continue to the next step

Appendix: Output contract

YAML schema（formal）

type: object
required:
  - report_title
  - action_taken
  - result
  - next_step
  - continuation_signal
properties:
  report_title:
    type: string
    const: "这次自动推进做了什么"
  action_taken:
    type: string
    minLength: 1
    description: 用文件名或功能名描述本次唯一执行动作
  why_fix:
    type: string
    minLength: 1
    description: 可选；首次创建文件可省略
  changes:
    type: object
    required: [before, after]
    properties:
      before:
        type: string
      after:
        type: string
  result:
    type: string
    enum: ["成功 ✅", "需要你来决定 ⚠️", "出错了 ❌"]
  next_step:
    type: string
    minLength: 1
  continuation_signal:
    type: string
    enum: [advance, done, blocked, stalled, error]
  execution_trace:
    type: object
    required: [selected_skill, post_check_plan_next_rerun]
    properties:
      selected_skill:
        type: string
        pattern: "^/[a-z0-9-]+"
      post_check_plan_next_rerun:
        type: boolean
        const: true
additionalProperties: false

JSON schema（formal）

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "IterationStepReport",
  "type": "object",
  "required": [
    "report_title",
    "action_taken",
    "result",
    "next_step",
    "continuation_signal",
    "execution_trace"
  ],
  "properties": {
    "report_title": {
      "type": "string",
      "const": "这次自动推进做了什么"
    },
    "action_taken": {
      "type": "string",
      "minLength": 1
    },
    "why_fix": {
      "type": "string",
      "minLength": 1
    },
    "changes": {
      "type": "object",
      "required": ["before", "after"],
      "properties": {
        "before": { "type": "string" },
        "after": { "type": "string" }
      },
      "additionalProperties": false
    },
    "result": {
      "type": "string",
      "enum": ["成功 ✅", "需要你来决定 ⚠️", "出错了 ❌"]
    },
    "next_step": {
      "type": "string",
      "minLength": 1
    },
    "continuation_signal": {
      "type": "string",
      "enum": ["advance", "done", "blocked", "stalled", "error"]
    },
    "execution_trace": {
      "type": "object",
      "required": ["selected_skill", "post_check_plan_next_rerun"],
      "properties": {
        "selected_skill": {
          "type": "string",
          "pattern": "^/[a-z0-9-]+"
        },
        "post_check_plan_next_rerun": {
          "type": "boolean",
          "const": true
        }
      },
      "additionalProperties": false
    }
  },
  "additionalProperties": false
}

Self-check

Completeness of required sections

All 11 required sections exist (Purpose / Core Objective / Scope Boundaries / Usage Scenarios / Behavior / Inputs and Outputs / Limitations / Anti-Patterns / Examples / AI Refactoring Instructions / Self-check)
The Semantic Role positioning block exists, explaining the difference from plan-next / loop / automate-repair

Core success criteria

Each invocation executes exactly 1 action
Stuck detection: fingerprint duplication 2 times within a session triggers stalled
Post-execution verification: rerun plan-next to confirm the target card disappears
Did step 6 actually rerun plan-next? (Do not accept "inferring governance completion on your own" as a substitute; self-assessment language must not appear in the notes)
Manual gate: strategic creative skills trigger blocked; cards with the "to be executed" label trigger blocked
Each output is a valid continuation_signal (advance / done / blocked / stalled / error)
The "governance context" output by plan-next contains the current status of the L1 acceptance KPI? If not, treat plan-next as non-compliant, output error, and prompt for escalation
done The signal simultaneously satisfies three conditions: plan-next output "what to do now" is empty + KPI has been achieved + no "to be executed" cards
In cron mode (fixed-interval), the first report includes a suggestion to switch to dynamic /loop
stalled When it occurs for the 2nd consecutive time, it includes the prompt "immediately CronDelete "

Quality gate check

Hard Boundaries use MUST / MUST NOT and include verification methods
Anti-Patterns ≥ 2 comparative examples (actually 4)
Examples ≥ 2, of which ≥ 1 is a boundary scenario (Example 3 covers stuck detection)
AI Refactoring Instructions cover ≥ 2 error modes (actually 3)

Acceptance test

After execution is complete, does the IterationStepReport clearly state what was executed, what the result was, and whether the next step is to continue or requires human intervention? If not → rewrite the IterationStepReport.

About this skill

Purpose

Core Objectives

Scope Boundaries

Use cases

Behavior

Step 0: Pre-check

Step 1: Call plan-next

Step 2: Parse routing

Step 3: Stuck detection

Step 4: Manual gate

Step 5: Execute

Step 6: Post-execution verification

Step 7: Output IterationStepReport

Interaction mode with /loop (important)

Input and Output

Input

Output: IterationStepReport

continuation_signal semantics

Limitations

Hard Boundaries

Skill Boundaries

Anti-patterns

✅ Correct: single-step execution + post-verification + continue signal

❌ Wrong: executing two routes at once

❌ Wrong: bypassing the human gate

❌ Wrong: skipping post-execution verification and directly reporting advance

❌ Wrong: judging "governance complete" on its own instead of rerunning plan-next in step 6

❌ Wrong: treating 战略目标 status=approved as acceptance achieved → outputting done

❌ Error: Inferring done from intermediate-layer (M5/task) status

❌ Error: In cron mode, continuously outputting done without alerting the user

Example

Example 1: Happy path — task breakdown succeeds

Example 2: Human gate blocks — strategic objective pending definition

Example 3 (edge case): Stall detection — sub-skill did not advance

AI reconstruction instructions

Problem 1: Multiple routes were executed

Problem 2: Missing continuation_signal

Issue 3: Reporting advance after skipping post-execution verification

Issue 4: Judging completion status on your own and skipping step 6

Appendix: Output contract

YAML schema（formal）

JSON schema（formal）

Self-check

Completeness of required sections

Core success criteria

Quality gate check

Acceptance test

❌ Wrong: treating `战略目标 status=approved` as acceptance achieved → outputting done