reverse

# Reverse Engineering Assistant | 反向工程助手 System archeology framework: reverse engineer existing systems across three dimensions — **Logic**, **Data**, and **Runtime**. 系統考古框架：從三個維度反向工程既有系統——**邏輯**、**資料**、**執行環境**。 ## Three Dimensions | 三大維度 ``` ┌─────────────────────────────────────────────────────────┐ │ System Archeology Framework │ ├──────────┬──────────────┬────────────────────────────────┤ │ Logic │ Data │ Runtime │ │ (spec) │ (data) │ (runtime) │ ├──────────┼──────────────┼────────────────────────────────┤ │ APIs │ DB Schemas │ Logs & Error Patterns │ │ Modules │ ORMs/Models │ Config & Environment │ │ Flows │ Migrations │ Metrics & Performance │ │ Tests │ Seed Data │ Infra & Deployment │ └──────────┴──────────────┴────────────────────────────────┘ ``` ## Subcommands | 子命令 | Subcommand | Dimension | Input | Output | 說明 | |------------|-----------|-------|--------|------| | *(none)* | All | Project root | Full Archeology Report | 三維度全面分析 | | `spec` | Logic | Code files/dirs | `SPEC-XXX.md` | 從程式碼提取規格 | | `data` | Data | DB schemas, ORMs, migrations | Data Model Spec | 分析資料模型與結構 | | `runtime` | Runtime | Logs, configs, metrics | Runtime Baseline | 分析執行環境基準 | | `bdd` | — | `SPEC-XXX.md` | `.feature` | 將 AC 轉為 Gherkin | | `tdd` | — | `.feature` | Coverage Report | 分析測試覆蓋率 | ## Full Analysis Mode | 全面分析模式 When `/reverse` is invoked without a subcommand, execute all three dimensions sequentially: 1. **Data** → Scan schemas, ORMs, migrations 2. **Runtime** → Analyze logs, configs, deployment 3. **Logic (spec)** → Extract APIs, flows, tests → Generate SPEC Output: Integrated **System Archeology Report** combining all three dimensions. ## Dimension Details | 維度詳情 ### spec: Logic Dimension (既有) 1. **Scan** - Read source files and identify public APIs, data flows, and business logic 2. **Classify** - Tag each finding as `[Confirmed]`, `[Inferred]`, or `[Unknown]` 3. **Structure** - Organize into SDD spec format with Acceptance Criteria 4. **Attribute** - Cite every reversed item with `file:line` source reference ### data: Data Dimension (新增) 1. **Discover** - Find database schemas, ORM models, migration files, seed data 2. **Map** - Build entity-relationship model from code evidence 3. **Classify** - Tag relationships as `[Confirmed]` (FK constraints) or `[Inferred]` (code patterns) 4. **Report** - Output data model spec with: - Entity list with fields and types - Relationship map (1:1, 1:N, M:N) - Index and constraint inventory - Migration history summary - Data flow paths (write → read) **Evidence sources**: `schema.prisma`, `*.migration.*`, `models/`, `entities/`, `knexfile.*`, `sequelize`, `typeorm`, SQL files, `docker-compose.yml` (DB services) ### runtime: Runtime Dimension (新增) 1. **Scan configs** - Environment variables, config files, feature flags 2. **Analyze logs** - Log patterns, error frequency, log levels 3. **Check infra** - Docker configs, CI/CD pipelines, deployment manifests 4. **Baseline** - Output runtime baseline with: - Environment variable inventory (names only, **never values/secrets**) - Config file map and hierarchy - External service dependencies (APIs, queues, caches) - Deployment topology (containers, services) - Health check and monitoring endpoints **Evidence sources**: `.env.example`, `docker-compose.yml`, `Dockerfile`, `*.config.*`, CI/CD files, `k8s/`, log files (patterns only) **Security**: NEVER output actual secret values. Only list variable names and describe their purpose. ## Anti-Hallucination Rules | 防幻覺規則 | Rule | Requirement | 要求 | |------|-------------|------| | **Certainty Tags** | Use `[Confirmed]`, `[Inferred]`, `[Unknown]` for all findings | 所有發現須標注確定性 | | **Source Attribution** | Cite `file:line` for every reversed item | 每項反向結果須引用來源 | | **No Fabrication** | Never invent APIs or behaviors not found in code | 不得捏造程式碼中不存在的 API 或行為 | | **No Secrets** | Never output secret values from configs or env files | 不得輸出設定檔或環境變數的密鑰值 | ## Usage | 使用方式 ``` /reverse - Full 3-dimension analysis | 三維度全面分析 /reverse spec src/auth/ - Logic: extract spec | 邏輯：提取規格 /reverse data - Data: analyze schemas & models | 資料：分析結構 /reverse runtime - Runtime: analyze configs & infra | 執行環境：分析配置 /reverse bdd specs/SPEC-AUTH.md - Convert spec ACs to Gherkin /reverse tdd features/auth.feature - Analyze test coverage ``` ## Next Steps Guidance | 下一步引導 After `/reverse` (full or `spec`) completes, the AI assistant should suggest: > **系統考古完成。建議下一步 / System archeology complete. Suggested next steps:** > - 執行 `/sdd` 審查並核准此規格 ⭐ **Recommended / 推薦** — Review and approve the generated spec > - 執行 `/derive` 從規格推導測試 — Derive tests from spec (requires approval first) > - 審查規格中的 `[Inferred]` 和 `[Unknown]` 標記 — Review uncertainty tags manually ## Reference | 參考 - [BDD Extraction Workflow Guide](./bdd-extraction.md) — Read it when extracting BDD scenarios out of an existing spec. - [TDD Analysis Workflow Guide](./tdd-analysis.md) — Read it when analysing test coverage against scenarios and finding the gaps. - Step-by-step workflow: [workflow.md](./workflow.md) — the reverse-engineering phases in order (code scanning, data models, configuration, test analysis, coverage). Read it when actually running the process rather than deciding whether to. - Detailed guide: [guide.md](./guide.md) - Core standard: [reverse-engineering-standards.md](../../core/reverse-engineering-standards.md) ## AI Agent Behavior | AI 代理行為 > 完整的 AI 行為定義請參閱對應的命令文件：[`/reverse`](../commands/reverse.md#ai-agent-behavior--ai-代理行為) > > For complete AI agent behavior definition, see the corresponding command file: [`/reverse`](../commands/reverse.md#ai-agent-behavior--ai-代理行為)