deep-plan-ingest

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Deep Plan Ingest

深度规划内容提取

A plan document is a snapshot; it goes stale the day implementation starts. This skill moves the verified knowledge out of the plan and into the three files future agents actually load — so the research paid for once keeps paying.

Target	Purpose	Audience
`AGENTS.md`	Operating rules + ground-truth facts for agents working in this repo	Every future agent session
`docs/ARCHITECTURE.md`	Component map, data flow, framework mechanisms — with citations	Agents and humans exploring the system
`ROADMAP.md`	The phased roadmap with live phase status	Anyone asking "what's next?"

规划文档是一个快照；从实施启动的那天起，它就会过时。本技能将已验证的知识从规划文档中迁移到未来Agent实际加载的三个文件中——让一次投入的研究持续发挥价值。

目标文件	用途	受众
`AGENTS.md`	供本仓库中工作的Agent使用的操作规则 + 基准事实	未来所有Agent会话
`docs/ARCHITECTURE.md`	带引用的组件图、数据流、框架机制	探索系统的Agent与人类
`ROADMAP.md`	含实时阶段状态的阶段性路线图	所有询问“下一步是什么？”的人

The Prime Directive (inherited from deep-plan)

核心准则（继承自deep-plan）

Only VERIFIED knowledge gets ingested. Stale evidence is re-verified or dropped.

Claims tagged
```
UNVERIFIED
```
in the plan never enter
```
AGENTS.md
```
or
```
docs/ARCHITECTURE.md
```
. They may appear in
```
ROADMAP.md
```
only as explicit open questions.
```
CORRECTED
```
entries win over the beliefs they corrected — ingest the correction, never the original mistake.
A citation is copied along with its claim. A fact that loses its
```
file:line
```
/ vendor path / doc URL on the way over was not ingested, it was laundered.

仅提取VERIFIED（已验证）的知识。过时的内容需重新验证或舍弃。

规划中标记为
```
UNVERIFIED
```
（未验证）的内容绝不会进入
```
AGENTS.md
```
或
```
docs/ARCHITECTURE.md
```
。它们仅能作为明确的开放性问题出现在
```
ROADMAP.md
```
中。
```
CORRECTED
```
（已修正）的条目优先于其修正的原有内容——提取修正后的内容，绝不保留原始错误。
引用需与对应内容一同复制。若某个事实在迁移过程中丢失了
```
file:line
```
（文件:行号）/供应商路径/文档URL，则该事实未被提取，而是被“清洗”掉了。

Progress checklist

进度检查清单

Copy this into your response and check items off:

Ingest Progress:
- [ ] Step 1: Locate the plan and confirm targets
- [ ] Step 2: Staleness check — re-verify claims touched since the plan was written
- [ ] Step 3: Ingest AGENTS.md (merge, don't clobber)
- [ ] Step 4: Ingest docs/ARCHITECTURE.md (merge, don't clobber)
- [ ] Step 5: Ingest ROADMAP.md with phase status
- [ ] Step 6: Report — written / updated / skipped / dropped-as-stale

将以下内容复制到你的回复中并勾选完成项：

提取进度：
- [ ] 步骤1：定位规划文档并确认目标文件
- [ ] 步骤2：时效性检查——重新验证规划撰写后被修改过的内容
- [ ] 步骤3：提取内容到AGENTS.md（合并，不覆盖）
- [ ] 步骤4：提取内容到docs/ARCHITECTURE.md（合并，不覆盖）
- [ ] 步骤5：提取内容到ROADMAP.md并更新阶段状态
- [ ] 步骤6：提交报告——已编写/已更新/已跳过/因过时舍弃

Step 1 — Locate the plan and confirm targets

步骤1 — 定位规划文档并确认目标文件

Plan path: use the path given with the invocation (
```
$ARGUMENTS
```
on platforms that substitute it); else try
```
docs/PLAN.md
```
, then
```
docs/*PLAN*.md
```
. If several candidates exist, ask ONE question with your recommended pick.
Target detection: if the repo already uses
```
CLAUDE.md
```
or
```
AGENT.md
```
as its agent-instructions file, merge into that file instead of creating a parallel
```
AGENTS.md
```
. Never create a second competing instructions file.
Read the entire plan before writing anything.

规划文档路径：使用调用时提供的路径（支持参数替换的平台使用
```
$ARGUMENTS
```
）；否则尝试
```
docs/PLAN.md
```
，再尝试
```
docs/*PLAN*.md
```
。若存在多个候选文件，仅提出一个问题并给出你的推荐选项。
目标文件检测：若仓库已使用
```
CLAUDE.md
```
或
```
AGENT.md
```
作为Agent指令文件，则合并到该文件中，而非创建并行的
```
AGENTS.md
```
。绝不要创建第二个相互竞争的指令文件。
在写入任何内容前，通读整个规划文档。

Step 2 — Staleness check

步骤2 — 时效性检查

The plan was true when written; the repo has moved. Before ingesting:

```
git log --oneline <plan-file-mtime-or-date>..HEAD
```
— list commits since the plan (or since its "Generated on" date).
For every plan claim whose cited file appears in those commits, re-open the file and re-verify before carrying the claim over.
Claims that no longer hold are dropped and listed in the Step 6 report — never silently ingested.

Skip nothing here: ingesting a stale "fact" into

AGENTS.md

poisons every future session that loads it.

规划文档撰写时是准确的，但仓库内容已更新。提取内容前：

执行
```
git log --oneline <plan-file-mtime-or-date>..HEAD
```
——列出规划文档撰写后（或其“生成日期”之后）的所有提交记录。
对于规划中引用的文件出现在上述提交记录中的每一项内容，重新打开文件并重新验证后再进行迁移。
不再成立的内容将被舍弃并在步骤6的报告中列出——绝不悄悄提取。

此处不可跳过任何步骤：将过时的“事实”提取到

AGENTS.md

中会污染所有未来加载该文件的Agent会话。

Step 3–5 — Write the three files

步骤3-5 — 写入三个文件

Follow the exact structures in the references (read the one you need before writing that file):

```
AGENTS.md
```
→ references/agents-template.md
```
docs/ARCHITECTURE.md
```
→ references/architecture-template.md
```
ROADMAP.md
```
→ references/roadmap-template.md

Merge policy (applies to all three):

If the target does not exist, create it from the template.
If it exists, update it section by section: refresh sections this skill owns, and leave human-authored sections untouched. When ownership is unclear, append under a clearly marked section rather than editing prose you did not write.
Keep it lean.
```
AGENTS.md
```
is loaded into context every session — hard budget under 150 lines; move depth to
```
docs/ARCHITECTURE.md
```
and link to it. Prefer deleting an outdated line over adding a clarifying one.
No duplication between the three files: rules live in
```
AGENTS.md
```
, structure in
```
ARCHITECTURE.md
```
, sequencing in
```
ROADMAP.md
```
. Cross-link instead of copying.

Before reporting, run the mechanical checks — commands, not judgment calls; all must pass:

```
wc -l
```
on the AGENTS-type file → 150 or less; over budget = cut lines until it passes, never present-and-apologize.
Repo metadata (remotes, hosting, author) must match
```
git remote -v
```
/ git config output exactly — never construct a GitHub/GitLab URL from the repo's name; no remote = say so.
Every claim carried over kept its citation — grep the outputs for bare assertions that lost their
```
file:line
```
on the way.

遵循参考文档中的精确结构（写入对应文件前先阅读参考文档）：

```
AGENTS.md
```
→ references/agents-template.md
```
docs/ARCHITECTURE.md
```
→ references/architecture-template.md
```
ROADMAP.md
```
→ references/roadmap-template.md

合并规则（适用于所有三个文件）：

若目标文件不存在，则根据模板创建。
若目标文件已存在，则逐节更新：刷新本技能负责的章节，保留人类撰写的章节不变。若所有权不明确，则在清晰标记的章节下追加内容，而非编辑非你撰写的文本。
保持内容精简。
```
AGENTS.md
```
会在每次会话中加载到上下文——严格控制在150行以内；将详细内容移至
```
docs/ARCHITECTURE.md
```
并添加链接。优先删除过时内容，而非添加解释性内容。
三个文件间无重复内容：规则存于
```
AGENTS.md
```
，结构存于
```
ARCHITECTURE.md
```
，时序安排存于
```
ROADMAP.md
```
。通过交叉链接替代复制。

提交报告前，执行机械检查——通过命令而非主观判断；所有检查必须通过：

对AGENTS类文件执行
```
wc -l
```
命令 → 行数不超过150；若超出，则删减内容直至符合要求，绝不提交后再道歉。
仓库元数据（远程仓库、托管平台、作者）必须与
```
git remote -v
```
/git config的输出完全一致——绝不要根据仓库名称构建GitHub/GitLab URL；若无远程仓库，则如实说明。
所有迁移的内容均保留引用——通过grep检查输出内容，确保没有丢失
```
file:line
```
的无引用断言。

Step 6 — Report

步骤6 — 提交报告

End with a concise report:

Written/updated: each file with a one-line summary of what changed.
Dropped as stale: each plan claim that failed re-verification, with the commit or file that invalidated it.
Skipped:
```
UNVERIFIED
```
items excluded (count is enough).
Suggested follow-up: if many claims were stale, recommend re-running deep-plan for the affected area instead of patching the docs by hand.

最后提交一份简洁的报告：

已编写/已更新： 每个文件的变更内容用一句话总结。
因过时舍弃： 每个未通过重新验证的规划内容，附上使其失效的提交记录或文件。
已跳过： 被排除的
```
UNVERIFIED
```
（未验证）项（仅需统计数量）。
建议后续操作： 若大量内容过时，建议针对受影响区域重新运行deep-plan，而非手动修补文档。