Overview
This skill is used to turn "an existing codebase legacy project"within a single command, as completely as possible,reverse-engineered and distilled into .aisdlc/project/ project-level SSOT (long-term asset), to support AI-assisted development for subsequent Spec Packsavoid re-running Discover as much as possible。
The core of Discover is not "translating code into documentation", but establishing the following three things (and keeping them continuously maintainable):
- Map layer: first have a navigable index skeleton (the index only navigates)
- Authoritative entry points: each P0 module has a single-page module SSOT (the module page is authoritative)
- Evidence chain: every key conclusion can point to a locatable evidence entry point within the repository (Evidence) or a structured gap (Evidence Gaps)
At the start, announce:"I am using the project-discover skill to execute Discover (reverse-engineering) for a legacy project and establish .aisdlc/project/ project-level SSOT."
Goals (deliverables of a single command)
Atsingle runend, by default at least the following should be produced and self-consistent (downgrading from "insufficient evidence -> structured gaps" is allowed, but making things up is not):
- 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(suggested; may be created or not based on evidence)
- Module pages (authoritative entry points, prioritize P0, as many as possible)
.aisdlc/project/components/{module}.md: for each identified P0 modulecreate and fill in as much as possible to DoD; for P1 modules create as much as possible (a section of contract may be downgraded to Evidence Gaps); P2 by default only indexed placeholders
- Ops (high ROI; create if evidence exists)
.aisdlc/project/ops/index.md(as well as entry pages such as monitoring/rollback/runbook, to be added when they can link to real platforms/configs/scripts)
- Governance capability (sustainable)
- DoD/checklist gate rules can be practically enforced ("module complete" only depends on the module page meeting the standard)
- Incremental Discover (Delta Discover) and the stale mechanism have entry points and writing constraints in the documentation (at least reflected in the module page frontmatter and the Evidence Gaps of products/ops/memory)
When to use / not use
- When to use
- You need to establish/complete for a legacy project
.aisdlc/project/（memory / components / products / ops / nfr） - You find that "where the entry point is, what the boundary is, where the contract is" always relies on guessing, causing the AI or newcomers to repeatedly ask the same questions
- You worry that writing indexes and details twice, exhaustive field lists, scattered TODOs, and non-authoritative contracts will cause a maintenance explosion
- You need to do incremental Discover (Delta Discover) to combat knowledge going stale
- You need to establish/complete for a legacy project
- Do not use for
- You are doingrequirement-level Spec Pack 's
requirements//design//implementation/(that is the spec-* skill chain) - You need to write a "field-level data dictionary" as an independent system for compliance/reconciliation/KPI definition governance (this is not Discover's default goal)
- You are doingrequirement-level Spec Pack 's
Core hard rules (if any one appears: stop and correct)
- Prohibit producing
.aisdlc/project/contracts/**- API/Data contracts must be merged into the module page:
.aisdlc/project/components/{module}.mdfixed section of## API Contract/## Data Contract
- API/Data contracts must be merged into the module page:
- Index only navigates
.aisdlc/project/components/index.mdand.aisdlc/project/products/index.mdmust not contain invariants/fields/detailed processes/"to be added"
- Module page single-page SSOT (authoritative entry point)
- P0 modules must have a module page and include fixed headings (stable anchors):
## TL;DR、## API Contract、## Data Contract、## Evidence（证据入口）、## Evidence Gaps（缺口清单）
- P0 modules must have a module page and include fixed headings (stable anchors):
- No guessing: if evidence is missing, write Evidence Gaps
- It is not allowed to scatter "to be added/not found/TODO" throughout the body text; gaps must go into
## Evidence Gaps（缺口清单）, structurally writing clearly "what is missing/where to find it/impact"
- It is not allowed to scatter "to be added/not found/TODO" throughout the body text; gaps must go into
- Stop the loss with Scope first
- Discover's biggest risk is uncontrolled coverage: you must first do P0/P1/P2; for P0, first do the three-piece set (module page + contract section + evidence chain) before expanding
- Converge Products to <= 6 (default)
- The business module map is a "business semantic anchor," not a comprehensive feature list; too many will make the map ineffective
Single-instruction execution strategy (master orchestration, do not run repeatedly)
This skill is a "master orchestrator." During execution, do not split the work into multiple rounds and make the user trigger it repeatedly; instead, complete it in this run:
- First build the map skeleton（Memory + Index）
- Then fill in module pages in parallel(As many P0 as possible, cover P1 as much as possible, P2 only placeholder)
- Converge Products and fill in Ops in parallel(If there is evidence, write it down; if evidence is missing, write the gap)
- Finally do DoD/consistency gate backfilling(Which modules can be checked off, which cannot, and the reasons are in the module page Evidence Gaps)
To ensure the output is maintainable, Discover is split into 4 deliverable domains (corresponding to the existing sub-skills), but they should be completed and summarized in one run:
| What you need to do now | Which sub-skill to use | Main output location |
|---|---|---|
| Inventory "entry points that can serve as evidence," and do P0/P1/P2 loss-stopping | project-discover-preflight-scope |
.aisdlc/project/components/index.md(priority/owner/code_entry, etc.) + evidence entry list placed into subsequent memory/ops |
| Establish the 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 |
| Turn each P0 module one by one into "single-page module SSOT + contract section + evidence chain" | project-discover-modules-contracts |
.aisdlc/project/components/{module}.md |
| Converge Products, fill in Ops entry points, do DoD checklist gates, and establish incremental maintenance | project-discover-products-ops-dod |
.aisdlc/project/products/* + .aisdlc/project/ops/* + DoD/Delta/expiration rules |
Default strategy (as rich as possible): Do not limit P0 to 1–3; within the allowed budget, create module pages for all identified P0s as much as possible and fill them to a usable threshold. If the repository is too large to fully cover: still complete memory + index, and leave "traceable Evidence Gaps and candidate evidence locations" for uncovered P0/P1, rather than blanks or guesses.
Parallelization suggestions (optional, but high ROI)
When you face 2+ mutually 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 in parallel: Scan the evidence entry points for run/test/ci/contract/ops separately
- Modules in parallel: one sub-agent per P0 module (do not have multiple agents modify the same module page; do not let multiple agents modify the same
components/{module}.md） - Products in parallel: 1 sub-agent is responsible for products convergence and
products/*(only write entry-level summaries, avoid exhaustive fields/flows) - Ops in parallel: 1 sub-agent is responsible for ops entry points and evidence (monitoring/alerting, log entry points, rollback entry points); as long as a real entry point can be provided, write it down, otherwise write Evidence Gaps
Hard constraints for parallel division of labor (conflict prevention/drift prevention)
- The only writable scope for the overall controller (you)：
.aisdlc/project/memory/*.aisdlc/project/components/index.md.aisdlc/project/products/index.md- DoD checkbox backfill and consistency verification (final summary)
- Write scope for module sub-agents: only write the
.aisdlc/project/components/{module}.md - Write scope for products sub-agents: only write
.aisdlc/project/products/*(do not modify components/index) - Write scope for ops sub-agents: only write
.aisdlc/project/ops/*
Sub-agent input (must be given clearly to avoid "inventing structures")
The task description given to each sub-agent must include:
- For that agentthe whitelist of paths allowed for writing
- For that pagefixed heading/anchor requirements(especially the module page's
## TL;DR / ## API Contract / ## Data Contract / ## Evidence / ## Evidence Gaps） - “If evidence is missing, write Evidence Gaps; do not make things up" hard rules
- Require output of "authoritative entry link + invariant summary + evidence entry point" at the minimum granularity (file/class/job/command)
Common excuses and countermeasures (from baseline stress testing)
These excuses come from the exact words of baseline stress testing under "no-skill constraints". The purpose of writing them here is to still uphold Discover's hard rules under time/authority/sunk-cost pressure.
| Excuse (original wording style) | Most common violation | Required countermeasure action |
|---|---|---|
| "First write the docs completely and build out the full structure; align the details with the code later." | Index writes details; TODOs are scattered; contracts are imagined | First do the Scope + Index skeleton; push all details down to module pages; if evidence is missing, write Evidence Gaps, not speculation |
| "If the index is too dry, no one will read it; write a little explanation so people understand without clicking in." | The index becomes a pile of details (double writing) | The index only navigates: only links/checkboxes/owner/code_entry; details only on module pages |
| "There is no Swagger/OpenAPI, so write a contract version based on experience first and mark it 'to be verified'." | The contract is not authoritative; exhaustive fields; the wrong interpretation gets amplified | The contract section of the module page only writes: authoritative entry point (file/generation command) + invariant summary + evidence entry point; missing authoritative entry point -> Evidence Gaps |
| "Time is tight, so first mark uncertain things as 'to be added/not found' to show honesty." | "To be added" scattered around means it can never be fully completed | Concentrate all gaps into ## Evidence Gaps, and write: gap/expected granularity/candidate evidence location/impact |
| "Half of it is already written, and changing it back to index-only navigation would require major revisions; ship it first." | Sunk-cost-driven structural violations | Delete/Move: move index details to module pages; the index returns to navigation; do not violate structural rules because of sunk cost |
| "Listing all fields makes it easier to query." | Field encyclopedia (maintenance explosion) | Field-level details are linked only through authoritative entry points (schema/DDL/model); at the project level, write only invariant summaries |
| "How to run/how to deploy is a hard requirement, so it is most appropriate to write it at the project-level entry point." | One-off delivery details pollute the project level | Project level writes onlyentry linksand minimal guardrails; detailed operation manuals belong to the ops system or external platform links |
Red-flag checklist (if any item appears: stop and correct)
- In
.aisdlc/project/components/index.mdorproducts/index.mdinvariants/fields/detailed processes were written - Appears
.aisdlc/project/contracts/** - A large number of "TODO/to be added/not found" items are scattered throughout the body (not summarized into
Evidence Gaps） - P0 module is marked
- [x], but the module page lacks fixed headings or lacks authoritative entry points/invariants/evidence entry points - To "write it all," Products is written as a feature list of 20+ modules
Consistency and completion gate (must be done before the end of this run)
At the end of an instruction, the controller must complete the following validation and backfilling to ensure the knowledge base is "usable and not self-contradictory":
- Index navigation-only validation：
components/index.md/products/index.mddoes not contain invariants/fields/detailed processes/"to be added/not found/TODO" - Module page compliance validation (determines whether it can be checked)：
- P0: the module page exists; fixed headings are complete; frontmatter metadata is complete; the API/Data contract section contains "authoritative entry points + 3–7 invariants + evidence entry points"; if gaps exist, they must be written to Evidence Gaps, and the module must not be checked
- P1: either API or Data may be missing, but Evidence Gaps must structurally record the gap and impact
- P2: unchecked by default
- SSOT gate: checkmarks in the index only reflect whether the module page meets the standard; do not "check first and fill in content later"
- Dependency graph maintenance：
components/index.mdThe Mermaid dependency graph draws only direct-only and labels the interaction method (API/Event/DB) - Products convergence: default <= 6; if convergence is impossible, the reason and governance recommendation entry point must be given (do not write it as a large directory)
Quick reference (high-frequency quick lookup)
Minimum viable delivery (MVP)
.aisdlc/project/memory/structure.md: entry points for how to run/how to verify/how to release (traceable).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 section + Evidence/Evidence Gaps)
One-sentence DoD
Whether a module is "complete" is determined only by whether the module page content meets the standard; the index checkmark only reflects this fact.
Common mistakes
- Making Discover into a "field-level dictionary project" (maintenance explosion)
- Writing details first and adding the map later (leading to double-writing and broken links)
- Filling in gaps by guessing when they are seen (downstream will treat guesses as facts)
- Merging requirement-level one-off delivery details into the project level (the project level becomes a dumping ground)