Reverse Engineering Specifications

Overview

For brownfield/legacy projects without documentation, this skill generates implementation-free specifications by exhaustively analyzing existing code. The output is a complete behavioral description that drives autonomous development on top of the existing codebase — enabling safe refactoring, feature addition, and modernization.

Key principle: Document actual behavior, including bugs. Bugs are "documented features" until explicitly marked for fixing.

This is a RIGID skill. Every code path must be traced. No assumptions, no skipping.

Phase 1: Exhaustive Code Investigation

[HARD-GATE] Every code path must be traced. No assumptions, no skipping.

Deploy parallel subagents via the Agent tool (up to 500, with subagent_type="Explore") to analyze:

Investigation Strategy Decision Table

STOP after investigation — present a summary of discovered entry points, data flows, and behaviors. Get confirmation before generating specs.

Phase 2: Behavioral Specification Generation

Transform code analysis into implementation-free specs following the spec-writing skill format.

Transformation Rules

Implementation Detail Stripping

STOP after spec generation — run the completeness checklist before organizing.

Phase 3: Specification Organization

Create spec files following the naming convention:

specs/
├── 01-[first-capability].md
├── 02-[second-capability].md
├── ...
├── NN-[last-capability].md
└── KNOWN_ISSUES.md

KNOWN_ISSUES.md Format

# Known Issues

## [Issue Title]
- **Current behavior:** [What actually happens]
- **Expected behavior:** [What should happen, if known]
- **Affected specs:** [Which spec files reference this behavior]
- **Severity:** [Critical | High | Medium | Low]
- **Notes:** [Additional context]

Severity Classification

STOP after organization — present the spec file list and KNOWN_ISSUES for review.

Phase 4: Quality Verification

[HARD-GATE] All checks must pass before this phase is complete.

Concrete Example: Code to Spec Transformation

Code (input — what you analyze):

function checkAuth(req, res, next) {
  const token = req.headers.authorization?.split(' ')[1];
  if (!token) return res.status(401).json({ error: 'No token' });
  try {
    const decoded = jwt.verify(token, process.env.JWT_SECRET);
    req.user = decoded;
    next();
  } catch (e) {
    return res.status(403).json({ error: 'Invalid token' });
  }
}

Spec (output — what you produce):

# Request Authentication

## Job to Be Done
When a request arrives at a protected endpoint, I want to verify the
caller's identity, so I can ensure only authorized users access the system.

## Acceptance Criteria

### Valid Credentials
- Given a request with valid credentials in the authorization header
- When the request is processed
- Then the request proceeds to the next handler
- And the authenticated user identity is available to downstream handlers

### Missing Credentials
- Given a request without credentials
- When the request is processed
- Then a 401 status is returned
- And an error message indicates missing credentials

### Invalid Credentials
- Given a request with invalid or expired credentials
- When the request is processed
- Then a 403 status is returned
- And an error message indicates invalid credentials

## Edge Cases
- Malformed authorization header (missing "Bearer" prefix): treated as missing credentials
- Expired credentials: treated as invalid credentials

## Data Contracts
- Input: Authorization header in "Bearer <credential>" format
- Output on success: User identity object attached to request context
- Output on failure: JSON error response with appropriate status code

Notice: No mention of JWT, middleware, Express, environment variables, or any implementation detail.

Anti-Patterns / Common Mistakes

Anti-Rationalization Guards

• [HARD-GATE] Do NOT skip any code path — every branch, conditional, and error handler must be traced
• [HARD-GATE] Do NOT include ANY implementation details in specs — no code, tech names, or architecture
• [HARD-GATE] Do NOT mark the completeness checklist as done until ALL 12 items pass
• Do NOT skip concurrency analysis — even if the code "looks synchronous"
• Do NOT skip configuration analysis — env vars and feature flags change behavior
• Do NOT assume behavior from function names — read the actual code
• Do NOT fix bugs while reverse-engineering — document them in KNOWN_ISSUES.md

Integration Points

Workflow After Reverse Engineering

Verification Gate

Before claiming reverse engineering is complete:

1. VERIFY the completeness checklist (all 12 items) passes
2. VERIFY zero implementation details in any spec file
3. VERIFY all acceptance criteria use Given/When/Then format
4. VERIFY KNOWN_ISSUES.md exists and categorizes all discovered bugs
5. VERIFY the user has reviewed the spec set and KNOWN_ISSUES

Skill Type

Flexible — Adapt investigation depth and subagent count to codebase size while preserving the exhaustive-investigation and implementation-free output rules. No code paths may be skipped.