# Skill Reverse Engineering

> Regenerate architecture documentation from codebase analysis.

- Skill: `matrixfounder/skill-reverse-engineering` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add matrixfounder/skill-reverse-engineering`
- Raw SKILL.md: https://api.skillmd.com/api/skills/matrixfounder/skill-reverse-engineering/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: MatrixFounder (https://skillmd.com/u/matrixfounder)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/matrixfounder/skill-reverse-engineering

---

# Reverse Engineering Skill

## Purpose
Recover the mental model of a project from its codebase when documentation is outdated or missing.

## When to Use
- Documentation-code mismatch detected
- New team member onboarding
- Post-"quick fix" cleanup

## Strategy: Automated Scan + Iterative Analysis

### Phase 1: Automated Directory Scan
**Tool:** `scripts/scan_structure.py`

**Usage:**
```bash
python3 .agent/skills/skill-reverse-engineering/scripts/scan_structure.py . --depth 2
```

**Goal:**
- Get high-level overview of project structure.
- Identify dominant languages and components.
- Avoid context overflow by NOT reading all files.

### Phase 2: Local Analysis (Per-Directory)
For each key component identified in Phase 1:
1. List files.
2. Sample 2-3 representative files (read content).
3. Generate **Local Summary**:
   - Purpose
   - Key Classes
   - Dependencies

### Phase 3: Global Synthesis
Combine local summaries to update `docs/ARCHITECTURE.md`:
- Update **Directory Structure**
- Update **Component Map**
- Identify **Architecture Drift** (Code != Docs)

## Output Artifacts

### 1. ARCHITECTURE.md Update
Generate diffs for:
- Directory Structure
- Component Map
- Data Flow

### 2. KNOWN_ISSUES.md Updates
Identify:
- `TODO`/`HACK` comments indicating tech debt.
- Discrepancies between implementation and docs.

**Filing format (thin index).** `docs/KNOWN_ISSUES.md` is a hand-maintained **thin index**, not a
flat checklist — do **NOT** append `- [ ]` lines to it. The authoritative format contract lives in the
**`known-issues-format`** skill (`artifact-management`, TIER 0, delegates to it) — follow it:
1. If `docs/KNOWN_ISSUES.md` does not exist yet, materialize it from
   `known-issues-format`'s `assets/templates/known_issues_md_template.md` first (create-if-absent).
2. File each finding as its own `docs/issues/<slug>.md` (frontmatter + H1 + body) **plus** one index
   line under the matching `## <category>` heading — edit both **in lockstep**.
3. If a finding needs a category/prefix the project's ledger doesn't have yet, add a new
   **prefix → category** row to that ledger's *Rules / Conventions* table before filing.

(The "Append new findings, do not delete existing rationale" protection in **Human Knowledge
Preservation** below still applies to the per-issue bodies.)

## Human Knowledge Preservation

> [!CAUTION]
> **Never overwrite architectural rationale written by humans.**

**Protected patterns:**
- `<!-- HUMAN KNOWLEDGE -->`
- `> **Design Decision:**`

**Strategy:** Append new findings, do not delete existing rationale.

## Integration
- **With `skill-update-memory`**: After analysis, run bootstrap mode to create missing `.AGENTS.md` files where needed.
- **Workflow `04-update-docs`**: Run this skill if docs drift is detected.