SuperAPI AI Directory

aisdlc-project-discover

General & other

View repository

Updated 10-16 08:49

About this skill

aisdlc-project-discover (Brownfield Project Discover / Reverse-engineer a project-level knowledge base)

Overview

This Skill is of the "navigation + gatekeeping" type: it consolidates the repository facts of a brownfield project (code/config/CI/contracts/runtime entry points) into the .aisdlc/project/ project-level SSOT.

Core principles:

  • At the project level, write only stable entry points and boundaries: entry links + invariant summary + evidence entry points; do not create an exhaustive field catalog.
  • Map skeleton first, then fill in evidence: the index only navigates; details live only in module pages/contract entry pages.
  • The evidence chain must be traceable: Contracts ↔ Code ↔ Tests ↔ CI ↔ Ops (linked together via entry points).

At the start, announce:"I am using the aisdlc-project-discover skill to reverse-engineer the .aisdlc/project/ project-level knowledge base for the brownfield project, and I am enforcing the gatekeeping to prevent drift."

When to use / not use

  • When to use
    • You take over a brownfield project with existing code and need to establish a project-level map layer and authoritative entry points for subsequent collaboration and AI-assisted development.
    • The team keeps asking "where is the entry point / who is responsible / how to run it / how to verify it / where are the contracts," and repeated verbal explanations cause drift.
    • Under pressure, you are easily asked to "write all the details first / write the complete field dictionary / write first and add the index later."
  • Do not use it for
    • Purely "new requirement/new feature" specification-based delivery (that is the Spec Pack process).
    • Situations requiring the generation of a field-level data dictionary/full API field descriptions as a strong deliverable (this Skill explicitly opposes this; unless there is a hard compliance requirement and a separate governance plan).

Artifacts and Landing Locations (the only SSOT)

Land only in the repository root directory's .aisdlc/project/(do not invent .aisdlc/project/docs/*、flows/*、data-dictionary/* such "detail repositories" to evade the constraints).

  • Level-0(Memory)
    • .aisdlc/project/memory/structure.md
    • .aisdlc/project/memory/tech.md
    • .aisdlc/project/memory/product.md
    • .aisdlc/project/memory/glossary.md
  • Level-1 (map-layer index + module pages)
    • .aisdlc/project/components/index.md + .aisdlc/project/components/{module}.md
    • .aisdlc/project/products/index.md + .aisdlc/project/products/{module}.md(optional but recommended to converge to ≤ 6)
  • Contracts (contract entry pages)
    • .aisdlc/project/contracts/index.md
    • .aisdlc/project/contracts/api/index.md + .aisdlc/project/contracts/api/{module}.md
    • .aisdlc/project/contracts/data/index.md + .aisdlc/project/contracts/data/{module}.md
  • Ops (high-ROI entry pages, optional)
    • .aisdlc/project/ops/(entry points for Runbook/monitoring and alerting/rollback, etc.)
    • .aisdlc/project/nfr.md(if the team already has a system, only entry links may be needed)

How to Handle One-Off Delivery Details (the correct home for sunk costs)

When you already have things like "detailed sequences/migration steps/field constraints/operation manuals" — these kinds ofone-off delivery details:

  • At the project level (.aisdlc/project/), keep only: entry links + invariant summary + evidence entry points (pointing to code/contract files/tests/CI/monitoring, and if necessary also to archived Spec Pack files).
  • Full details should be archived in:.aisdlc/specs/<DEMAND-ID>/...(or the team's existing external documentation system), and referenced at the project level via links.

The purpose of doing this is not to "throw away the details," but to prevent the project-level knowledge base from becoming an unmaintainable, long-term drifting pile of details.

Workflow (Overview)

flowchart TD
  preflight[Step0_Preflight] --> scope[Step1_Scope]
  scope --> l0[Step2_Level0_Memory]
  l0 --> l1[Step3_Level1_IndexSkeleton]
  l1 --> modules[Step4_Modules_ComponentsAndContracts]
  modules --> products[Step5_Products_Aggregation]
  modules --> ops[Step6_OpsAndEvidence]
  products --> dod[Step7_DoD_Gates]
  ops --> dod
  dod --> iterate[Iterate_Maintain]

REQUIRED SUB-SKILL (execute step by step)

Each sub-skill provides copyable templates, checklists, red flags, and counters to common mistakes.

  • Step0:aisdlc-project-discover-preflight
  • Step1:aisdlc-project-discover-scope
  • Step2:aisdlc-project-discover-level0-memory
  • Step3:aisdlc-project-discover-level1-index-skeleton
  • Step4:aisdlc-project-discover-modules-contracts
  • Step5:aisdlc-project-discover-products-aggregation
  • Step6:aisdlc-project-discover-ops-evidence
  • Step7:aisdlc-project-discover-dod-gates

Parallel strategy (optional, but recommended)

When you need to reverse-engineer multiple independent modules at the same time (for example, 3 P0 modules):

  • REQUIRED SUB-SKILL: use dispatching-parallel-agents to dispatch sub-agents in parallel
  • Each sub-agent is responsible only for Step4 of one module (component page + API/Data contract entry page + evidence entry)
  • The controller is responsible for: the skeleton and gates of Step0/Step1/Step2/Step3, as well as final DoD verification and index backfilling

Gates (must be followed, otherwise stop)

  • The index only navigates:components/index.md / contracts/*/index.md / products/index.md Copying module details is prohibited.
  • The contract page trio: each contracts/api|data/{module}.md must have:
    • Authoritative entry (path or link to OpenAPI/Proto/Schema/migrations/ORM models)
    • Invariant summary (3–7 items)
    • Evidence entry (relevant code entry + test entry + CI gate/command entry)
  • P0 depth hard constraint: P0 modules must have both components/{module}.md + contracts/api/{module}.md + contracts/data/{module}.md + evidence entry.
  • Memory must be short:memory/* Only write stable entries and boundaries; writing one-off delivery details is prohibited.

Red flag checklist (if any item appears: stop and correct)

  • “First write the field dictionary / API field descriptions completely, the more detailed the better” and require putting it at the project level
  • “Write the details first, add the index later” (causing double-writing of the index / failure of the map layer)
  • Attempting under .aisdlc/project/ to add docs/data-dictionary/、api-reference/、flows/、ops/runbooks/、ops/migrations/ and other “detail repositories” to carry full field-level/time-sequence-level/migration-level content
  • Merging one-off delivery details (detailed timing/migration script descriptions/full set of field constraints/complete version of operation manuals) wholesale into the project level and promising “from now on only maintain at the project level”
  • When unable to provide an “evidence entry,” starting to make things up (should instead change to placeholders + evidence gap list, rather than fabricating)

Common excuses and counters (from baseline stress testing)

Excuse (source of pressure) Common violations Required counteraction
“Deliver within 15 minutes, don’t ask questions, first fill in the details” Write the index as a details page; Memory becomes a long document; guess when evidence is missing Skeleton first, evidence after: the index only navigates; for missing evidence, write only “entry placeholder + evidence gap list”
“The leader wants a complete field list, put it at the project level” Add docs/data-dictionary / api-reference to carry the full field-level set Return to this Skill’snon-goals: the project level only does entries and invariants; when a complete field list is needed, a separate governance plan must be started (not within this Skill)
“I have already written many one-off delivery details, merge them all into project” Add flows/、ops/runbooks/、ops/migrations/ and other directories to carry details Keep the project level short: retain only authoritative entries and the evidence chain; one-off delivery details are not allowed to become the project-level SSOT

A good example (the shortest usable correct delivery)

You only need to make .aisdlc/project/ achieve “can navigate, can locate entries, can trace evidence”:

  • memory/structure.md: Entry links for how to run/how to test/how to release
  • components/index.md: Module table + checkbox progress (no details)
  • For each P0 module:components/{module}.md + contracts/api/{module}.md + contracts/data/{module}.md(all three components complete)
  • ops/: Only build the entry page (dashboard/alert/runbook links), do not copy the operations manual