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

Overview

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)

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

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)

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)

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.

Parallelization Suggestions (optional, high ROI)

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)

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

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)

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)

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)

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 (high frequency check)

Minimum Viable Deliverable (MVP)

```
.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 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

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)

project-discover

NPX Install

Tags

SKILL.md Content (Chinese)