spec-mining · diff
git:20260504.759031f to git:20260803.af106c2
28 added, 54 removed. Audit A to A.
---
name: spec-mining
description: "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."
- allowed-tools: Read, Grep, Glob, Bash
---
- # Spec Miner
-
- Reverse-engineering specialist who extracts specifications from existing codebases.
-
- ## Role Definition
-
- You are a senior software archaeologist with 10+ years of experience. You operate with two perspectives: **Arch Hat** for system architecture and data flows, and **QA Hat** for observable behaviors and edge cases.
-
- ## When to Use This Skill
-
- - Understanding legacy or undocumented systems
- - Creating documentation for existing code
- - Onboarding to a new codebase
- - Planning enhancements to existing features
- - Extracting requirements from implementation
+ # Spec Mining
- ## Core Workflow
+ Extract a specification from a system that has no usable documentation, by reading the code that actually runs.
- 1. **Scope** - Identify analysis boundaries (full system or specific feature)
- 2. **Explore** - Map structure using Glob, Grep, Read tools
- 3. **Trace** - Follow data flows and request paths
- 4. **Document** - Write observed requirements in EARS format
- 5. **Flag** - Mark areas needing clarification
+ 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.
- ## Reference Guide
+ ## Approach
- Load detailed guidance based on context:
+ 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.
- | Topic | Reference | Load When |
- | --- | --- | --- |
- | Analysis Process | `references/analysis-process.md` | Starting exploration, Glob/Grep patterns |
- | EARS Format | `references/ears-format.md` | Writing observed requirements |
- | Specification Template | `references/specification-template.md` | Creating final specification document |
- | Analysis Checklist | `references/analysis-checklist.md` | Ensuring thorough analysis |
+ 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.
- ## Constraints
+ 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.
- ### MUST DO
+ 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.
- - Ground all observations in actual code evidence
- - Use Read, Grep, Glob extensively to explore
- - Distinguish between observed facts and inferences
- - Document uncertainties in dedicated section
- - Include code locations for each observation
+ ## Writing observed requirements — EARS
- ### MUST NOT DO
+ EARS keeps requirements unambiguous by forcing the trigger and the state into the sentence, so "the system validates the token" can't hide _when_.
- - Make assumptions without code evidence
- - Skip security pattern analysis
- - Ignore error handling patterns
- - Generate spec without thorough exploration
+ | 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 … |
- ## Output Templates
+ Number them by area so they can be referenced later — `OBS-AUTH-001`, `OBS-USER-002`:
- Save specification as: `specs/{project_name}_reverse_spec.md`
+ ```text
+ 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
+ ```
- Include:
+ ## Uncertainties are a deliverable
- 1. Technology stack and architecture
- 2. Module/directory structure
- 3. Observed requirements (EARS format)
- 4. Non-functional observations
- 5. Inferred acceptance criteria
- 6. Uncertainties and questions
- 7. Recommendations
+ 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.
- ## Knowledge Reference
+ ## Output
- Code archaeology, static analysis, design patterns, architectural patterns, EARS syntax, API documentation inference
+ Save to `specs/{project_name}_reverse_spec.md`. Structure and section order: `references/specification-template.md`.