code-to-catalog

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Code to Catalog

代码转目录文档

Turn a codebase into EventCatalog documentation through a guided, evidence-based interview. Works for two situations:

No catalog yet — document an unfamiliar or undocumented codebase from scratch.
Existing catalog — reconcile the catalog with the current code (add new resources, flag drift, surface stale entries).

This skill does not write catalog files itself. It produces a plan file (

.catalog-plan.md

) that captures the agreed architectural model, then hands off to the

catalog-documentation-creator

skill to generate the actual documentation.

通过引导式、基于证据的交互式流程将代码库转换为EventCatalog文档。适用于两种场景：

尚无目录文档 —— 从零开始为不熟悉或未归档的代码库生成文档。
已有目录文档 —— 协调目录文档与当前代码（添加新资源、标记差异、显示过时条目）。

本技能不会直接编写目录文件。它会生成一个计划文件（

.catalog-plan.md

），记录已确认的架构模型，然后移交至

catalog-documentation-creator

技能来生成实际文档。

How this skill works

本技能的工作方式

The skill runs in six phases. Follow them in order — later phases depend on earlier ones.

Locate & inventory — find the code directory and any existing catalog
Discovery scan — read the code, form a hypothesis
Reconcile with existing catalog — categorize findings as
```
new
```
/
```
update
```
/
```
unchanged
```
/
```
investigate
```
Tiered grilling — interview the user on structural decisions only
Produce the plan file — write
```
.catalog-plan.md
```
, get approval
Handoff — ask whether to generate the catalog now or stop at the plan

该技能分为六个阶段运行，请按顺序执行——后续阶段依赖于前期阶段的结果。

定位与盘点 —— 找到代码目录及任何现有目录文档
发现扫描 —— 读取代码，形成假设
与现有目录文档协调 —— 将发现结果分类为
```
new
```
（新增）/
```
update
```
（更新）/
```
unchanged
```
（未变更）/
```
investigate
```
（待调查）
分层确认 —— 仅就架构决策与用户进行交互式确认
生成计划文件 —— 写入
```
.catalog-plan.md
```
，获取用户批准
移交处理 —— 询问用户是立即生成目录文档还是仅保留计划文件

Conversational style (applies throughout)

交互风格（全程适用）

One question at a time. Never batch questions. The user answers, then move on.
Always provide a recommended answer. Every question includes what you think is true, with evidence (file path + line number). The user confirms, corrects, or overrides.
Cite the code. When you present a finding, point at the file where you saw it — e.g.,
```
src/orders/events.ts:42
```
. The user should be able to verify without trusting you.
Be honest about uncertainty. If the code does not tell you whether something is an event or a command, say so. Do not guess silently.
Surface conflicts, do not pick silently. When catalog and code disagree, the user decides. Never overwrite without confirmation.
Respect the user's time. Grilling is tiered on purpose — structural decisions only. Do not grill on per-resource fields (summaries, owners, schemas).
No catalog deletions. Resources in the catalog that you cannot find in code are flagged
```
investigate
```
— never removed automatically.

一次只提一个问题。绝不批量提问。用户回答后再继续。
始终提供建议答案。每个问题都要包含你认为正确的答案，并附上证据（文件路径+行号）。用户可确认、修正或覆盖建议。
引用代码。展示发现结果时，指明你看到该内容的文件——例如
```
src/orders/events.ts:42
```
。用户无需信任你，即可自行验证。
坦诚表达不确定性。如果代码无法告知你某个内容是事件还是命令，请如实说明。不要暗自猜测。
暴露冲突，不要暗自处理。当目录文档与代码不一致时，由用户决定。未经确认绝不能覆盖现有内容。
尊重用户时间。分层确认是有意设计的——仅关注架构决策。不要对每个资源的字段（摘要、所有者、模式）进行确认。
不删除目录资源。在目录文档中存在但在代码中未找到的资源会被标记为
```
investigate
```
（待调查）——绝不自动删除。

Phase 1: Locate & inventory

阶段1：定位与盘点

Find the codebase

找到代码库

Ask the user: "Which code directory should I analyze?"

Verify the directory exists and looks like a code project (has a

package.json

pom.xml

go.mod

Cargo.toml

pyproject.toml

, source directories, etc.). If the directory is ambiguous (e.g., a monorepo), confirm the scope: the whole repo, or a specific subdirectory.

询问用户：“我应该分析哪个代码目录？”

验证该目录是否存在且看起来是一个代码项目（包含

package.json

、

pom.xml

、

go.mod

、

Cargo.toml

、

pyproject.toml

、源码目录等）。如果目录不明确（例如单体仓库），确认范围：是整个仓库，还是特定子目录。

Find the catalog

找到目录文档

Ask the user: "Do you already have an EventCatalog project, or do you want to start fresh?"

If they already have one:

Ask for the path. Verify it's an EventCatalog project by checking for
```
eventcatalog.config.js
```
or the standard directories (
```
services/
```
,
```
events/
```
,
```
commands/
```
,
```
queries/
```
,
```
domains/
```
,
```
channels/
```
,
```
flows/
```
).
Build an inventory of what already exists. If the EventCatalog MCP server is connected, use
```
getResources
```
,
```
getResource
```
,
```
findResourcesByOwner
```
. Otherwise read the filesystem directly and parse the frontmatter of each
```
index.md
```
/
```
index.mdx
```
.
Record for each resource:
```
id
```
,
```
name
```
,
```
version
```
,
```
type
```
,
```
summary
```
, and (for services)
```
sends
```
/
```
receives
```
relationships.
Note the catalog's conventions: nested (
```
domains/X/services/Y/events/Z
```
) vs flat, PascalCase vs kebab-case IDs, existing owners, schema formats in use.

If they do not have a catalog:

That's fine. Note that scaffolding will happen at handoff time through

catalog-documentation-creator

(which runs

npx @eventcatalog/create-eventcatalog@latest <name> --empty

Phase 3 (reconciliation) becomes a no-op — everything discovered will be
```
new
```
.

询问用户：“你已经有EventCatalog项目了，还是想要从头开始创建？”

如果已有EventCatalog项目：

询问路径。通过检查
```
eventcatalog.config.js
```
或标准目录（
```
services/
```
、
```
events/
```
、
```
commands/
```
、
```
queries/
```
、
```
domains/
```
、
```
channels/
```
、
```
flows/
```
）来验证它是否为EventCatalog项目。
盘点现有资源。如果已连接EventCatalog MCP服务器，使用
```
getResources
```
、
```
getResource
```
、
```
findResourcesByOwner
```
接口。否则直接读取文件系统并解析每个
```
index.md
```
/
```
index.mdx
```
的前置元数据。
记录每个资源的以下信息：
```
id
```
、
```
name
```
、
```
version
```
、
```
type
```
、
```
summary
```
，以及（针对服务）
```
sends
```
/
```
receives
```
关系。
记录目录文档的约定：嵌套结构（
```
domains/X/services/Y/events/Z
```
）还是扁平结构、ID采用PascalCase还是kebab-case、现有所有者、使用的模式格式。

如果没有EventCatalog项目：

没问题。记录在移交阶段将通过
```
catalog-documentation-creator
```
完成脚手架搭建（该技能会运行
```
npx @eventcatalog/create-eventcatalog@latest <name> --empty
```
）。
阶段3（协调）将无需执行——所有发现的内容都会被标记为
```
new
```
（新增）。

Phase 2: Discovery scan

阶段2：发现扫描

Read the codebase and form a hypothesis. Do not show the user your findings yet — you'll present them as questions in Phase 4, backed by evidence.

For detailed detection heuristics per language/framework (Node.js, Python, Go, Java, .NET), see

references/discovery.md

. Read that file now if the codebase uses a stack you need guidance on.

Detect:

读取代码库并形成假设。不要向用户展示你的发现结果——你会在阶段4将其作为问题提出，并附上证据。

关于各语言/框架（Node.js、Python、Go、Java、.NET）的详细检测启发式规则，请查看

references/discovery.md

。如果代码库使用了你需要指导的技术栈，请立即阅读该文件。

检测内容：

Project structure

项目结构

Monorepo vs single service (look for workspace configs:
```
pnpm-workspace.yaml
```
,
```
package.json
```
with
```
workspaces
```
,
```
nx.json
```
,
```
turbo.json
```
,
```
lerna.json
```
, multiple top-level service directories with their own manifests).
Language and framework per service.
Build/deploy units (Dockerfiles, Helm charts,
```
serverless.yml
```
,
```
cdk
```
stacks, k8s manifests).

单体仓库还是单一服务（查找工作区配置：
```
pnpm-workspace.yaml
```
、包含
```
workspaces
```
的
```
package.json
```
、
```
nx.json
```
、
```
turbo.json
```
、
```
lerna.json
```
、多个顶级服务目录且各有自己的清单文件）。
每个服务使用的语言和框架。
构建/部署单元（Dockerfile、Helm charts、
```
serverless.yml
```
、
```
cdk
```
栈、k8s清单）。

Service boundaries

服务边界

A service is an independently-deployable, independently-ownable unit. Signals:

Separate package with its own manifest
Separate Dockerfile / deployment config
Its own entrypoint (
```
main.ts
```
,
```
main.go
```
,
```
app.py
```
, etc.)
Consumed by others over a network boundary (HTTP, message bus)

When in doubt, mark as a candidate and grill the user in Phase 4.

服务是可独立部署、可独立维护的单元。判断信号：

独立的包，有自己的清单文件
独立的Dockerfile/部署配置
自己的入口文件（
```
main.ts
```
、
```
main.go
```
、
```
app.py
```
等）
通过网络边界被其他服务调用（HTTP、消息总线）

如有疑问，标记为候选服务，并在阶段4与用户确认。

Messages (events, commands, queries)

消息（事件、命令、查询）

Candidates come from:

Naming patterns —
```
*Created
```
,
```
*Placed
```
,
```
*Updated
```
,
```
*Deleted
```
(likely events);
```
Place*
```
,
```
Create*
```
,
```
Cancel*
```
,
```
Process*
```
(likely commands);
```
Get*
```
,
```
Find*
```
,
```
List*
```
(likely queries).
Message bus clients — Kafka (
```
kafkajs
```
,
```
confluent-kafka
```
,
```
sarama
```
), RabbitMQ (
```
amqplib
```
,
```
pika
```
), NATS, AWS SNS/SQS/EventBridge, GCP PubSub, Azure Service Bus.
Schema files — JSON Schema (
```
.schema.json
```
), Avro (
```
.avsc
```
), Protobuf (
```
.proto
```
). These are strong signals of a message contract.
DTO / type definitions — especially if they look like payloads (flat, data-only, named after a domain event).

Classify each candidate as event, command, or query based on evidence:

Event: past tense, published to a topic/exchange, multiple consumers possible, no direct reply expected.
Command: imperative, sent to one specific handler, expects to be processed.
Query: read-only, expects a response.

If evidence is ambiguous (common), mark it as uncertain and grill in Phase 4 — do not silently pick.

候选消息来自：

命名模式 ——
```
*Created
```
、
```
*Placed
```
、
```
*Updated
```
、
```
*Deleted
```
（可能是事件）；
```
Place*
```
、
```
Create*
```
、
```
Cancel*
```
、
```
Process*
```
（可能是命令）；
```
Get*
```
、
```
Find*
```
、
```
List*
```
（可能是查询）。
消息总线客户端 —— Kafka（
```
kafkajs
```
、
```
confluent-kafka
```
、
```
sarama
```
）、RabbitMQ（
```
amqplib
```
、
```
pika
```
）、NATS、AWS SNS/SQS/EventBridge、GCP PubSub、Azure Service Bus。
模式文件 —— JSON Schema（
```
.schema.json
```
）、Avro（
```
.avsc
```
）、Protobuf（
```
.proto
```
）。这些是消息契约的强烈信号。
DTO/类型定义 —— 尤其是看起来像负载的定义（扁平结构、仅含数据、以领域事件命名）。

根据证据将每个候选消息分类为事件、命令或查询：

事件：过去式，发布到主题/交换器，可能有多个消费者，不期望直接回复。
命令：祈使语气，发送给特定处理程序，期望被处理。
查询：只读，期望得到响应。

如果证据不明确（常见情况），标记为不确定，并在阶段4与用户确认——不要暗自选择分类。

Channels

通道

Anywhere messages flow through named infrastructure:

Kafka topics (string literals passed to
```
producer.send({ topic: '...' })
```
)
RabbitMQ queues/exchanges
SNS topics, SQS queues
HTTP endpoints for query services (
```
GET /users/:id
```
)

消息流经的命名基础设施：

Kafka主题（传递给
```
producer.send({ topic: '...' })
```
的字符串字面量）
RabbitMQ队列/交换器
SNS主题、SQS队列
查询服务的HTTP端点（
```
GET /users/:id
```
）

Domains (candidates)

领域（候选）

Strong signals:

Top-level folder grouping (
```
src/orders/
```
,
```
src/payments/
```
,
```
src/shipping/
```
)
Bounded-context hints in READMEs, module docs
Package namespaces (
```
com.company.orders.*
```
)
Ownership files (
```
CODEOWNERS
```
,
```
.codeowners
```
)

Do not guess domains with low confidence. If unclear, propose "single domain = whole codebase" and let the user split in Phase 4.

强烈信号：

顶级文件夹分组（
```
src/orders/
```
、
```
src/payments/
```
、
```
src/shipping/
```
）
README、模块文档中的限界上下文提示
包命名空间（
```
com.company.orders.*
```
）
所有权文件（
```
CODEOWNERS
```
、
```
.codeowners
```
）

不要在低置信度下猜测领域。如果不明确，建议“单一领域 = 整个代码库”，让用户在阶段4进行拆分。

Containers

容器

Databases, caches, queues referenced in config, env vars, or client instantiation:

Postgres / MySQL / SQLite / Mongo / DynamoDB / Cassandra
Redis / Memcached
S3 buckets, GCS buckets

配置、环境变量或客户端实例化中引用的数据库、缓存、队列：

Postgres / MySQL / SQLite / Mongo / DynamoDB / Cassandra
Redis / Memcached
S3存储桶、GCS存储桶

Output of Phase 2

阶段2输出

An internal draft map:

domains:
  - name: <candidate>
    confidence: high|medium|low
    services: [...]
services:
  - name: <candidate>
    path: <dir>
    sends: [...]
    receives: [...]
    channels: [...]
    containers: [...]
messages:
  - name: <candidate>
    classification: event|command|query|uncertain
    evidence: <file:line>
    producer: <service>
    consumer: <service or unknown>
channels: [...]
containers: [...]

Hold this map internally. You'll use it to drive Phase 3 and Phase 4.

内部草稿映射：

domains:
  - name: <candidate>
    confidence: high|medium|low
    services: [...]
services:
  - name: <candidate>
    path: <dir>
    sends: [...]
    receives: [...]
    channels: [...]
    containers: [...]
messages:
  - name: <candidate>
    classification: event|command|query|uncertain
    evidence: <file:line>
    producer: <service>
    consumer: <service or unknown>
channels: [...]
containers: [...]

保留此映射供内部使用。你将用它驱动阶段3和阶段4。

Phase 3: Reconcile with existing catalog

阶段3：与现有目录文档协调

Skip this phase if there is no existing catalog — everything discovered is

new

For each item in the draft map, find the matching resource in the catalog inventory (match by ID, then by name, then by fuzzy match on name + type). Assign a status:

Status	Meaning
`unchanged`	Resource exists in catalog and matches what's in code. No user grilling needed.
`update`	Resource exists in catalog, but the code has drifted — new messages emitted, renamed fields, changed schemas, new sends/receives relationships.
`new`	Found in code, not in catalog. Candidate for a new resource.
`investigate`	Exists in catalog, not found in code. Possibly stale, possibly removed, possibly in a different repo. Never delete — only surface.

For

update

items, capture what specifically drifted:

```
OrderService
```
in catalog sends
```
[OrderPlaced]
```
, code also sends
```
OrderCancelled
```
→ drift: new send.
```
PaymentService
```
schema field renamed
```
amount_cents
```
→
```
amountCents
```
→ drift: schema change.

This categorization drives Phase 4 — you only grill on

update

, ambiguous

new

, and

investigate

items.

unchanged

resources are silent.

如果没有现有目录文档，跳过此阶段——所有发现的内容都会被标记为

new

（新增）。

对于草稿映射中的每个条目，在目录文档资源清单中找到匹配的资源（按ID匹配，然后按名称，最后按名称+类型模糊匹配）。分配状态：

状态	含义
`unchanged`	资源存在于目录文档中，且与代码中的内容一致。无需与用户确认。
`update`	资源存在于目录文档中，但代码已发生变化——新增了消息、字段重命名、模式变更、新增了发送/接收关系。
`new`	在代码中找到，但不存在于目录文档中。是新增资源的候选。
`investigate`	存在于目录文档中，但在代码中未找到。可能已过时、已移除，或位于其他仓库。绝不删除——仅标记出来。

对于

update

条目，记录具体的差异内容：

目录文档中的
```
OrderService
```
发送
```
[OrderPlaced]
```
，代码中还发送
```
OrderCancelled
```
→ 差异：新增发送消息。
```
PaymentService
```
的模式字段从
```
amount_cents
```
重命名为
```
amountCents
```
→ 差异：模式变更。

此分类将驱动阶段4——你只需就

update

、模糊的

new

和

investigate

条目与用户确认。

unchanged

资源无需处理。

Phase 4: Tiered grilling

阶段4：分层确认

Grill only on structural decisions. Per-resource details (summary text, owner names, schema fields, badge styles) are not your concern —

catalog-documentation-creator

handles them.

For the full question bank with recommended-answer templates, see

references/grilling.md

. Read it now.

Walk the topics in this order. Dependencies flow downward — resolve earlier topics before later ones.

仅就架构决策进行确认。每个资源的细节（摘要文本、所有者姓名、模式字段、徽章样式）不属于你的职责范围——这些由

catalog-documentation-creator

处理。

完整的问题库及建议答案模板，请查看

references/grilling.md

。请立即阅读该文件。

按以下顺序处理主题。依赖关系自上而下——先解决前面的主题，再处理后面的。

Topic 1: Domains & boundaries

主题1：领域与边界

Ask about domain groupings first, because service placement depends on it.

If you detected clear domain candidates: present each with its recommended services and ask the user to confirm.
If you detected none: propose "single domain for the whole codebase" and ask whether they want to split.
For any ambiguous service ("does
```
NotificationService
```
belong to
```
Orders
```
or its own
```
Notifications
```
domain?"), grill it.

首先询问领域分组，因为服务的归属取决于领域。

如果检测到明确的候选领域：展示每个领域及其推荐的服务，请求用户确认。
如果未检测到候选领域：建议“整个代码库为单一领域”，询问用户是否需要拆分。
对于任何模糊的服务（“
```
NotificationService
```
属于
```
Orders
```
领域还是独立的
```
Notifications
```
领域？”），与用户确认。

Topic 2: Service boundaries

主题2：服务边界

Confirm each service candidate. Present its evidence (path, entrypoint, Dockerfile).
For ambiguous cases ("this module could be its own service or part of another"), grill with a recommended answer.
Handle monorepo edge cases: is the shared
```
lib/
```
package a service? (Probably not — it's infrastructure.)

确认每个候选服务。展示其证据（路径、入口文件、Dockerfile）。
对于模糊情况（“这个模块可以是独立服务，也可以是另一个服务的一部分”），给出建议答案并与用户确认。
处理单体仓库的边缘情况：共享的
```
lib/
```
包是服务吗？（可能不是——它是基础设施。）

Topic 3: Message classification

主题3：消息分类

This is the most commonly-wrong call. Grill it hard.

For every message marked

uncertain

in discovery:

I found
OrderReceived
at
src/orders/handlers.ts:18
. It's consumed from a queue and there's no reply path, so I'd classify it as an event. Agree?

For messages with high-confidence classification, present them for quick bulk confirmation:

I identified these as events (based on past-tense naming + pub/sub pattern):
OrderPlaced
,
OrderCancelled
,
PaymentProcessed
. Any you'd reclassify?

这是最容易出错的判断，需要重点确认。

对于发现阶段标记为

uncertain

的每条消息：

我在
src/orders/handlers.ts:18
找到
OrderReceived
。它从队列中被消费，且没有回复路径，所以我将其分类为事件。你同意吗？

对于高置信度分类的消息，批量展示供用户快速确认：

根据过去式命名+发布/订阅模式，我将这些识别为事件：
OrderPlaced
、
OrderCancelled
、
PaymentProcessed
。你是否需要重新分类其中任何一个？

Topic 4: Drift reconciliation (only if existing catalog)

主题4：差异协调（仅适用于已有目录文档的情况）

For each

update

item:

Catalog says
PaymentService
sends
[PaymentProcessed]
. Code also emits
PaymentRefunded
at
src/payments/refund.ts:24
. Add
PaymentRefunded
to the service's sends? I'd say yes.

For each

investigate

item:

Catalog has
LegacyPaymentConfirmed
(event, v0.0.3). I could not find it in the code. It might live in another repo, or it might be removed. I'll flag it as
investigate
in the plan — the user can decide later. OK?

Do not propose deletions. Only surface.

对于每个

update

条目：

目录文档显示
PaymentService
发送
[PaymentProcessed]
。代码中还在
src/payments/refund.ts:24
处发送
PaymentRefunded
。是否要将
PaymentRefunded
添加到该服务的发送列表中？我建议添加。

对于每个

investigate

条目：

目录文档中有
LegacyPaymentConfirmed
（事件，v0.0.3）。我在代码中找不到它。它可能位于其他仓库，或者已被移除。我会在计划中将其标记为
investigate
（待调查），用户可稍后决定。可以吗？

不要建议删除，仅标记出来。

What NOT to grill on

无需确认的内容

Summary text for each resource
Owner / team assignments (unless discovered from
```
CODEOWNERS
```
and ambiguous)
Schema field-level detail
Badges, visual customizations
Flow diagrams (that's
```
flow-wizard
```
)

Those pass through to

catalog-documentation-creator

with sensible defaults.

每个资源的摘要文本
所有者/团队分配（除非从
```
CODEOWNERS
```
中发现且模糊不清）
模式字段级细节
徽章、视觉自定义
流程图（由
```
flow-wizard
```
处理）

这些内容会传递给

catalog-documentation-creator

，并使用合理的默认值。

Watch for interview fatigue

注意用户疲劳

If the grilling is running long (say, more than ~15 questions):

Summarize progress: "Here's what we've agreed so far — domains X, Y; services A, B, C; 12 messages classified."
Offer to pause at the plan file: "We can stop here, write the plan, and pick up details later."

如果确认过程耗时较长（例如超过约15个问题）：

总结进度：“以下是我们已达成的共识——领域X、Y；服务A、B、C；12条消息已分类。”
提供暂停选项：“我们可以在此停止，写入计划文件，稍后再处理细节。”

Phase 5: Produce the plan file

阶段5：生成计划文件

Write the plan to

.catalog-plan.md

. Default location: root of the code directory. Ask the user if they'd like it elsewhere.

Use this exact structure:

markdown

undefined

将计划写入

.catalog-plan.md

。默认位置：代码目录的根目录。询问用户是否需要保存到其他位置。

使用以下精确结构：

markdown

undefined

Catalog Plan

Generated: YYYY-MM-DD Codebase: /absolute/path/to/repo Existing catalog: /absolute/path/to/catalog (or "none — will be created")

Generated: YYYY-MM-DD Codebase: /absolute/path/to/repo Existing catalog: /absolute/path/to/catalog (或 "none — will be created")

Summary

<1–2 paragraph narrative of what was found and the agreed architectural model>

Domains

Orders (status: new)
- Services: OrderService, ShippingService
- Rationale: both deal with the order lifecycle; confirmed with user
Payments (status: unchanged)
- Services: PaymentService

Orders (status: new)
- Services: OrderService, ShippingService
- Rationale: both deal with the order lifecycle; confirmed with user
Payments (status: unchanged)
- Services: PaymentService

Services

OrderService (status: new)

Domain: Orders
Path in code: /services/orders
Receives: PlaceOrder (command)
Sends: OrderPlaced (event), OrderCancelled (event)
Channels: orders.commands, orders.events
Containers: orders-db (postgres)

Domain: Orders
Path in code: /services/orders
Receives: PlaceOrder (command)
Sends: OrderPlaced (event), OrderCancelled (event)
Channels: orders.commands, orders.events
Containers: orders-db (postgres)

PaymentService (status: update)

Domain: Payments
Path in code: /services/payments
Drift: code emits new PaymentRefunded event not in catalog
Sends (after update): PaymentProcessed, PaymentRefunded

Domain: Payments
Path in code: /services/payments
Drift: code emits new PaymentRefunded event not in catalog
Sends (after update): PaymentProcessed, PaymentRefunded

Messages

OrderPlaced (event, status: new) — emitted by OrderService via orders.events
OrderCancelled (event, status: new) — emitted by OrderService via orders.events
PlaceOrder (command, status: new) — handled by OrderService
PaymentRefunded (event, status: new) — emitted by PaymentService
LegacyPaymentConfirmed (event, status: investigate) — in catalog, not found in code

OrderPlaced (event, status: new) — emitted by OrderService via orders.events
OrderCancelled (event, status: new) — emitted by OrderService via orders.events
PlaceOrder (command, status: new) — handled by OrderService
PaymentRefunded (event, status: new) — emitted by PaymentService
LegacyPaymentConfirmed (event, status: investigate) — in catalog, not found in code

Channels

orders.events (Kafka topic, status: new)
orders.commands (Kafka topic, status: new)

orders.events (Kafka topic, status: new)
orders.commands (Kafka topic, status: new)

Containers

orders-db (postgres, status: new) — used by OrderService

orders-db (postgres, status: new) — used by OrderService

Open decisions / rationale

Classified
```
CancelOrder
```
as a command (user confirmed — it expects a handler)
Kept Shipping as a sub-area of Orders rather than splitting (user preference)
Flagged
```
LegacyPaymentConfirmed
```
for manual review — may live in a different repo

Classified
```
CancelOrder
```
as a command (user confirmed — it expects a handler)
Kept Shipping as a sub-area of Orders rather than splitting (user preference)
Flagged
```
LegacyPaymentConfirmed
```
for manual review — may live in a different repo

Next step

Run

catalog-documentation-creator

with this plan to generate resources marked

new

update


**Status values** (use exactly these): `new`, `update`, `unchanged`, `investigate`.

After writing, show the plan to the user and ask for explicit approval: **"Here's the plan. Does this match what we agreed? Anything to add, change, or remove before we proceed?"**

Loop on edits until the user approves.

Run

catalog-documentation-creator

with this plan to generate resources marked

new

update


**状态值**（严格使用这些值）：`new`、`update`、`unchanged`、`investigate`。

写入完成后，向用户展示计划并请求明确批准：**“这是生成的计划。它是否符合我们达成的共识？在继续之前，是否有需要添加、修改或删除的内容？”**

循环修改直到用户批准。

Phase 6: Handoff

阶段6：移交处理

Once the plan is approved, ask:

"Generate the catalog now, or stop here with just the plan?"

If generate now:

Invoke the
```
catalog-documentation-creator
```
skill, passing the plan file path.
Tell it to only create/update resources flagged
```
new
```
or
```
update
```
. Skip
```
unchanged
```
. Report
```
investigate
```
items to the user as a list — do not auto-handle.
If the user has no existing catalog,
```
catalog-documentation-creator
```
will scaffold one first.

If stop here:

Confirm the plan file location.
Tell the user how to resume: "When you're ready, run
```
catalog-documentation-creator
```
and point it at this plan file. It will generate the
```
new
```
and
```
update
```
resources."

计划获得批准后，询问：

“立即生成目录文档，还是仅保留计划文件？”

如果立即生成：

调用
```
catalog-documentation-creator
```
技能，传递计划文件路径。
告知该技能仅创建/更新标记为
```
new
```
或
```
update
```
的资源。跳过
```
unchanged
```
资源。将
```
investigate
```
条目列表报告给用户——不要自动处理。
如果用户没有现有目录文档，
```
catalog-documentation-creator
```
会先搭建脚手架。

如果仅保留计划：

确认计划文件的位置。
告知用户如何继续：“当你准备好时，运行
```
catalog-documentation-creator
```
并指向此计划文件。它将生成
```
new
```
和
```
update
```
的资源。”

After handoff

移交后

Let the user know:

Where the plan was saved.
(If generated) which resources were created/updated.
Which
```
investigate
```
items need manual review.
That they can run
```
flow-wizard
```
next if they want to document business flows across the catalog.

告知用户：

计划文件的保存位置。
（如果已生成）创建/更新了哪些资源。
哪些
```
investigate
```
条目需要手动审核。
如果想要记录目录文档中的业务流程，接下来可以运行
```
flow-wizard
```
。

Quality checklist

质量检查清单

Before finishing, verify:

The plan file exists at the agreed path.
Every domain, service, message, channel, and container has a status:
```
new
```
/
```
update
```
/
```
unchanged
```
/
```
investigate
```
.
Every
```
update
```
item lists what specifically drifted.
Every
```
investigate
```
item is flagged, not deleted.
Message classifications (event / command / query) were either confirmed by the user or clearly recommended with evidence.
Service-to-domain mapping is explicit for every service.
No per-resource grilling happened (summaries, owners, schemas — those are for
```
catalog-documentation-creator
```
).
If handing off,
```
catalog-documentation-creator
```
has the plan path and instructions to skip
```
unchanged
```
.

完成前，验证以下内容：

计划文件存在于约定的路径。
每个领域、服务、消息、通道和容器都有状态：
```
new
```
/
```
update
```
/
```
unchanged
```
/
```
investigate
```
。
每个
```
update
```
条目都列出了具体的差异内容。
每个
```
investigate
```
条目都已标记，未被删除。
消息分类（事件 / 命令 / 查询）要么已得到用户确认，要么已附上明确的证据建议。
每个服务的领域映射都已明确。
未对资源细节进行确认（摘要、所有者、模式——这些由
```
catalog-documentation-creator
```
处理）。
如果移交处理，
```
catalog-documentation-creator
```
已获得计划路径和跳过
```
unchanged
```
资源的指令。

code-to-catalog

Original

Translation

Code to Catalog

代码转目录文档

How this skill works

本技能的工作方式

Conversational style (applies throughout)

交互风格（全程适用）

Phase 1: Locate & inventory

阶段1：定位与盘点

Find the codebase

找到代码库

Find the catalog

找到目录文档

Phase 2: Discovery scan

阶段2：发现扫描

Project structure

项目结构

Service boundaries

服务边界

Messages (events, commands, queries)

消息（事件、命令、查询）

Channels

通道

Domains (candidates)

领域（候选）

Containers

容器

Output of Phase 2

阶段2输出

Phase 3: Reconcile with existing catalog

阶段3：与现有目录文档协调

Phase 4: Tiered grilling

阶段4：分层确认

Topic 1: Domains & boundaries

主题1：领域与边界

Topic 2: Service boundaries

主题2：服务边界

Topic 3: Message classification

主题3：消息分类

Topic 4: Drift reconciliation (only if existing catalog)

主题4：差异协调 （仅适用于已有目录文档的情况）

What NOT to grill on

无需确认的内容

Watch for interview fatigue

注意用户疲劳

Phase 5: Produce the plan file

阶段5：生成计划文件

Catalog Plan

Catalog Plan

Summary

Summary

Domains

Domains

Services

Services

OrderService (status: new)

OrderService (status: new)

PaymentService (status: update)

PaymentService (status: update)

Messages

Messages

Channels

Channels

Containers

Containers

Open decisions / rationale

Open decisions / rationale

Next step

Next step

Phase 6: Handoff

阶段6：移交处理

After handoff

移交后

Quality checklist

质量检查清单

主题4：差异协调（仅适用于已有目录文档的情况）