project-discover-preflight-scope

project-discover-preflight-scope (Step0+1: evidence entry inventory + scope stop-loss)

Overview

The goal of Preflight is not to "write out all the information", but to first take inventory of the executable/locatable evidence entry points clearly; the goal of Scope is to first apply a coverage stop-loss(P0/P1/P2), to avoid reverse engineering turning into "write everything but unmaintainable".

At the start, announce:"I am using the project-discover-preflight-scope skill to execute Discover's Preflight and Scope stop-loss."

Input / Output

• Input
  • Repository root directory (code, configuration, dependencies, CI/CD configuration)
  • Existing documentation entry points (README/Makefile/package.json/scripts, etc.)
  • Observability/operations entry points (if present: dashboard, alerts, runbook, rollback)
• Output (to disk)
  • .aidlc/project/components/index.md: module inventory + P0/P1/P2 + code_entry + checkboxes (do not check them at this point)
  • .aidlc/project/memory/structure.md: pin the "how to run/how to verify/how to release" entry points in link form (the next sub-skill will formally write them)
  • Note: the "evidence entry inventory" from Preflight does not need a separate new file; it is recommended to gradually place it in a distributed way as "entry links + Evidence Gaps" into memory/*, module pages, and ops/*

Core principles (Preflight)

1. Prefer executable evidence
   • Priority: scripts/CI jobs/contract files/migrations/generation commands > descriptive documentation > oral experience
2. Record only "entry points", do not write inferences
   • What you need to write is "where to enter from, how to locate, which file/which job the evidence is in", not "how it should work"
3. Missing evidence = structured gap
   • Write it into the subsequent document's ## Evidence Gaps: gap/expected granularity/candidate location/impact

Preflight minimal checklist (find evidence entry points)

As long as it can locate a specific file or job name, it counts as a valid entry point; do not make things up just to "write complete explanations".

• Run entry points
  • Local startup script/command entry points (for example:package.json scripts、Makefile、*.ps1/*.sh、docker-compose、k8s manifest）
  • Environment variable entry points (for example:.env.example, configuration templates, helm values)
• Test entry points
  • Command entry points and directory entry points for unit/integration/E2E tests
  • Coverage/gate entry points (for example: CI jobs, test threshold configuration)
• CI/CD entry points
  • workflow/pipeline file locations + key job names
  • Whether there are gates such as docs/link-check (if not, they can be suggestions later)
• Contract/structured fact entry points
  • OpenAPI/Proto/GraphQL schema
  • DB migrations/DDL/ORM models
• Observability/operations entry points (if any)
  • dashboard, alerts, log query entry points, runbook, rollback entry points

Scope (P0/P1/P2) rules

Grading suggestions (aligned with Discover DoD)

• P0 (must): high-frequency changes, cross-team boundaries, many external integrations, incident/failure hotspots, high compliance risk
• P1 (recommended): Stable but frequently referenced/asked about/depended-upon foundational capabilities
• P2 (on demand): Low risk, low collaboration, short lifecycle; create index placeholders first, upgrade when necessary

Reverse-engineering deep stop-loss (hard constraint)

• P0: Must ultimately have a module page .aidlc/project/components/{module}.md, and the page must simultaneously contain ## API Contract + ## Data Contract + ## Evidence(gaps can only be written to Evidence Gaps, and this module must not be checked off)
• P1: Must ultimately have a module page; allowed to degrade either the API or Data section to Evidence Gaps (recording gaps and impact)
• P2: Only index placeholder navigation (no module page created by default)

components/index.md(Scope persisted) minimal template

Index only navigates: This table does not write invariants, does not write fields, and does not write "to be added/not found". Gaps are uniformly left to the module page's Evidence Gaps。

# 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 suggestions

When entry-point inventory tasks are mutually independent, parallelization is recommended:

• Agent A: runtime entry points + environment variable entry points
• Agent B: test entry points + quality gate entry points
• Agent C: CI/CD entry points
• Agent D: contract/schema/DDL entry points + Ops entry points

Red flag checklist

• Starting to write details for a bunch of modules before Scope is done (scope will inevitably spiral out of control)
• Filling in runtime/test/contract with "I guess it should be..." (Evidence Gaps must be written)
• Writing "main classes/core tables/error codes/field lists" in the index (the index only navigates)

Common mistakes

• Turning Preflight into "writing a README tutorial" (it should only lock down entry points and the evidence chain)
• Trying to cover all modules at once (the P0 trio should be done first)