Overview
This skill is used to take "an existing-code legacy project"within a single instruction, as completely as possible,reverse-sediment it into .aidlc/project/ project-level SSOT (long-term asset), to support AI-assisted development of subsequent Spec Packsand as much as possible no longer repeatedly run Discover。
The core of Discover is not "translating code into documentation", but establishing the following three things (and being able to maintain them continuously):
- Map layer: first have a navigable index skeleton (the index only navigates)
- Authoritative entry: each P0 module has a single-page module SSOT (the module page is authoritative)
- Evidence chain: each key conclusion can point to a locatable evidence entry (Evidence) within the repository or a structured gap (Evidence Gaps)
At the start, announce:"I am using the project-discover skill to execute Discover (reverse) for a legacy project and establish .aidlc/project/ project-level SSOT."
Goals (deliverables of a single instruction)
Ata single runat the end, by default at least the following should be produced and self-consistent (degrading to "insufficient evidence -> structured gaps" is allowed, but making things up is not):
- Level-0 / Memory (North Star)
.aidlc/project/memory/structure.md.aidlc/project/memory/tech.md.aidlc/project/memory/product.md.aidlc/project/memory/glossary.md
- Level-1 / Map index (navigation only + progress panel)
.aidlc/project/components/index.md(including direct-only dependency graph).aidlc/project/products/index.md(recommended; whether to create can be decided based on evidence)
- Module pages (authoritative entry, prioritize P0, as many as possible)
.aidlc/project/components/{module}.md: for each identified P0 modulecreate and fill it to DoD as much as possible; for P1 modules create as much as possible (a section of contract may be degraded to Evidence Gaps); P2 by default only index placeholders
- Ops (high ROI; create if there is evidence)
.aidlc/project/ops/index.md(and entry pages such as monitoring/rollback/runbook; add them only when they can link to real platforms/configs/scripts)
- Governance capability (sustainable)
- DoD/checklist gate rules can be implemented and enforced ("module complete" only looks at the module page meeting the standard)
- Incremental Discover (Delta Discover) and stale mechanisms have entries and writing constraints in the documentation (at least reflected in module page frontmatter and products/ops/memory's Evidence Gaps)
When to use / not use
- When to use
- You want to establish/complete for a legacy project
.aidlc/project/（memory / components / products / ops / nfr） - You find that "where the entry is, what the boundary is, where the contract is" is always guessed, causing AI or newcomers to repeatedly ask the same questions
- You worry about maintenance explosion caused by double-writing the index and details, exhaustive field lists, scattered TODOs, and non-authoritative contracts
- You want to do incremental Discover (Delta Discover) to combat stale knowledge
- You want to establish/complete for a legacy project
- Do not use it 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
.aidlc/project/contracts/**- API/Data contracts must be merged into the module page:
.aidlc/project/components/{module}.md's fixed section## API Contract/## Data Contract
- API/Data contracts must be merged into the module page:
- Index only navigates
.aidlc/project/components/index.mdand.aidlc/project/products/index.mdmust not contain invariants/fields/detailed flows/"to be added"
- Module page single-page SSOT (authoritative entry)
- 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; 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; gaps must go into
- Scope first to stop losses
- 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 for the user to trigger 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 to disk; if evidence is missing, write the gap)
- Finally do DoD/consistency gate backfilling(which modules can be checked off, which cannot, with reasons 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 a single run:
| What you need to do now | Which sub-skill to use | Main output location |
|---|---|---|
| Inventory "entries that can serve as evidence", and do P0/P1/P2 loss-stopping | project-discover-preflight-scope |
.aidlc/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 |
.aidlc/project/memory/* + .aidlc/project/components/index.md + .aidlc/project/products/index.md |
| Turn each P0 module one by one into a "single-page module SSOT + contract section + evidence chain" | project-discover-modules-contracts |
.aidlc/project/components/{module}.md |
| Converge Products, fill in Ops entries, do DoD checkbox gating, establish incremental maintenance | project-discover-products-ops-dod |
.aidlc/project/products/* + .aidlc/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 the 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). This skill's goal 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 respectively
- Modules in parallel: one sub-agent per P0 module (do not modify the same module page as each other; do not let multiple agents modify the same
components/{module}.md） - Products in parallel: 1 sub-agent is responsible for products convergence and
products/*(write only entry-level summaries, avoid exhaustive field/process lists) - 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 to disk, otherwise write Evidence Gaps
Hard constraints for parallel division of labor (conflict prevention/drift prevention)
- The only writable scope for the overall controller (you)：
.aidlc/project/memory/*.aidlc/project/components/index.md.aidlc/project/products/index.md- DoD checkbox backfilling and consistency verification (final aggregation)
- Writable scope for module sub-agents: only write the
.aidlc/project/components/{module}.md - Writable scope for products sub-agents: only write
.aidlc/project/products/*(do not modify components/index) - Writable scope for ops sub-agents: only write
.aidlc/project/ops/*
Sub-agent input (must be given clearly, to avoid "inventing structures")
The task description given to each sub-agent must include:
- This agent'swhitelist of paths allowed for writing
- This page'sfixed 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 original wording of baseline stress testing under "no skill constraints." The purpose of writing them here is to still uphold Discover's hard rules under pressure from time/authority/sunk cost.
| Excuse (original wording style) | Most common violation | Required countermeasure action |
|---|---|---|
| "First write the documentation fully, build out the structure completely, and reconcile the details against the code later." | Index writes details; TODOs scattered; contracts made up | First do the Scope + Index skeleton; push all details down to module pages; if evidence is missing, write Evidence Gaps, do not write speculation |
| "If the index is too dry, no one will read it; write some explanation so it is understandable without clicking in." | The index becomes a pile of details (double writing) | The index only navigates: only put links/checkboxes/owner/code_entry; details only on module pages |
| "There is no Swagger/OpenAPI, so first write a version of the contract based on experience and mark it 'to be verified.'" | The contract is not authoritative; exhaustive fields; wrong interpretations get amplified | The contract section of a module page should only write: authoritative entry point (file/generation command) + invariant summary + evidence entry point; if the authoritative entry point is missing -> Evidence Gaps |
| "Time is tight, so first mark uncertain things as 'to be added/not found' to show honesty." | "To be added" is scattered, so it can never be fully completed | Concentrate all gaps into ## Evidence Gaps, and write: gap/expected granularity/candidate evidence location/impact |
| "Half is already written, and changing it to an index that only navigates would require major changes; submit it first." | Structural violations driven by sunk cost | Delete/Move: move index details to the module page; indexes return to navigation; do not violate structural rules because of sunk cost |
| "Listing all fields makes it easier to query." | Full field list (maintenance explosion) | Field-level details only via authoritative entry links (schema/DDL/model); at the project layer write only invariant summaries |
| "How to run/how to deploy is a hard requirement, so it fits best at the project-level entry." | One-off delivery details pollute the project level | At the project level write onlyentry linksand minimal guardrails; detailed operation manuals belong to the ops system or external platform links |
Red flag checklist (if any one appears: stop and correct)
- In
.aidlc/project/components/index.mdorproducts/index.md, invariants/fields/detailed processes were written - Appears
.aidlc/project/contracts/** - A large number of "TODO/to be added/not found" are scattered throughout the body (not summarized into
Evidence Gaps） - The P0 module has
- [x], but the module page lacks fixed headings or lacks authoritative entry/invariants/evidence entry - Writing Products as a feature list of 20+ modules in order to "write it all"
Consistency and completion gate (must be done before this run ends)
At the end of an instruction, the orchestrator must complete the following checks and backfills to ensure the knowledge base is "usable and not self-contradictory":
- Index-navigation-only check：
components/index.md/products/index.mddoes not contain invariants/fields/detailed processes/"to be added/not found/TODO" - Module page compliance check (determines whether it can be checked off)：
- P0: the module page exists; fixed headings are complete; frontmatter metadata is complete; the API/Data contract section contains "authoritative entry + 3-7 invariants + evidence entry"; if gaps exist they must be written to Evidence Gaps, and the module must not be checked off
- P1: either API or Data may be missing, but Evidence Gaps must structurally record the gap and impact
- P2: not checked off by default
- SSOT gate: a checkmark in the index only reflects whether the module page meets the standard; do not "check off first, then fill in content"
- Dependency graph maintenance：
components/index.md's Mermaid dependency graph draws direct-only and labels the interaction mode (API/Event/DB) - Products convergence: by default <= 6; if convergence is impossible, provide the reason and a governance recommendation entry (do not write it as a large directory)
Quick reference (high-frequency lookup)
Minimum viable delivery (MVP)
.aidlc/project/memory/structure.md: entries for how to run/how to verify/how to release (traceable).aidlc/project/components/index.md: module map (navigation only) + checkbox progress + dependency graph- 1-3 P0 module pages:
.aidlc/project/components/{module}.md(including TL;DR + API/Data contract section + Evidence/Evidence Gaps)
DoD in one sentence
Whether a module is "complete" is determined only by whether the module page content meets the standard; the index checkmark merely reflects this fact.
Common mistakes
- Turning Discover into a "field-level dictionary project" (maintenance explosion)
- Writing details first and filling in the map later (leading to double-writing and broken links)
- Filling in gaps by imagination upon seeing them (downstream will treat guesses as facts)
- Merging requirement-level one-off delivery details into the project level (the project level becomes a dumping ground)