reverse-adr

Files (1)

• SKILL.md

SKILL.md (first lines)

# Reverse ADR — Architecture Decision Records from Code

Detect architectural decisions that have already been made in this codebase and produce documented ADRs explaining what was chosen and why (inferred from code patterns, library choices, and structure).

## When to Use

- Project has no ADRs or DECISIONS.md
- New team members need to understand *why* things are the way they are
- Preparing to evaluate changing an architectural decision
- Creating a brownfield knowledge transfer document

## What Makes a Good Reverse ADR

An ADR is worth writing when:
- A technology, library, or pattern was chosen over a notable alternative
- A structural decision affects how the whole system is organized
- The choice has trade-offs worth understanding
- Understanding it helps prevent someone from accidentally reversing it

## Step 1: Identify Decision Points

Scan the codebase for these high-signal decision indicators:

**Dependency choices** (read `package.json`, `pyproject.toml`, etc.):
- ORM selection (Prisma vs TypeORM vs raw SQL vs Mongoose)
- Auth library (Passport vs JWT-only vs Auth0 vs NextAuth)
- Validation library (Zod vs Joi vs class-validator vs Pydantic)
- HTTP client (axios vs fetch vs got)
- Testing framework (Jest vs Vitest vs Mocha)
- State management (Redux vs Zustand vs MobX vs Jotai)

**Structural decisions** (read directory layout + imports):
- Layered architecture vs feature folders vs domain-driven structure
- Monorepo vs single package
- REST vs GraphQL vs gRPC choice
- Synchronous vs async/event-driven design
- Database per service vs shared database (if microservices)

**Configuration decisions**:
- TypeScript strict mode (read `tsconfig.json`)
- Environment management approach (.env vs vault vs cloud config)
- Docker vs bare metal vs serverless deployment

**Pattern decisions**:
- Dependency injection vs direct imports
- Repository pattern vs active record
- DTO pattern vs direct entity exposure
- Error handling strategy (exceptions vs Result types vs error codes)

---

## Step 2: For Each Decision, Gather Evidence

For each decision identified, collect:

```
Decision: {Name}
Evidence files: [{file1}, {file2}]
What was chosen: {the actual choice made}
What was NOT chosen: {notable alternatives not present}
Signals suggesting why: {code comments, config settings, patterns}
Confidence: High (explicit) | Medium (inferred) | Low (speculative)
```

**High confidence** = explicit config, comment, or highly specific library version  
**Medium confidence** = consistent pattern across files without explicit statement  
**Low confidence** = only guessable from indirect signals  

---

## Step 3: Write ADRs

Write to: `{project-root}/docs/decisions/`

Create one file per decision: `ADR-001-{kebab-case-title}.md`

Also create an index: `{project-root}/docs/DECISIONS.md`

**ADR Template:**

```markdown
# ADR-{nnn}: {Decision Title}

**Status:** Active (reverse-engineered — not verified with original authors)  
**Date:** {approximate — use earliest relevant commit or "unknown"}  
**Confidence:** {High | Medium | Low}  
**Evidence:** `{primary source file(s)}`

---

## Context

{What situation prompted this decision? Inferred from the codebase context — e.g., "This is a REST API serving a React frontend. An ORM was needed to manage a PostgreSQL database."}

## Decision

**Chosen:** {Prisma as the ORM}

{1–2 sentences describing what was chosen and how it's used}

## Observed Evidence

- `{prisma/schema.prisma}` — primary schema definition in Prisma SDL format
- `{src/repositories/}` — all database queries written using Prisma Client
- `{package.json}` — `@prisma/client` is a production dependency, `prisma` is a dev dependency
- {No TypeORM, Sequelize, or raw SQL found anywhere in the codebase}

## Likely Reasoning

{Based on the code patterns, the likely reason for this choice was:}

1. {Type-safe database queries — Prisma generates typed client from schema}
2. {Schema-first development — migrations managed by Prisma Migrate}
3. {Good TypeScript ergonomics — common choice in the TypeScript ecosystem circa 2022–present}

**Alternatives not chosen:** TypeORM (no `typeorm` in dependencies), Sequelize (no `sequelize`), raw `pg` queries.

## Trade-offs

From superMLdev/smart-sdlc, MIT.

More from superMLdev/smart-sdlc