Reverse Engineer（Route-Aware）是 StackShift 逆向工程到规格驱动开发（Reverse Engineering to Spec-Driven Development）流程中的第 2 步，共 6 步：1. 分析，2. 逆向工程（本技能），3. 创建规格，4. 差距分析，5. 实施规划，6. 实施。预计耗时 30-45 分钟。前置条件是第 1 步已完成，即已生成 analysis-report.md 并在 .stackshift-state.json 中完成路线选择。输出为 docs/reverse-engineering/ 目录下的 11 份文档。
路线相关行为：Greenfield 路线仅提取业务逻辑（与框架无关）；Brownfield 路线提取业务逻辑加技术实现细节。无论采用哪种实现框架（Spec Kit、BMAD 或 BMAD Auto-Pilot），输出内容相同，框架选择只影响第 2 步之后发生的事情。
配置检查：技能首先验证状态文件是否存在。若 .stackshift-state.json 不存在，则报错并提示必须先完成第 1 步（初始分析），可运行 /stackshift.analyze 开始。随后从状态文件中读取 detection_type 和 route，若缺失则报错并提示重新运行 /stackshift.analyze。还会读取 config.spec_output_location（默认 "."），若非 "." 则创建 $SPEC_OUTPUT/docs/reverse-engineering 和 $SPEC_OUTPUT/.specify/memory/specifications 目录。状态文件结构示例包含 detection_type、route、implementation_framework 以及 config 中的 spec_output_location、build_location、target_stack。技能还会捕获提交哈希用于增量更新：COMMIT_HASH=$(git rev-parse HEAD 2>/dev/null || echo "unknown")，COMMIT_DATE=$(git log -1 --format=%ci 2>/dev/null || date -u +"%Y-%m-%d %H:%M:%S")。
提取方式取决于 detection 与 route 的组合：Monorepo Service 在 Greenfield 下仅提取业务逻辑（技术无关），在 Brownfield 下提取完整实现加共享包（技术规定性）；Nx App 在 Greenfield 下仅提取业务逻辑（框架无关），在 Brownfield 下提取完整 Nx/Angular 实现细节；Generic App 在 Greenfield 下仅提取业务逻辑，在 Brownfield 下提取完整实现。detection_type 决定要查找哪些模式（共享包、Nx 项目配置、monorepo 结构等），route 决定如何记录它们（技术无关 vs 技术规定性）。
阶段 1：深度代码库分析。使用 Task 工具，subagent_type=stackshift:stackshift-code-analyzer:AGENT 执行分析；若该 agent 不可用，则回退到 Explore agent。错误恢复：若某个子代理失败或某个子阶段返回空结果，用 Explore agent 重试一次；若重试仍失败，则用 [ANALYSIS INCOMPLETE] 标记记录缺口并继续其余子阶段。缺失组件：若某子阶段未找到相关代码（例如仅后端服务中没有前端），则在对应输出文件中记录该缺失，而不是跳过该子阶段。子阶段 1.1 至 1.6 通过独立的子代理调用并行启动，收集所有结果后再进入阶段 2。
1.1 后端分析：查找所有 API 端点并记录其方法、路由、认证要求、参数和用途；编目每个数据模型，包括 schema、类型、接口和字段定义；清点所有配置来源：环境变量、配置文件和设置；映射每个外部集成：API、服务和数据库；从服务、工具和算法中提取业务逻辑。
1.2 前端分析：列出所有页面和路由及其用途和认证要求；按类别编目所有组件：布局、表单和 UI 组件；记录状态管理：store 结构和全局状态模式；映射 API 客户端层：前端如何调用后端；提取样式模式：设计系统、主题和组件样式。
1.3 基础设施分析：记录部署配置：IaC 工具、云提供商和服务；映射 CI/CD 流水线和工作流；编目数据库设置：类型、schema 和迁移；识别存储系统：对象存储、文件系统和缓存。
1.4 测试分析：定位所有测试文件并识别所用测试框架；按类型分类测试：单元、集成和 E2E；按模块估算覆盖率百分比；编目测试数据：mock、fixture 和种子数据。
1.5 业务上下文分析：阅读 README、CONTRIBUTING 以及任何营销或落地页；提取包描述和仓库元数据；识别指示用户面向功能的注释模式；收集错误消息和用户面向字符串以推断用户画像；分析命名约定以揭示领域概念；检查 git 历史进行决策考古。
1.6 决策考古：检查依赖清单（package.json、go.mod、requirements.txt）以了解技术选择；分析配置文件（tsconfig、eslint、prettier）以了解设计理念；审查 CI/CD 配置以了解部署决策；对关键架构文件运行 git blame 以识别决策点；收集带有 "why" 解释的注释（TODO、HACK、FIXME、NOTE）；查找 git 历史或注释中可见的被拒绝的替代方案。
进度信号：所有子阶段完成后，记录："Phase 1 complete: Analysis gathered for [list which sub-phases produced results]."
阶段 2：生成文档。创建 docs/reverse-engineering/ 目录并生成全部 11 份文档文件。对每个文件，按 operations/output-file-specs.md 中所述应用 greenfield 或 brownfield 变体。若 .stackshift-docs-meta.json 已存在，则用新元数据完全覆盖。
步骤 2.1：先写元数据文件。写入 docs/reverse-engineering/.stackshift-docs-meta.json，包含 commit_hash、commit_date、generated_at、doc_count（11）、route，以及 docs 对象中 11 个文件各自的 generated_at 和 commit_hash。
步骤 2.2：为每份文档添加元数据头。每份生成的文档在标题后以如下头部开始：
[Document Title]
Generated by StackShift | Commit:
<short-hash>| Date:<GENERATED_AT>Run/stackshift.refresh-docsto update with latest changes.
步骤 2.3：带检查点生成文件。按顺序生成并记录进度： 批次 1（核心架构）：functional-specification.md、data-architecture.md、integration-points.md、configuration-reference.md。写完文件 1-4 后记录："Generated 4/11 files (core architecture complete)." 继续前验证输出目录包含 4 个文件。 批次 2（运维与质量）：operations-guide.md、technical-debt-analysis.md、observability-requirements.md、visual-design-system.md、test-documentation.md。写完文件 5-9 后记录："Generated 9/11 files (operations and quality complete)." 继续前验证输出目录包含 9 个文件。 批次 3（上下文与决策）：business-context.md、decision-rationale.md。写完文件 10-11 后记录："Generated 11/11 files. Phase 2 complete."
输出结构：docs/reverse-engineering/ 下包含 .stackshift-docs-meta.json、functional-specification.md、integration-points.md、configuration-reference.md、data-architecture.md、operations-guide.md、technical-debt-analysis.md、observability-requirements.md、visual-design-system.md、test-documentation.md、business-context.md、decision-rationale.md。
成功标准：全部 11 份文档生成在 docs/reverse-engineering/；全面覆盖应用所有方面；框架无关的功能规格（greenfield）；完整的数据模型文档；业务上下文捕获并带有清晰的 [INFERRED] / [NEEDS USER INPUT] 标记；决策理由以 ADR 格式记录；集成点完全映射并带数据流图；.stackshift-docs-meta.json 创建并含提交哈希以支持增量更新；每份文档都有含提交哈希和生成日期的元数据头。
下一步：所有文档生成后，对于 GitHub Spec Kit（implementation_framework: speckit），进入第 3 步——使用 /stackshift.create-specs 将文档转换为 .specify/ 规格。对于 BMAD Method（implementation_framework: bmad），进入第 6 步——移交给 BMAD 的 *workflow-init；BMAD 的 PM 和 Architect agent 使用逆向工程文档作为上下文。对于 BMAD Auto-Pilot（implementation_framework: bmad-autopilot），进入 /stackshift.bmad-synthesize 自动生成 BMAD 工件；11 份逆向工程文档提供 BMAD 所需约 90% 的内容。
DO / DON'T：DO——描述系统做什么（WHAT），而非怎么做（HOW），尤其对 greenfield；使用所有可用信号进行推断：README、注释、命名、配置、git 历史；标记置信度：无标记=确信，[INFERRED]=合理推断，[NEEDS USER INPUT]=确实未知；文档间交叉引用（例如技术债影响权衡）；为每个推断引用具体证据。DON'T——在功能规格中硬编码框架名称（greenfield）；将业务逻辑与技术实现混在一起（greenfield）；在没有支持证据的情况下编造业务目标；将推断陈述为事实而不加标记；因为需要推断而跳过某节——应尝试并标记置信度。
完整性检查清单：验证分析捕获了所有 API 端点（不只是明显的那些）、所有数据模型（包括 DTO、类型、接口）、所有配置选项（检查多个文件）、所有外部集成、所有用户面向字符串和错误消息（用于用户画像/上下文推断）、所有配置文件（用于决策理由推断）。每份文档必须全面、准确、有条理、可操作，并诚实区分推断与已验证信息。