skilld
All skills
jeffallan avatar

/spec-miner

@efebc44
by jeffallanjeffallan/claude-skills12k stars
1,124

Reverse-engineering specialist that extracts specifications from existing codebases. Use when working with legacy or undocumented systems, inherited projects, or old codebases with no documentation. Invoke to map code dependencies, generate API documentation from source, identify undocumented business logic, figure out what code does, or create architecture documentation from implementation. Trigger phrases: reverse engineer, old codebase, no docs, no documentation, figure out how this works, inherited project, legacy analysis, code archaeology, undocumented features.

Ask your Agent

Use this Skill: https://skilld.dev/gh/jeffallan/claude-skills/spec-miner

This session only. Nothing lands on disk.

referencesspecification-template.md

≈619 tokens on demand. Your agent reads this file only when SKILL.md points to it.

Specification Template

Full Template

# Reverse-Engineered Specification: [System/Feature Name]

## Overview
[High-level description based on analysis]

## Architecture Summary

### Technology Stack
- **Language**: TypeScript 5.x
- **Framework**: NestJS 10.x
- **Database**: PostgreSQL 15
- **ORM**: Prisma 5.x

### Module Structure

src/ ├── auth/ # Authentication (JWT, guards) ├── users/ # User CRUD operations ├── orders/ # Order processing └── common/ # Shared utilities


### Data Flow

Request → Guard → Controller → Service → Repository → Database ↓ External APIs


## Observed Functional Requirements

### [Module Name]

**OBS-XXX-001**: [Feature Name]
[EARS format requirement]

**OBS-XXX-002**: [Feature Name]
[EARS format requirement]

## Observed Non-Functional Requirements

### Security
- JWT tokens signed with RS256
- Passwords hashed with bcrypt (12 rounds)
- Rate limiting: 100 req/min per IP

### Performance
- Database connection pool: 10 connections
- Response timeout: 30 seconds
- Pagination: default 20, max 100

### Error Handling
| Code | Condition | Response |
|------|-----------|----------|
| 400 | Validation failure | `{ error: string, details: object }` |
| 401 | Invalid/missing token | `{ error: "Unauthorized" }` |
| 404 | Resource not found | `{ error: "Not found" }` |
| 500 | Unhandled error | `{ error: "Internal server error" }` |

## Inferred Acceptance Criteria

### AC-001: [Feature]
Given [precondition]
When [action]
Then [expected result]

## Uncertainties and Questions

- [ ] What triggers order status transitions?
- [ ] Is soft delete implemented for users?
- [ ] What external APIs are called?
- [ ] Are there background jobs?

## Recommendations

1. Add OpenAPI documentation to controllers
2. Missing input validation on PATCH endpoints
3. Consider adding request tracing

Output Location

Save specification as: specs/{project_name}_reverse_spec.md

Required Sections

Section Purpose
Overview High-level summary
Architecture Tech stack, structure, data flow
Functional Requirements EARS format observations
Non-Functional Security, performance, errors
Acceptance Criteria Given/When/Then format
Uncertainties Questions for clarification
Recommendations Improvements identified

Source: SKILL.md on GitHub

Third-party checks

1 alert16d5 checks · Risk CRITICAL
  • Gen Agent Trust Hub16d

    The skill facilitates reverse-engineering of codebases but directs the agent to access sensitive credentials in .env files and environment configurations. Security scanners have flagged the skill file itself and its external documentation links as potentially malicious.

  • Socket16d

    No alerts

  • Snyk16d

    Risk: LOW · No issues

  • Runlayer6mo

    1/5 files flagged

  • ZeroLeaks5mo

    Score: 93/100 · 2 sections analyzed

Provenance

Signed by skilld at efebc44. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 2 months ago.

Steadyupdated 5 months ago

Capability

What it can do
Reads files Runs commands
All 4 allowed tools
ReadGrepGlobBash
Other metadata
metadata
{
  "author": "https://github.com/Jeffallan",
  "version": "1.1.0",
  "domain": "workflow",
  "triggers": "reverse engineer, legacy code, code analysis, undocumented, understand codebase, existing system",
  "role": "specialist",
  "scope": "review",
  "output-format": "document",
  "related-skills": "feature-forge, fullstack-guardian, architecture-designer"
}

Topics

  • Documentation
  • reverse-engineering
  • legacy-code
  • code-analysis
  • codebase-exploration
  • requirements-extraction
  • architecture
  • undocumented-systems

README badge

README badge for jeffallan/claude-skills/spec-miner

What it does

Extracts specifications from undocumented or legacy codebases by systematically exploring code structure, tracing data flows, and documenting observed behavior in EARS format. Use this skill when onboarding to inherited projects, creating documentation from implementation, or understanding systems with no written specification.

Generated from the current SKILL.md.

Frequently asked

What tools can this skill use to explore a codebase?
The skill uses Read, Grep, Glob, and Bash to map file structure, locate patterns, trace data flows, and extract observable behaviors from source code.
Does this skill generate documentation in a specific format?
Yes. It documents observed requirements using EARS (Easy Approach to Requirements Syntax) format, which structures behavior as ubiquitous, event-driven, state-driven, or optional rules.
Can this skill work on any codebase or language?
The skill is language-agnostic and designed for any codebase, but examples in the documentation focus on Python (Flask, Django) and Express. Adjustment of Glob and Grep patterns may be needed for other languages or frameworks.
Does this skill make assumptions or only report what it finds in code?
The skill must ground all observations in actual code evidence and distinguish between observed facts and inferences. It documents uncertainties in a dedicated section rather than making unsupported assumptions.
What does the skill output?
It produces a specification document saved as `specs/{project_name}_reverse_spec.md`, including technology stack, module structure, observed requirements, non-functional observations, inferred acceptance criteria, uncertainties, and recommendations.

Generated from the current SKILL.md. These answers refresh after source changes.