project-discover

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

project-discover（一次指令全量 Discover 总控：地图层 + 权威入口 + 证据链）

project-discover (Full Discover Master Control with One Command: Map Layer + Authoritative Entry + Evidence Chain)

概览

Overview

本技能用于把“已有代码的存量项目”在一次指令内尽可能完整地逆向沉淀为

.aisdlc/project/

项目级 SSOT（长期资产），以支撑后续 Spec Pack 的 AI 辅助开发尽量不再重复跑 Discover。

Discover 的核心不是“把代码翻译成文档”，而是把以下三件事立起来（并且能被持续维护）：

地图层：先有可导航的索引骨架（索引只导航）
权威入口：每个 P0 模块有单页模块 SSOT（模块页是权威）
证据链：每个关键结论都能指向仓库内可定位的证据入口（Evidence）或结构化缺口（Evidence Gaps）

开始时宣布：「我正在使用 project-discover 技能执行存量项目 Discover（逆向）并建立

.aisdlc/project/

项目级 SSOT。」

This skill is used to reverse and as completely as possible within one command consolidate "legacy projects with existing code" into

.aisdlc/project/

project-level SSOT (long-term asset), to support subsequent AI-assisted development of Spec Pack avoid running Discover repeatedly as much as possible.

The core of Discover is not "translating code into documentation", but establishing the following three items (and enabling sustainable maintenance):

Map Layer: First build a navigable index skeleton (index is only used for navigation)
Authoritative Entry: Each P0 module has a single-page module SSOT (module page is authoritative)
Evidence Chain: Each key conclusion can point to a locatable evidence entry (Evidence) or structured gap (Evidence Gaps) in the repository

Announce at startup: "I am using the project-discover skill to perform Discover (reverse engineering) on the legacy project and establish the

.aisdlc/project/

project-level SSOT."

目标（一次指令的交付物）

Objectives (Deliverables of one command execution)

在单次运行结束时，默认应至少产出并自洽以下内容（允许“证据不足→结构化缺口”降级，但不允许脑补）：

Level-0 / Memory（北极星）

```
.aisdlc/project/memory/structure.md
```
```
.aisdlc/project/memory/tech.md
```
```
.aisdlc/project/memory/product.md
```
```
.aisdlc/project/memory/glossary.md
```

Level-1 / 地图索引（只导航 + 进度面板）
- ```
.aisdlc/project/components/index.md
```
  （含 direct-only 依赖图）
- ```
.aisdlc/project/products/index.md
```
  （建议；可按证据决定是否创建）
模块页（权威入口，优先 P0，尽可能多）
- ```
.aisdlc/project/components/{module}.md
```
  ：对每个识别到的 P0 模块尽可能创建并填充到 DoD；对 P1 模块尽可能创建（允许一段契约降级到 Evidence Gaps）；P2 默认仅索引占位
Ops（高 ROI；有证据则创建）
- ```
.aisdlc/project/ops/index.md
```
  （以及 monitoring/rollback/runbook 等入口页，能链接到真实平台/配置/脚本时再加）
治理能力（可持续）
- DoD/勾选门禁规则能落地执行（“模块完成”只看模块页达标）
- 增量 Discover（Delta Discover）与 stale（过期）机制在文档里有入口与写法约束（至少体现在模块页 frontmatter 与 products/ops/memory 的 Evidence Gaps）

At the end of a single run, the following content should be produced and self-consistent by default (downgrade to "insufficient evidence → structured gap" is allowed, but guessing out of thin air is not allowed):

Level-0 / Memory (North Star)

```
.aisdlc/project/memory/structure.md
```
```
.aisdlc/project/memory/tech.md
```
```
.aisdlc/project/memory/product.md
```
```
.aisdlc/project/memory/glossary.md
```

Level-1 / Map Index (navigation only + progress panel)
- ```
.aisdlc/project/components/index.md
```
  (including direct-only dependency graph)
- ```
.aisdlc/project/products/index.md
```
  (recommended; decide whether to create based on evidence)
Module Pages (authoritative entry, prioritize P0, cover as many as possible)
- ```
.aisdlc/project/components/{module}.md
```
  : Create and fill to DoD as much as possible for each identified P0 module; create as much as possible for P1 modules (allow downgrading to Evidence Gaps with a section of contract); P2 modules only have index placeholders by default
Ops (high ROI; create if evidence exists)
- ```
.aisdlc/project/ops/index.md
```
  (as well as entry pages for monitoring/rollback/runbook, etc., add only when they can link to real platforms/configurations/scripts)
Governance Capability (sustainable)
- DoD/check gatekeeping rules can be implemented ("module completion" only depends on whether the module page meets the standards)
- Delta Discover and stale mechanism have entry and writing constraints in the documentation (at least reflected in the module page frontmatter and Evidence Gaps of products/ops/memory)

何时使用 / 不使用

When to use / not to use

使用时机
- 你要为存量项目建立/补齐
```
.aisdlc/project/
```
  （memory / components / products / ops / nfr）
- 你发现“入口在哪里、边界是什么、契约在哪”总是靠猜，导致 AI 或新人反复问同样的问题
- 你担心索引与细节双写、字段大全、TODO 散落、契约不权威造成维护爆炸
- 你要做增量 Discover（Delta Discover）来对抗知识过期（stale）
不要用在
- 你在做需求级 Spec Pack 的
```
requirements/
```
  /
```
design/
```
  /
```
implementation/
```
  （那是 spec-* 技能链路）
- 你要写“字段级数据字典”作为合规/对账/KPI 口径治理的独立体系（这不是 Discover 的默认目标）

Usage Scenarios
- You need to establish/complement
```
.aisdlc/project/
```
  (memory / components / products / ops / nfr) for legacy projects
- You find that "where is the entry, what is the boundary, where is the contract" are always guessed, leading to repeated questions from AI or new team members
- You worry about duplicate writing of indexes and details, full field lists, scattered TODOs, and unauthoritative contracts causing maintenance explosion
- You need to perform Delta Discover to combat knowledge stale
Do NOT use for
- You are working on
```
requirements/
```
  /
```
design/
```
  /
```
implementation/
```
  of requirement-level Spec Pack (that belongs to the spec-* skill chain)
- You need to write "field-level data dictionary" as an independent system for compliance/reconciliation/KPI caliber governance (this is not the default goal of Discover)

核心硬规则（出现任一条：停止并纠正）

Core Hard Rules (if any occurs: stop and correct)

禁止产出
.aisdlc/project/contracts/**

API/Data 契约必须合并进模块页：

.aisdlc/project/components/{module}.md

的固定段落

## API Contract

## Data Contract

索引只导航
- ```
.aisdlc/project/components/index.md
```
  与
```
.aisdlc/project/products/index.md
```
  不得写不变量/字段/详细流程/“待补”
模块页单页 SSOT（权威入口）
- P0 模块必须存在模块页，并包含固定标题（锚点稳定）：
```
## TL;DR
```
  、
```
## API Contract
```
  、
```
## Data Contract
```
  、
```
## Evidence（证据入口）
```
  、
```
## Evidence Gaps（缺口清单）
```
不脑补：缺证据就写 Evidence Gaps
- 不允许用“待补/未发现/TODO”散落正文；缺口必须进入
```
## Evidence Gaps（缺口清单）
```
  ，结构化写清楚“缺什么/去哪找/影响”
先 Scope 止损
- Discover 最大风险是覆盖面失控：必须先做 P0/P1/P2；P0 先做三件套（模块页 + 契约段落 + 证据链）再扩
Products 收敛到 <= 6（默认）
- 业务模块地图是“业务语义锚点”，不是功能清单大全；过多会让地图失效

Prohibit generating
.aisdlc/project/contracts/**

API/Data contracts must be merged into the module page: fixed sections
```
## API Contract
```
/
```
## Data Contract
```
in
```
.aisdlc/project/components/{module}.md
```

Index is only for navigation
- ```
.aisdlc/project/components/index.md
```
  and
```
.aisdlc/project/products/index.md
```
  must not contain invariants/fields/detailed processes/"to be filled"
Module page is single-page SSOT (authoritative entry)
- P0 modules must have a module page, and contain fixed titles (stable anchors):
```
## TL;DR
```
  ,
```
## API Contract
```
  ,
```
## Data Contract
```
  ,
```
## Evidence
```
  ,
```
## Evidence Gaps
```
No guessing: write Evidence Gaps when evidence is missing
- Scattered "to be filled/not found/TODO" in the text is not allowed; all gaps must be included in
```
## Evidence Gaps
```
  , clearly write "what is missing/where to find/impact" in a structured way
Scope control first to stop loss
- The biggest risk of Discover is out-of-control coverage: must prioritize P0/P1/P2 first; complete the three-piece set (module page + contract section + evidence chain) for P0 before expanding
Products converge to <= 6 (default)
- Business module map is "business semantic anchors", not a full list of functions; too many entries will invalidate the map

一次指令执行策略（总控编排，不反复运行）

One Command Execution Strategy (master orchestration, no repeated runs)

本技能是“总控编排器”。执行时不要把工作拆成多轮让用户反复触发；而是在本次运行中完成：

先建地图骨架（Memory + Index）
再并行补模块页（P0 尽可能多，P1 尽可能覆盖，P2 只占位）
并行收敛 Products 与补 Ops（有证据就落盘；缺证据写缺口）
最后做 DoD/一致性门禁回填（哪些模块能打勾、哪些不行，原因在模块页 Evidence Gaps）

为确保输出可维护，Discover 拆成 4 个可交付域（对应现有子技能），但应在一次运行中完成并汇总：

你现在要做什么	用哪个子技能	主要输出位置
盘点“可作为证据的入口”，并做 P0/P1/P2 止损	`project-discover-preflight-scope`	`.aisdlc/project/components/index.md` （priority/owner/code_entry 等）+ 证据入口清单落位到后续 memory/ops
建立 Level-0 北极星与 Level-1 索引骨架（地图层）	`project-discover-memory-index`	`.aisdlc/project/memory/*` + `.aisdlc/project/components/index.md` + `.aisdlc/project/products/index.md`
逐个把 P0 模块做成“单页模块 SSOT + 契约段落 + 证据链”	`project-discover-modules-contracts`	`.aisdlc/project/components/{module}.md`
收敛 Products、补 Ops 入口、做 DoD 勾选门禁、建立增量维护	`project-discover-products-ops-dod`	`.aisdlc/project/products/` + `.aisdlc/project/ops/` + DoD/Delta/过期规则

默认策略（尽可能丰富）：不把 P0 限制在 1–3 个；在预算允许范围内，尽可能为所有识别到的 P0 都创建模块页并填充到可用门槛。若仓库过大导致无法全覆盖：仍然要完成 memory + index，并为未覆盖的 P0/P1 留下“可追溯的 Evidence Gaps 与候选证据位置”，而不是空白或脑补。

This skill is a "master orchestrator". Do not split the work into multiple rounds for users to trigger repeatedly; complete all tasks in this run:

Build map skeleton first (Memory + Index)
Fill module pages in parallel (cover as many P0 as possible, cover P1 as much as possible, only placeholders for P2)
Converge Products and supplement Ops in parallel (persist if evidence exists; write gaps if evidence is missing)
Finally complete DoD/consistency gate backfilling (which modules can be checked, which cannot, and the reasons are recorded in the module page Evidence Gaps)

To ensure maintainable output, Discover is split into 4 deliverable domains (corresponding to existing sub-skills), but should be completed and aggregated in one run:

What you need to do now	Which sub-skill to use	Main output location
Inventory of "evidence-qualified entries" and implement P0/P1/P2 scope control	`project-discover-preflight-scope`	`.aisdlc/project/components/index.md` (priority/owner/code_entry, etc.) + evidence entry list placed in subsequent memory/ops
Establish Level-0 North Star and Level-1 index skeleton (map layer)	`project-discover-memory-index`	`.aisdlc/project/memory/*` + `.aisdlc/project/components/index.md` + `.aisdlc/project/products/index.md`
Build "single-page module SSOT + contract section + evidence chain" for each P0 module	`project-discover-modules-contracts`	`.aisdlc/project/components/{module}.md`
Converge Products, supplement Ops entries, implement DoD check gate, establish incremental maintenance mechanism	`project-discover-products-ops-dod`	`.aisdlc/project/products/` + `.aisdlc/project/ops/` + DoD/Delta/stale rules

Default strategy (as rich as possible): Do not limit P0 to 1-3; within the budget, create module pages for all identified P0 modules and fill them to the usable threshold as much as possible. If the repository is too large to cover fully: still complete memory + index, and leave "traceable Evidence Gaps and candidate evidence locations" for uncovered P0/P1 modules, instead of leaving blanks or guessing.

并行化建议（可选，但高 ROI）

Parallelization Suggestions (optional, high ROI)

当你面对 2+ 个互不依赖的任务域时，建议使用并行子代理（参考

dispatching-parallel-agents

）。本技能的目标明确允许并鼓励把 Modules 与 Products/Ops 拆给独立子代理并行处理。

Preflight 并行：分别扫描 run/test/ci/contract/ops 的证据入口
Modules 并行：每个 P0 模块一个子代理（互不改同一模块页；不要让多个代理改同一个
```
components/{module}.md
```
）
Products 并行：1 个子代理负责 products 收敛与
```
products/*
```
（只写入口级摘要，避免字段/流程大全）
Ops 并行：1 个子代理负责 ops 入口与证据（监控/告警、日志入口、回滚入口），只要能给出真实入口就落盘，否则写 Evidence Gaps

When facing 2+ independent task domains, it is recommended to use parallel sub-agents (refer to

dispatching-parallel-agents

). The goal of this skill explicitly allows and encourages splitting Modules and Products/Ops to independent sub-agents for parallel processing.

Preflight parallel: Scan evidence entries of run/test/ci/contract/ops separately
Modules parallel: One sub-agent per P0 module (do not modify the same module page; do not let multiple agents modify the same
```
components/{module}.md
```
)
Products parallel: 1 sub-agent responsible for products convergence and
```
products/*
```
(only write entry-level summaries, avoid full lists of fields/processes)
Ops parallel: 1 sub-agent responsible for ops entries and evidence (monitoring/alarm, log entry, rollback entry), persist only when real entries can be provided, otherwise write Evidence Gaps

并行分工硬约束（防冲突/防漂移）

Hard Constraints for Parallel Division of Labor (anti-conflict/anti-drift)

总控（你）唯一可写范围：

```
.aisdlc/project/memory/*
```
```
.aisdlc/project/components/index.md
```
```
.aisdlc/project/products/index.md
```
DoD 勾选回填与一致性校验（最终汇总）

模块子代理写入范围：仅写自己负责的
```
.aisdlc/project/components/{module}.md
```
products 子代理写入范围：仅写
```
.aisdlc/project/products/*
```
（不改 components/index）
ops 子代理写入范围：仅写
```
.aisdlc/project/ops/*
```

Writable scope only for master controller (you):
- ```
.aisdlc/project/memory/*
```
- ```
.aisdlc/project/components/index.md
```
- ```
.aisdlc/project/products/index.md
```
- DoD check backfilling and consistency verification (final aggregation)
Writable scope for module sub-agents: Only write the
```
.aisdlc/project/components/{module}.md
```
they are responsible for
Writable scope for products sub-agent: Only write
```
.aisdlc/project/products/*
```
(do not modify components/index)
Writable scope for ops sub-agent: Only write
```
.aisdlc/project/ops/*
```

子代理输入（必须给清楚，避免“自创结构”）

Sub-agent Input (must be clear to avoid "self-created structure")

给每个子代理的任务描述必须包含：

该代理允许写入的路径白名单

该页的固定标题/锚点要求（尤其模块页的

## TL;DR / ## API Contract / ## Data Contract / ## Evidence / ## Evidence Gaps

）

“缺证据就写 Evidence Gaps，不许脑补”的硬规则
要求输出“权威入口链接 + 不变量摘要 + 证据入口”的最小粒度（文件/类/job/命令）

The task description for each sub-agent must include:

Allowed write path whitelist for the agent

Fixed title/anchor requirements for the page (especially

## TL;DR / ## API Contract / ## Data Contract / ## Evidence / ## Evidence Gaps

for module pages)

Hard rule of "Write Evidence Gaps when evidence is missing, no guessing allowed"
Minimum granularity requirement of output "authoritative entry link + invariant summary + evidence entry" (file/class/job/command)

常见借口与反制（来自基线压测）

Common Excuses and Countermeasures (from baseline stress test)

这些借口来自“无技能约束”的基线压测原话。写入这里的目的，是为了在时间/权威/沉没成本压力下，仍能守住 Discover 的硬规则。

借口（原话风格）	最常见违规	必须的反制动作
“先把文档写全，结构搭满，细节后面再对代码补。”	索引写细节；TODO 散落；脑补契约	先做 Scope + Index 骨架；所有细节下沉模块页；缺证据写 Evidence Gaps，不写推测
“索引太干会没人看，写点说明不用点进去就懂。”	索引变成细节堆（双写）	索引只导航：只放链接/复选框/owner/code_entry；细节只在模块页
“没有 Swagger/OpenAPI，先按经验写一版契约，标‘待核对’。”	契约不权威；字段大全；错口径被放大	模块页契约段落只写：权威入口（文件/生成命令）+ 不变量摘要 + 证据入口；缺权威入口→Evidence Gaps
“时间紧，先把不确定的用‘待补/未发现’标出来，表示诚实。”	“待补”散落导致永远补不完	所有缺口集中到 `## Evidence Gaps` ，并写：缺口/期望粒度/候选证据位置/影响
“已经写了一半，再改成索引只导航要大改；先交差。”	沉没成本驱动的结构性违规	删除/移动：把索引细节挪到模块页；索引回归导航；不能因为沉没成本违反结构规则
“字段列全一点查起来方便。”	字段大全（维护爆炸）	字段级细节只通过权威入口链接（schema/DDL/model）；在 project 层只写不变量摘要
“怎么跑/怎么部署是刚需，写在项目级入口最合适。”	一次性交付细节污染项目级	项目级只写入口链接与最小护栏；详细操作手册归 ops 体系或外部平台链接

These excuses are original quotes from baseline stress tests without skill constraints. The purpose of writing them here is to adhere to the hard rules of Discover even under pressure of time/authority/sunk cost.

Excuse (original style)	Most common violation	Required countermeasure
"Write the full documentation first, build the structure, and fill in the details against the code later."	Index writes details; scattered TODOs; guessed contracts	Build Scope + Index skeleton first; all details sink to module pages; write Evidence Gaps for missing evidence, no speculation
"The index is too dry for people to read, write some explanations so you don't need to click in."	Index becomes a pile of details (duplicate writing)	Index is only for navigation: only put links/checkboxes/owner/code_entry; details are only in module pages
"There is no Swagger/OpenAPI, write a version of the contract based on experience first, mark 'to be checked'."	Unauthorized contracts; full field lists; wrong caliber amplified	Contract section of module page only writes: authoritative entry (file/generation command) + invariant summary + evidence entry; missing authoritative entry → Evidence Gaps
"Time is tight, mark uncertain content with 'to be filled/not found' first to show honesty."	Scattered "to be filled" leads to never being completed	All gaps are concentrated in `## Evidence Gaps` , and write: gap/expected granularity/candidate evidence location/impact
"Half of it is already written, it will take a lot of modification to change to index-only navigation; submit it first."	Structural violation driven by sunk cost	Delete/move: move index details to module pages; index returns to navigation function; do not violate structural rules due to sunk cost
"It is more convenient to check if all fields are listed."	Full field list (maintenance explosion)	Field-level details are only linked through authoritative entries (schema/DDL/model); only write invariant summaries at the project layer
"How to run/how to deploy is a rigid requirement, it is most appropriate to write it in the project-level entry."	One-time delivery details pollute the project level	Project level only writes entry links and minimum guardrails; detailed operation manuals belong to the ops system or external platform links

红旗清单（出现任一条：停止并纠正）

Red Flag List (if any occurs: stop and correct)

在

.aisdlc/project/components/index.md

或

products/index.md

里写了不变量/字段/详细流程

出现
```
.aisdlc/project/contracts/**
```
出现大量“TODO/待补/未发现”散落正文（未汇总到
```
Evidence Gaps
```
）
P0 模块打了
```
- [x]
```
，但模块页缺少固定标题或缺少权威入口/不变量/证据入口
为了“写全”而把 Products 写成 20+ 个模块的功能清单

Invariants/fields/detailed processes are written in
```
.aisdlc/project/components/index.md
```
or
```
products/index.md
```
```
.aisdlc/project/contracts/**
```
appears
A large number of scattered "TODO/to be filled/not found" in the text (not aggregated into
```
Evidence Gaps
```
)
P0 module is marked with
```
- [x]
```
, but the module page lacks fixed titles or lacks authoritative entry/invariants/evidence entry
Products are written as a function list of 20+ modules for the sake of "completeness"

一致性与完成门禁（本次运行结束前必须做）

Consistency and Completion Gate (must be completed before the end of this run)

在一次指令的末尾，总控必须完成以下校验与回填，确保知识库“能用且不自相矛盾”：

索引只导航校验：
```
components/index.md
```
/
```
products/index.md
```
不出现不变量/字段/详细流程/“待补/未发现/TODO”
模块页达标校验（决定能否打勾）：
- P0：模块页存在；固定标题齐全；frontmatter 元数据齐全；API/Data 契约段落存在“权威入口 + 3–7 条不变量 + 证据入口”；若存在缺口必须写到 Evidence Gaps，且该模块不得勾选
- P1：允许 API 或 Data 其一缺失，但必须 Evidence Gaps 结构化记录缺口与影响
- P2：默认不勾选
SSOT 门禁：索引中的勾选只是反映模块页是否达标；不得“先勾选再补内容”
依赖图维护：
```
components/index.md
```
的 Mermaid 依赖图只画 direct-only，并标注交互方式（API/Event/DB）
Products 收敛：默认 <= 6；无法收敛必须给出原因与治理建议入口（不要把它写成大目录）

At the end of one command, the master controller must complete the following verification and backfilling to ensure the knowledge base is "usable and not self-contradictory":

Index navigation only verification:
```
components/index.md
```
/
```
products/index.md
```
do not contain invariants/fields/detailed processes/"to be filled/not found/TODO"
Module page compliance verification (determines whether it can be checked):
- P0: Module page exists; fixed titles are complete; frontmatter metadata is complete; API/Data contract sections have "authoritative entry + 3-7 invariants + evidence entry"; if there are gaps, they must be written in Evidence Gaps, and the module must not be checked
- P1: Allow either API or Data to be missing, but gaps and impacts must be recorded in Evidence Gaps in a structured way
- P2: Not checked by default
SSOT gate: Checks in the index only reflect whether the module page meets the standards; "check first then fill content" is not allowed
Dependency graph maintenance: Mermaid dependency graph in
```
components/index.md
```
only draws direct-only, and marks interaction methods (API/Event/DB)
Products convergence: <= 6 by default; if convergence is not possible, reasons and governance suggestion entries must be provided (do not write it as a large directory)

Quick reference（高频速查）

Quick reference (high frequency check)

最小可用交付（MVP）

Minimum Viable Deliverable (MVP)

```
.aisdlc/project/memory/structure.md
```
：怎么跑/怎么验/怎么发布的入口（可追溯）
```
.aisdlc/project/components/index.md
```
：模块地图（只导航）+ 复选框进度 + 依赖图
1–3 个 P0 模块页：
```
.aisdlc/project/components/{module}.md
```
（含 TL;DR + API/Data 契约段落 + Evidence/Evidence Gaps）

```
.aisdlc/project/memory/structure.md
```
: Traceable entries for how to run/how to test/how to release
```
.aisdlc/project/components/index.md
```
: Module map (navigation only) + checkbox progress + dependency graph
1-3 P0 module pages:
```
.aisdlc/project/components/{module}.md
```
(including TL;DR + API/Data contract sections + Evidence/Evidence Gaps)

DoD 的一句话

DoD in one sentence

模块是否“完成”，只由模块页内容是否达标决定；索引勾选只是反映这一事实。

Whether a module is "completed" is only determined by whether the content of the module page meets the standards; the check in the index only reflects this fact.

常见错误

Common Mistakes

把 Discover 做成“字段级字典工程”（维护爆炸）
先写细节再补地图（导致双写与断链）
看到缺口就脑补（下游会把猜测当事实）
把需求级一次性交付细节合并进项目级（项目级变成垃圾场）

Make Discover into "field-level dictionary engineering" (maintenance explosion)
Write details first then supplement the map (leading to duplicate writing and broken links)
Guess when seeing gaps (downstream will treat speculation as fact)
Merge requirement-level one-time delivery details into the project level (project level becomes a garbage dump)