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

Overview

Inputs / Outputs

• 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"

Core Principles (Preflight)

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 Minimum Checklist (Find Evidence Portals)

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) Rules

Grading Recommendations (aligned with Discover DoD)

• 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: 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 Persistence) Minimum Template

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.

# Components Index（地图层：只导航）

| module | priority | owner | code_entry | api_contract | data_contract | ops_entry | status |
|--------|----------|-------|------------|--------------|---------------|-----------|--------|
| auth | P0 | team-x | `src/auth/` | [api](./auth.md#api-contract) | [data](./auth.md#data-contract) | [ops](../ops/index.md) | - [ ] |
| order | P1 | team-y | `src/order/` | [api](./order.md#api-contract) | [data](./order.md#data-contract) |  | - [ ] |
| legacy-tooling | P2 |  | `tools/legacy/` |  |  |  | - [ ] |

Parallelization Recommendations

• 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

• 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

• 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)