From eb0d565e63d78b2e3a24f72d04981d3df62e1427 Mon Sep 17 00:00:00 2001
From: LoopX Agent <337587101+loopx-agent@users.noreply.github.com>
Date: Sat, 7 Nov 2026 03:22:16 +0800
Subject: [PATCH] docs: explain what to evaluate with LoopX alongside native
 Goal

Signed-off-by: LoopX Agent <337587101+loopx-agent@users.noreply.github.com>
---
 docs/guides/first-bugfix-loop.md       | 42 ++++++++++++++++++++++++++
 docs/guides/first-bugfix-loop.zh-CN.md | 37 +++++++++++++++++++++++
 2 files changed, 79 insertions(+)

diff --git a/docs/guides/first-bugfix-loop.md b/docs/guides/first-bugfix-loop.md
index 82028406c3..305113a0cb 100644
--- a/docs/guides/first-bugfix-loop.md
+++ b/docs/guides/first-bugfix-loop.md
@@ -9,6 +9,9 @@ inspect the patch, and make a local commit. No remote repository is required.
 **Finish steps 1–4 first.** Steps 5–6 are optional extensions for recurring
 bug fixes or refactoring in your own repository.
 
+Already use Codex `/goal`? See [what to evaluate with LoopX](#when-to-use-loopx)
+before adding it to a longer job.
+
 You need Python 3.11+ for the exercise. To use LoopX, also install Node.js
 22.22.3+ (24 LTS recommended), LoopX, and an agent host you already use. The
 tests themselves need no third-party packages or model access.
@@ -224,6 +227,45 @@ provides a complete task prompt and an example of what to compare before and
 after. Continue from the same Goal and its recorded evidence; each refactoring
 still needs a reviewable result and a stopping rule.
 
+<a id="when-to-use-loopx"></a>
+
+## If I already use Codex `/goal`, what should I try with LoopX?
+
+[OpenAI documents native Goal](https://developers.openai.com/cookbook/examples/codex/using_goals_in_codex)
+as durable state within a thread, with completion, budget and continuation
+controls. LoopX adds a project work record of accepted requirements, Todos,
+ownership, decisions and evidence that connected sessions and Agents can share.
+In Codex CLI, it still uses native `/goal` to drive continuation, as described
+in step 2. You can start with one Agent; adding another host or Agent requires
+its own setup. Check whether the retained work actually informs later actions.
+
+Choose a real job where you need to inspect that continuity:
+
+| Job | A concrete change during the work | What to inspect before accepting it |
+| --- | --- | --- |
+| Keep finding and fixing bugs in one module | You add a compatibility constraint after several repairs | The existing LoopX Goal retains the new constraint, earlier valid requirements and evidence; the next repair follows them |
+| Work through a PR review queue | A PR changes its head, or one merge needs your decision | Findings identify the reviewed revision; that decision holds the affected merge while independent authorized reviews can continue |
+| Supervise a longer research effort | An experiment fails or new evidence challenges the current approach | Failed and uncertain results remain available; the Agent explains why it changes or continues the approach, and records the resulting outcome and cost |
+
+For the recurring job in step 5, try a natural follow-up in the **same Goal**:
+
+```text
+For future repairs, leave each patch uncommitted until I review it.
+Keep the other accepted requirements and existing results. Before continuing,
+show where this correction is retained and which next action changes.
+```
+
+Inspect the retained work and the next actual patch. An acknowledgement or a
+Todo being marked done does not show that the correction was followed. You
+should not need to maintain a second goal document yourself.
+
+The creator's [reported uses](https://x.com/huangruiteng/status/2118539848235803121)
+include research supervision, PR review, product iteration and refactoring.
+These are use cases, not a controlled performance comparison. If your current
+Goal workflow already delivers what you need, keep it. LoopX adds state,
+validation and continuation work with their own costs; this small exercise
+does not establish a quality or efficiency advantage over native Goal.
+
 ## Setup effort, ongoing cost, and limits
 
 The copied exercise needs two files and the Python standard library. LoopX
diff --git a/docs/guides/first-bugfix-loop.zh-CN.md b/docs/guides/first-bugfix-loop.zh-CN.md
index 5047379a4e..9fad95c8d5 100644
--- a/docs/guides/first-bugfix-loop.zh-CN.md
+++ b/docs/guides/first-bugfix-loop.zh-CN.md
@@ -7,6 +7,8 @@
 
 **先完成第 1–4 步。** 第 5–6 步是用于真实仓库的持续查错与重构扩展，跑通练习后再读。
 
+已经在用 Codex `/goal`？给长任务加上 LoopX 前，先看[值得比较什么](#when-to-use-loopx)。
+
 练习需要 Python 3.11+。使用 LoopX 还需要 Node.js 22.22.3+（推荐 24 LTS）、
 LoopX，以及你已经在用的 Agent 宿主。练习测试只用 Python 标准库，不需要模型。
 
@@ -203,6 +205,41 @@ Goal、任务归属和待评审 PR，确认写入范围、测试命令、当前
 这是选题示例，不代表你的仓库已经存在该问题。英文完整示例见
 [长程编程任务指南](long-running-coding-agents.md#example-keep-improving-repository-quality)。
 
+<a id="when-to-use-loopx"></a>
+
+## 已经在用 Codex `/goal`，可以拿什么任务试 LoopX？
+
+[OpenAI 官方指南](https://developers.openai.com/cookbook/examples/codex/using_goals_in_codex)
+说明，原生 Goal 已有线程内的持久状态、完成条件、预算和续跑控制。LoopX 增加的是
+项目层的工作记录：已接受要求、Todo、归属、决定和证据，供已接入的会话与 Agent
+共用。如第 2 步所述，它在 Codex CLI 中仍用原生 `/goal` 驱动续跑。可以从一个
+Agent 开始；增加宿主或 Agent 需要各自接入。要检查的是，留下的工作记录有没有
+真正影响后续行动。
+
+选一个确实需要检查这种连续性的任务：
+
+| 任务 | 中途发生的具体变化 | 验收前看什么 |
+| --- | --- | --- |
+| 持续检查并修复一个模块的 bug | 修了几轮后，你补充一条兼容要求 | 既有 LoopX Goal 留下新要求、仍有效的旧要求和证据，下一次修复实际遵守它们 |
+| 持续处理 PR 评审队列 | PR 换了 head，或其中一次合并需要你决定 | 结论对应实际评审版本；只等待受影响的合并，其它已授权的独立评审仍可继续 |
+| 看护一项长程研究 | 实验失败，或新证据挑战了当前方向 | 失败和未知结果仍可查；Agent 说明为什么换方向或继续，并记录后续成果与成本 |
+
+如果已经启用第 5 步的持续任务，可以在**同一个 Goal**里接着说：
+
+```text
+后面的修复都先留着补丁，等我 review 后再提交。
+其它已接受的要求和已有结果保留。继续前，说明这条修订留在了哪里，
+下一步具体改了什么。
+```
+
+接着检查保留的工作状态和下一份实际补丁。回复“收到”或勾选 Todo，都不能说明
+修订已被执行；你也不应该需要自己再维护一份目标文档。
+
+作者[公开报告的用法](https://x.com/huangruiteng/status/2118539848235803121)包括研究看护、
+PR 评审、产品迭代和持续重构。这些是使用场景，不是受控性能对照。如果现有 Goal
+工作流已经能交付你需要的结果，可以继续沿用。LoopX 的状态维护、验证与续跑也有
+成本；这个小练习不能证明它比原生 Goal 效果更好或效率更高。
+
 ## 准备成本、持续费用与适用范围
 
 复制练习只需两个文件和 Python 标准库。LoopX 另外需要一次 CLI/技能安装和宿主激活。