Spec mining
Skill alexander-danilenko/cortex-ai-skills/skills/spec-mining
Apply this opinionated workflow when reverse-engineering legacy or undocumented systems: scope, explore with Glob/Grep/Read, trace data flows, document in EARS format, flag uncertainties. For code archaeology, onboarding, and requirements extraction.From its SKILL.md
npx -y skills add alexander-danilenko/cortex-ai-skills --skill spec-miningAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 14 stars14 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
3.0 KB, as published. Nobody here has run it
Spec Mining
Extract a specification from a system that has no usable documentation, by reading the code that actually runs.
The discipline that makes the output trustworthy: separate what you observed from what you inferred. A reader will act on this document — rebuilding a service, planning a migration, onboarding — and a confident-sounding guess is worse than an acknowledged gap, because nobody goes back to check it.
Approach
Work outside-in: entry points, then routes, then the services behind them, then the data layer. Following an actual request path teaches you the system's real structure, which is often not the structure its directory names advertise.
Read the tests too. They document intended behaviour and edge cases someone hit in production, and they are usually more honest than any comment or README in the repo.
Read the migration history as well. Migrations are dated and ordered, so they show how the schema arrived at its current shape — which columns were added under pressure, what was backfilled, what was renamed but never dropped. That sequence is often the only surviving record of why the data model looks the way it does.
Every observation cites its evidence — src/auth/jwt.strategy.ts:42. Without a location the reader can't verify a claim, and unverifiable claims are what make reverse-engineered specs rot.
Writing observed requirements — EARS
EARS keeps requirements unambiguous by forcing the trigger and the state into the sentence, so "the system validates the token" can't hide when.
| Pattern | Form |
|---|---|
| Ubiquitous | The system shall [action]. |
| Event | When [trigger], the system shall [action]. |
| State | While [state], the system shall [action]. |
| Conditional | While [state], when [trigger], shall … |
| Optional | Where [feature enabled], shall … |
Number them by area so they can be referenced later — OBS-AUTH-001, OBS-USER-002:
OBS-AUTH-001
While credentials are valid, when POST /auth/login is called, the system
shall return a JWT access token (15m) and a refresh token (7d).
Evidence: src/auth/auth.controller.ts:31, src/auth/auth.service.ts:88
Uncertainties are a deliverable
Anything you could not determine from the code goes in its own section as a question, not a guess: what triggers a status transition, whether a delete is soft, which external system owns a field. This section is often the most valuable part of the document — it is the list of things a maintainer must be asked before anyone relies on the rest.
Output
Save to specs/{project_name}_reverse_spec.md. Structure and section order: references/specification-template.md.
What ships with it: 1 file
2.1 KB alongside SKILL.md
references/
Gives 0 of the 12 instructions most plan spec skills give
Counted across 1,360 of the 2,617 authors here whose files we hold, read 2026-09-06
- Ask one question at a timein 73 of 1360
- Write the spec using the templatein 22 of 1360
- Ask clarifying questions if neededin 19 of 1360, across 18 files
- Wait for user confirmation before proceedingin 19 of 1360
- Save plans to the plans directoryin 17 of 1360, across 13 files
- Check for product marketing context firstin 16 of 1360, across 5 files
- Read the plan file completelyin 16 of 1360
- Order tasks by dependencyin 16 of 1360
- Gather context from the conversationin 15 of 1360, across 9 files
- Explore the codebase instead of askingin 15 of 1360, across 13 files
- Wait for explicit user approvalin 14 of 1360, across 13 files
- Quiz the user on the breakdownin 13 of 1360, across 7 files
Said here and by no other author read
- Work outside-in from entry points
- Read the tests too
- Read the migration history as well
- Every observation cites its evidence
- Separate what you observed from what you inferred
- Document in EARS format
Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once.