Back to Details

project-discover-preflight-scope

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

project-discover-preflight-scope（Step0+1：证据入口盘点 + 范围止损）

project-discover-preflight-scope (Step 0 + 1: Evidence Portal Inventory + Scope Risk Control)

概览

Overview

Preflight 的目标不是“把信息都写出来”，而是先把 可执行/可定位的证据入口 盘清楚；Scope 的目标是先把 覆盖面止损（P0/P1/P2），避免逆向工程变成“写全但不可维护”。
开始时宣布：「我正在使用 project-discover-preflight-scope 技能执行 Discover 的 Preflight 与 Scope 止损。」
The goal of Preflight is not to "write down all information", but to first sort out executable/locatable evidence portals; the goal of Scope is to first achieve coverage risk control (P0/P1/P2) to avoid reverse engineering turning into "comprehensive but unmaintainable documentation".
Announce at the start: "I am using the project-discover-preflight-scope skill to perform Preflight and Scope risk control for Discover."

输入 / 输出

Inputs / Outputs

  • 输入
    • 仓库根目录（代码、配置、依赖、CI/CD 配置）
    • 已有文档入口（README/Makefile/package.json/脚本等）
    • 可观测/运维入口（若存在：dashboard、告警、runbook、回滚）
  • 输出（落盘） 
    • .aisdlc/project/components/index.md
      ：模块清单 + P0/P1/P2 + code_entry + 复选框（此时不打勾）
    • .aisdlc/project/memory/structure.md
      ：将“如何跑/如何验/如何发布”的入口以链接形式固定（下一步子技能会正式写）
    • 注意：Preflight 的“证据入口清单”不需要单独建新文件，建议以“入口链接 + Evidence Gaps”逐步分散落位到 
      memory/*
      、模块页与 
      ops/*
  • Inputs
    • Repository root directory (code, configurations, dependencies, CI/CD configurations)
    • Existing documentation portals (README, Makefile, package.json, scripts, etc.)
    • Observability/Ops portals (if available: dashboard, alerts, runbook, rollback)
  • Outputs (persisted to disk) 
    • .aisdlc/project/components/index.md
      : Module list + P0/P1/P2 + code_entry + checkboxes (leave unchecked at this stage)
    • .aisdlc/project/memory/structure.md
      : Fix portals for "how to run/how to verify/how to release" in the form of links (sub-skills in the next step will formalize the content)
    • Note: The "evidence portal list" for Preflight does not require a separate new file, it is recommended to gradually disperse and place them in 
      memory/*
      , module pages and 
      ops/*
      in the form of "portal links + Evidence Gaps"

核心原则（Preflight）

Core Principles (Preflight)

  1. 优先可执行证据
    • 优先级：脚本/CI job/契约文件/迁移/生成命令 > 描述性文档 > 口述经验
  2. 只记录“入口”，不写推断
    • 你要写的是“从哪里进入、如何定位、证据在哪个文件/哪个 job”，不是“它应该怎么工作”
  3. 缺证据 = 结构化缺口
    • 写进后续文档的 
      ## Evidence Gaps
      ：缺口/期望粒度/候选位置/影响
  1. Prioritize executable evidence
    • Priority: Scripts/CI jobs/contract files/migration/generation commands > descriptive documentation > verbal experience
  2. Only record "portals", do not write inferences
    • You should write "where to enter, how to locate, which file/which job the evidence is in", not "how it should work"
  3. Missing evidence = structured gap
    • Write into the 
      ## Evidence Gaps
      section of subsequent documentation: gap/expected granularity/candidate location/impact

Preflight 最小清单（找证据入口）

Preflight Minimum Checklist (Find Evidence Portals)

只要能定位到具体文件或 job 名，就算有效入口；不要为了“写完整说明”而脑补。
  • 运行入口
    • 本地启动脚本/命令入口（例如：
      package.json scripts
      、
      Makefile
      、
      *.ps1/*.sh
      、docker-compose、k8s manifest）
    • 环境变量入口（例如：
      .env.example
      、配置模板、helm values）
  • 测试入口
    • 单测/集成测/E2E 的命令入口与目录入口
    • 覆盖率/门禁入口（例如：CI job、测试阈值配置）
  • CI/CD 入口
    • workflow/pipeline 文件位置 + 关键 job 名
    • 是否有 docs/link-check 等门禁（如果没有，后续可作为建议）
  • 契约/结构化事实入口
    • OpenAPI/Proto/GraphQL schema
    • DB migrations/DDL/ORM models
  • 可观测/运维入口（如有）
    • dashboard、告警、日志查询入口、runbook、回滚入口
As long as you can locate the specific file or job name, it is a valid portal; do not make assumptions for the sake of "writing complete instructions".
  • Runtime portals
    • Local startup script/command portals (e.g.: 
      package.json scripts
      , 
      Makefile
      , 
      *.ps1/*.sh
      , docker-compose, k8s manifest)
    • Environment variable portals (e.g.: 
      .env.example
      , configuration templates, helm values)
  • Test portals
    • Command portals and directory portals for unit tests/integration tests/E2E tests
    • Coverage/access control portals (e.g.: CI jobs, test threshold configurations)
  • CI/CD portals
    • workflow/pipeline file location + key job names
    • Whether there are access controls such as docs/link-check (if not, it can be used as a suggestion later)
  • Contract/structured fact portals
    • OpenAPI/Proto/GraphQL schema
    • DB migrations/DDL/ORM models
  • Observability/Ops portals (if available)
    • Dashboard, alerts, log query portals, runbook, rollback portals

Scope（P0/P1/P2）规则

Scope (P0/P1/P2) Rules

分级建议（与 Discover DoD 对齐）

Grading Recommendations (aligned with Discover DoD)

  • P0（必须）：高频变更、跨团队交界、对外集成多、事故/故障热点、合规风险高
  • P1（建议）：稳定但经常被引用/被问到/被依赖的基础能力
  • P2（按需）：低风险、低协作、生命周期短；先做索引占位，必要时再升级
  • P0 (Mandatory): High-frequency changes, cross-team boundaries, many external integrations, accident/failure hotspots, high compliance risks
  • P1 (Recommended): Stable but frequently referenced/asked/depended on basic capabilities
  • P2 (On-demand): Low risk, low collaboration, short lifecycle; create index placeholder first, upgrade when necessary

逆向深度止损（强约束）

Reverse Engineering Depth Risk Control (Strong Constraint)

  • P0：必须最终具备模块页 
    .aisdlc/project/components/{module}.md
    ，且页内同时包含 
    ## API Contract
    + 
    ## Data Contract
    + 
    ## Evidence
    （缺口只能写到 
    Evidence Gaps
    ，且此模块不得打勾）
  • P1：必须最终具备模块页；允许 API 或 Data 其中一段降级为 Evidence Gaps（记录缺口与影响）
  • P2：只在索引占位导航（默认不创建模块页）
  • P0: Must eventually have a module page 
    .aisdlc/project/components/{module}.md
    , and the page must contain 
    ## API Contract
    + 
    ## Data Contract
    + 
    ## Evidence
    at the same time (gaps can only be written in 
    Evidence Gaps
    , and this module cannot be checked)
  • P1: Must eventually have a module page; allow either API or Data section to be downgraded to Evidence Gaps (record gaps and impacts)
  • P2: Only place navigation in the index (module page is not created by default)

components/index.md
（Scope 落盘）最小模板

components/index.md
(Scope Persistence) Minimum Template

索引只导航：此表格不写不变量、不写字段，不写“待补/未发现”。缺口统一留给模块页的 
Evidence Gaps
。
markdown
undefined
Index only for navigation: Do not write invariants, fields, or "to be supplemented/not found" in this table. Gaps are uniformly left to the 
Evidence Gaps
section of the module page.
markdown
undefined

Components Index（地图层：只导航）

Components Index（地图层：只导航）

modulepriorityownercode_entryapi_contractdata_contractops_entrystatus
authP0team-x
src/auth/
apidataops- [ ]
orderP1team-y
src/order/
apidata- [ ]
legacy-toolingP2
tools/legacy/
- [ ]
undefined
modulepriorityownercode_entryapi_contractdata_contractops_entrystatus
authP0team-x
src/auth/
apidataops- [ ]
orderP1team-y
src/order/
apidata- [ ]
legacy-toolingP2
tools/legacy/
- [ ]
undefined

并行化建议

Parallelization Recommendations

当入口盘点任务互不依赖时，建议并行：
  • Agent A：运行入口 + 环境变量入口
  • Agent B：测试入口 + 质量门禁入口
  • Agent C：CI/CD 入口
  • Agent D：契约/Schema/DDL 入口 + Ops 入口
When portal inventory tasks are independent of each other, parallel execution is recommended:
  • Agent A: Runtime portals + environment variable portals
  • Agent B: Test portals + quality access control portals
  • Agent C: CI/CD portals
  • Agent D: Contract/Schema/DDL portals + Ops portals

红旗清单

Red Flag Checklist

  • Scope 还没做，就开始为一堆模块写细节（范围必失控）
  • 用“我猜应该是……”来填运行/测试/契约（必须写 Evidence Gaps）
  • 在索引里写“主要类/核心表/错误码/字段列表”（索引只导航）
  • Start writing details for a bunch of modules before Scope is completed (scope will definitely get out of control)
  • Use "I guess it should be..." to fill in runtime/test/contract information (must write Evidence Gaps instead)
  • Write "main classes/core tables/error codes/field lists" in the index (index is only for navigation)

常见错误

Common Mistakes

  • 把 Preflight 变成“写 README 教程”（应只固定入口与证据链）
  • 试图一次覆盖全部模块（应先 P0 三件套）
  • Turn Preflight into "writing README tutorials" (you should only fix portals and evidence chains)
  • Try to cover all modules at once (you should complete the P0 three-piece set first)