Reverse PRD

Extract a Product Requirements Document from what the codebase ACTUALLY does, not what documentation claims. This skill traces routes, handlers, models, and integrations to build an evidence-backed feature inventory, user flow map, data entity catalog, and integration manifest.

When to Use This Skill

• Need to understand what an inherited codebase actually does
• Documentation is missing, outdated, or suspected to be inaccurate
• Preparing for a rewrite or major refactor and need a baseline specification
• As input to Architecture Gap Analysis for comparing actual behavior to desired behavior
• When onboarding to a legacy system and need a ground-truth feature inventory

Pipeline Position

[AS_IS_SYSTEM_MODEL.md + Codebase] --> **REVERSE PRD** --> [REVERSE_PRD.md] --> Architecture Gap Analysis --> ...

Input: AS_IS_SYSTEM_MODEL.md, actual codebase (via Read/Glob/Grep) Output: REVERSE_PRD.md written to artifacts directory

Artifact Template

The output artifact follows the standard artifact template:

# [ARTIFACT TITLE]
## Summary
## Inputs
## Outputs
## Assumptions
## Open Questions
## Main Content
## Acceptance Criteria

Process

Step 1: Read As-Is System Model

1. Read AS_IS_SYSTEM_MODEL.md to understand:
   • Component inventory (COMP-NNNN entries)
   • Technology stack and frameworks in use
   • Entry points and exit points
   • Data flow patterns
2. Extract the component list and their entry points for targeted analysis
3. Note any Open Questions from the AS-IS model that may affect requirement extraction

Step 2: Discover Route and Endpoint Definitions

Systematically find all entry points where the system accepts input.

1. HTTP Routes (Grep for framework-specific patterns):

   • Express/Koa: app.get(, app.post(, router.get(, router.post(
   • FastAPI: @app.get(, @app.post(, @router.get(
   • Django: path(, url(, urlpatterns
   • Rails: get ', post ', resources :
   • Spring: @GetMapping, @PostMapping, @RequestMapping
   • Go/Gin: r.GET(, r.POST(, http.HandleFunc(
   • ASP.NET: [HttpGet], [HttpPost], MapGet(

2. CLI Commands (Grep for command registration):

   • argparse, click.command, cobra.Command, clap::Command
   • bin/ directory scripts with shebang lines

3. Message Queue Consumers (Grep for subscription patterns):

   • subscribe(, consume(, on('message', @RabbitListener, @KafkaListener

4. Scheduled Jobs (Grep for cron/scheduler patterns):

   • cron(, schedule(, @Scheduled, setInterval(

5. File/Event Watchers:

   • watch(, on('change', inotify, FileSystemWatcher

6. Record each endpoint:

| Method | Path/Pattern | Handler | Component | Evidence |
|--------|-------------|---------|-----------|----------|
| GET | /api/users | UserController.list | COMP-0001 | [src/routes/users.ts:12] |
| POST | /api/users | UserController.create | COMP-0001 | [src/routes/users.ts:25] |

Step 3: Trace Handler Logic to Extract Features

For each discovered endpoint/entry point, trace the handler logic to understand what the system does.

1. Read handler file at the cited line
2. Follow the call chain: handler -> service -> repository/model -> external calls
3. Identify the feature: What business capability does this handler provide?
4. Record feature with REQ-NNNN ID:

Feature format:

### REQ-0001: [Feature Title]
- **Type**: Functional | Non-Functional | Integration | Administrative
- **Description**: [What this feature does, derived from code behavior]
- **Entry Point**: [HTTP method + path | CLI command | Queue topic]
- **Handler Chain**: [handler -> service -> repository flow with citations]
  > Request enters via POST /api/users [src/routes/users.ts:25]
  > Validated by UserSchema [src/schemas/user.ts:8-22]
  > Processed by UserService.create [src/services/user.ts:34-58]
  > Persisted via UserRepository.save [src/repositories/user.ts:15]
- **Data Entities**: [Models/schemas touched]
- **Side Effects**: [Emails sent, events published, files written]
- **Error Handling**: [How errors are caught and reported]
- **Authentication**: [Required | Optional | None] with evidence
- **Authorization**: [Role/permission checks] with evidence

5. Assign REQ-NNNN IDs: Sort all requirements alphabetically by feature title, then assign sequential four-digit numbers starting at REQ-0001

Step 4: Map User Flows

Trace end-to-end user journeys through the codebase.

1. Identify flow entry points: Login pages, registration forms, main dashboards, API root endpoints
2. Trace each flow:
   • What triggers the flow (user action, system event, scheduled task)
   • What steps occur in sequence
   • What data is read and written at each step
   • What the outcome is (response, side effect, state change)
3. Record as flow diagrams:

#### FLOW-0001: [Flow Name]
```mermaid
sequenceDiagram
    actor User
    User->>API: POST /login [src/routes/auth.ts:10]
    API->>AuthService: validate(credentials) [src/services/auth.ts:22]
    AuthService->>DB: SELECT user [src/repositories/user.ts:8]
    DB-->>AuthService: user record
    AuthService->>AuthService: bcrypt.compare() [src/services/auth.ts:30]
    AuthService-->>API: JWT token [src/services/auth.ts:35]
    API-->>User: 200 + token

4. **Assign FLOW-NNNN IDs**: Sort alphabetically by flow name

### Step 5: Catalog Data Entities

Extract the data model from code, not documentation.

1. **Grep for model/schema definitions**:
   - ORM models: `class.*Model`, `@Entity`, `Schema({`, `model(`, `#[derive(`, `type.*struct`
   - Database schemas: migration files, SQL CREATE TABLE statements
   - API schemas: Zod schemas, Joi validations, Pydantic models, JSON Schema files
   - TypeScript interfaces/types in model directories

2. **For each entity, record**:
```markdown
#### ENT-0001: [Entity Name]
- **Source**: [ORM model | Migration | API schema | TypeScript interface]
- **File**: [file:line]
- **Fields**:
  | Field | Type | Constraints | Evidence |
  |-------|------|------------|----------|
  | id | UUID | Primary Key | [src/models/user.ts:5] |
  | email | string | Unique, Not Null | [src/models/user.ts:8] |
- **Relationships**:
  - Has many: [Entity] via [foreign key] [file:line]
  - Belongs to: [Entity] via [foreign key] [file:line]
- **Indexes**: [If discoverable from migrations]

3. Entity Relationship Diagram:

```mermaid
erDiagram
    USER ||--o{ ORDER : places
    ORDER ||--|{ LINE_ITEM : contains
    PRODUCT ||--o{ LINE_ITEM : "ordered in"

4. **Assign ENT-NNNN IDs**: Sort alphabetically by entity name

### Step 6: Identify Integration Points

Map all external system interactions.

1. **Database connections** (Grep for connection/client initialization):
   - Connection strings, pool configurations, ORM setup
   - Record: database type, connection method, evidence

2. **External API calls** (Grep for HTTP client usage):
   - `fetch(`, `axios.`, `http.get(`, `requests.`, `HttpClient`, `reqwest::`
   - Record: target URL/service, method, purpose, evidence

3. **Message queues** (Grep for publisher/subscriber setup):
   - RabbitMQ, Kafka, SQS, Redis pub/sub, NATS
   - Record: queue/topic names, message formats, evidence

4. **File I/O** (Grep for file system operations):
   - `fs.readFile`, `open(`, `File::open`, `os.Open`
   - Cloud storage: S3, GCS, Azure Blob
   - Record: paths/buckets, read/write, evidence

5. **Email/Notification services**:
   - SMTP, SendGrid, Twilio, push notification services
   - Record: service, trigger conditions, evidence

6. **Integration inventory**:
```markdown
| INT-NNNN | Type | Target | Direction | Evidence |
|----------|------|--------|-----------|----------|
| INT-0001 | Database | PostgreSQL | Bidirectional | [src/db/connection.ts:5] |
| INT-0002 | API | Stripe | Outbound | [src/services/payment.ts:22] |
| INT-0003 | Queue | Redis | Bidirectional | [src/queue/setup.ts:8] |

7. Assign INT-NNNN IDs: Sort alphabetically by target name

Step 7: Detect Dead and Unreachable Code

Identify features that exist in code but may not be reachable.

1. Unreachable routes: Routes defined but commented out or behind always-false feature flags

2. Unused exports: Functions/classes exported but never imported elsewhere

   • Grep for function definitions, then Grep for their usage across the codebase

3. Commented-out code blocks: Large sections of commented code indicating abandoned features

   • Grep for patterns like // TODO, /* deprecated */, # FIXME, # HACK

4. Dead feature flags: Feature flags that are always true or always false

5. Orphaned files: Source files not imported by any other file

6. Record findings:

#### DEAD-0001: [Description]
- **Type**: Unreachable Route | Unused Export | Commented Code | Dead Flag | Orphan File
- **Location**: [file:line]
- **Evidence**: [Why this is considered dead]
- **Risk**: [What breaks if removed]

7. Assign DEAD-NNNN IDs: Sort alphabetically by description

Step 8: Compile Reverse PRD

Assemble all findings into the final artifact.

1. Write REVERSE_PRD.md following the template
2. Verify every claim has [file:line] citation
3. Cross-reference REQ entries with COMP entries from AS_IS_SYSTEM_MODEL.md
4. Flag any components without mapped requirements as Open Questions

Output Format

REVERSE_PRD.md Structure

# Reverse PRD: [Project Name]

## Summary
[3-5 sentence overview of what the system actually does based on code analysis]

## Inputs
- AS_IS_SYSTEM_MODEL.md
- Codebase at: [path]

## Outputs
- REVERSE_PRD.md (this document)

## Assumptions
- [ASM-NNNN]: [Assumption with rationale]

## Open Questions
- [OQ-NNNN]: [Question about ambiguous or unclear behavior]

## Main Content

### Feature Inventory
[REQ-NNNN entries with full detail]

### Feature Summary Table
| REQ ID | Title | Type | Entry Point | Component | Auth Required |
|--------|-------|------|------------|-----------|---------------|

### User Flows
[FLOW-NNNN entries with sequence diagrams]

### Data Entities
[ENT-NNNN entries with field tables]

#### Entity Relationship Diagram
```mermaid
[ER diagram]

Integration Points

[INT-NNNN entries]

Integration Map

[Integration diagram]

Dead Code Inventory

[DEAD-NNNN entries]

Requirements Traceability

REQ ID	Components	Entities	Integrations	Flows
[Cross-reference matrix]

Acceptance Criteria

• Every REQ-NNNN cites handler chain with [file:line] evidence
• All discovered routes/endpoints mapped to REQ entries
• Data entities extracted from code, not documentation
• Integration points list all external dependencies
• Dead code inventory documents unreachable features
• User flows trace entry to exit with evidence
• Traceability matrix cross-references all artifact IDs

**Output path**: `artifacts/brownfield/<project_name>/REVERSE_PRD.md`

**Template**: `${CLAUDE_PLUGIN_ROOT}/reference/templates/REVERSE_PRD.template.md`

## Determinism Rules

These rules ensure reproducible output regardless of when or how many times the skill is invoked on the same inputs.

1. **REQ-NNNN IDs**: Sort all requirements alphabetically by feature title (case-insensitive), then assign sequential four-digit numbers starting at 0001
2. **FLOW-NNNN IDs**: Sort all flows alphabetically by flow name, then assign sequentially
3. **ENT-NNNN IDs**: Sort all entities alphabetically by entity name, then assign sequentially
4. **INT-NNNN IDs**: Sort all integrations alphabetically by target name, then assign sequentially
5. **DEAD-NNNN IDs**: Sort all dead code findings alphabetically by description, then assign sequentially
6. **Entity fields**: Sort by field name alphabetically within each entity
7. **Endpoint table rows**: Sort by Method, then by Path alphabetically
8. **Sections**: Always in template order, never reordered
9. **No timestamps**: Do not include generation timestamps in artifact body
10. **Handler chains**: List in call order (entry -> ... -> exit), not alphabetically

## Evidence Citation Rules

Every claim about system behavior MUST include evidence citations from actual code.

**Format**: `> Claim text [relative/path/to/file.ext:line_number]`

**Examples**:
```markdown
> User creation validates email uniqueness before insert [src/services/user.ts:42]
> Password is hashed with bcrypt, 12 salt rounds [src/auth/hash.ts:8]
> Order total calculation includes tax based on shipping state [src/services/order.ts:88-102]
> Webhook retry logic attempts 3 times with exponential backoff [src/integrations/webhook.ts:15-30]

Rules:

• Single line reference: [file:line]
• Range reference: [file:start-end]
• Multiple files: [file1:line] [file2:line]
• If behavior is ambiguous, cite all relevant files and note ambiguity in Open Questions
• NEVER cite documentation files as evidence for system behavior; only cite source code
• Test files may be cited as supplementary evidence for expected behavior

Quality Checklist

Before finalizing the artifact, verify:

• Every REQ-NNNN has a handler chain with [file:line] citations
• All discovered routes/endpoints are mapped to at least one REQ entry
• No REQ is based solely on documentation without code evidence
• Data entities are extracted from model/schema code, not README claims
• Entity relationships cite foreign key or join evidence
• All external API calls, database connections, and queue interactions are in INT inventory
• Dead code inventory has been populated (even if empty, state "None detected")
• User flows cover at least the primary happy path
• Traceability matrix connects REQ to COMP, ENT, INT, and FLOW
• REQ-NNNN IDs sorted alphabetically by title
• Mermaid diagrams use valid syntax
• Open Questions capture any ambiguous behavior

Error Handling

• AS_IS_SYSTEM_MODEL.md not found: Report error; this skill requires the as-is model as input. Direct user to run codebase-discovery-as-is first
• No routes or endpoints found: Check for non-HTTP entry points (CLI, queue, cron); if truly none found, document as a library/SDK rather than application
• Minified or generated code: Skip; note in Assumptions and focus on source files
• Test-only routes: Include but tag as Type: Test/Debug in the REQ entry
• Feature flag gated code: Include as REQ with note about feature flag status and gate evidence
• Conflicting behavior (multiple code paths for same feature): Document all paths; flag as Open Question for resolution