drive-to-legacy

Files (2)

• SKILL.md
• diagram-convention.md · references/

SKILL.md (first lines)

# Drive to Legacy - Systematic Legacy Code Exploration

## Overview

A 6-phase systematic approach to fully understand an unfamiliar codebase, producing a comprehensive architecture document with mermaid diagrams that both humans and AI can use for porting, migration, or onboarding.

**Core principle:** Explore wide before deep. Map the full territory first, then drill into each layer. Every finding goes into a living ARCHITECTURE.md with diagrams.

## When to Use

- Onboarding to an unfamiliar codebase
- Preparing to port or rewrite an application
- Documenting a legacy system that lacks documentation
- Studying code you need to maintain but did not write
- Any "how does this work?" question about a full project

**When NOT to use:**
- Small bug fixes in code you already understand
- Greenfield projects (no legacy to explore)
- Single-file scripts or utilities

## The 6 Phases

Follow these phases in order. Each phase builds on the previous. Use parallel Explore agents where possible to speed up discovery.

### Phase 1: User Stories

**Goal:** Describe WHAT the app does from the user's perspective. This comes first because it answers "why does this app exist?" — the context that makes all technical details meaningful.

1. Read `package.json` / `README.md` to understand the app's purpose
2. Read entry points and main container components to identify the UI flow
3. Walk through component render methods to find every user action
4. Trace each action to its handler and side effects
5. Note conditional paths (different behavior for different roles or data states)

**Write to ARCHITECTURE.md:**
- Section: "User Stories" with one subsection per story
- Each story: user story statement + mermaid `sequenceDiagram` showing the interaction

**Template per story:**
```markdown
### US-XX: Story Title

AS A [role]
I WANT TO [action]
SO THAT [outcome]

(mermaid sequence diagram)
```

### Phase 2: Project Identity and Component Map

**Goal:** Know the tech stack, file layout, and component tree.

1. Read build config (`vite.config.ts`, `webpack.config.js`, `tsconfig.json`, etc.)
2. List the top-level directory structure
3. Glob for all source files to see the shape: `**/*.tsx`, `**/*.ts`, `**/*.vue`, etc.
4. Read each main component/module entry point (not every file, just the key ones)
5. Trace the component hierarchy from root down
6. Identify reusable/shared components vs. page-specific ones

**Write to ARCHITECTURE.md:**
- Section: "What This App Does" (3 sentences max)
- Section: "Tech Stack and Key Dependencies" (bullet list)
- Section: "File-to-Responsibility Map" (tree with one-line descriptions)
- Section: "Component Hierarchy" (mermaid `graph TD` diagram)
- Section: "State Management Overview" (mermaid diagram showing where state lives)

### Phase 3: Data Model

**Goal:** Understand every entity, type, and relationship.

1. Read all type/interface/model files
2. Read the service/API layer to find all entities referenced
3. Map relationships between entities (foreign keys, lookups, joins)
4. Identify choice/enum fields and their values

**Capture:**
- Every TypeScript interface / database model / API schema
- Entity relationships (one-to-many, many-to-many)
- Key constants and magic numbers with their meanings

**Write to ARCHITECTURE.md:**
- Section: "CRM/Database Entity Relationship Diagram" (mermaid `erDiagram` with field lists)
- Section: "Key Constants and Option Set Values" (table)

### Phase 4: Business Logic

**Goal:** Extract every rule, validation, cascade, and conditional behavior.

This is the deepest phase. Read line by line through:
1. **Form validation rules** - what is required, when, why
2. **Field cascade logic** - selecting A resets B, populates C
3. **Conditional rendering** - what shows/hides and when
4. **Data transformation** - how input maps to output on save
5. **Silent fallbacks** - what happens when data is missing (nullability chains)

**Write to ARCHITECTURE.md:**
- Section: "Business Logic and Rules" with subsections for each rule domain
- Use mermaid `flowchart TD` for decision trees
- Use tables for validation rules and field mappings
- Include a "Nullability and Silent Fallbacks" table (what can be undefined and what happens)
- Include an "Auto-Population Rules" section (what triggers auto-fill of which fields)

### Phase 5: API Reference

**Goal:** Document every data query with exact parameters, filters, joins, and purpose.

**CRITICAL RULE: Every API endpoint MUST have a Why row.** The Why explains the business reason the data is needed - not just "fetches X from Y" but why the application cannot function without this call. Without Why, a developer porting the code cannot tell which APIs are essential vs. nice-to-have, or what would break if the API were removed or changed.

For each service method / API call:
1. Read the exact query (SQL, FetchXml, OData, GraphQL, REST URL)
2. Document parameters, entity, joins, filters
3. Note when it is called and by which component
4. **Explain WHY it exists** (business purpose, not just technical description)

**The Why row must answer:** "What business goal does this query serve? What breaks or becomes impossible without it?"

**Good Why examples:**

From ThodsaphonSonthiphin/workflow-daily-work, MIT.

More from ThodsaphonSonthiphin/workflow-daily-work