investigate

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Feature Investigation

功能调查

READ-ONLY exploration skill for understanding existing features. No code changes.

用于理解现有功能的只读探索技能。不修改代码。

Summary

概述

Goal: READ-ONLY exploration of existing features and logic — understand how code works without making changes.

Step	Action	Key Notes
1	Discovery	Search codebase for related files (Entities > Commands > Events > Controllers)
2	Knowledge Graph	Read and document purpose, symbols, dependencies per file
3	Flow Mapping	Trace entry points through pipeline to exit points
4	Analysis	Extract business rules, validation, authorization, error handling
5	Synthesis	Write executive summary with key files and flow diagrams
6	Present	Deliver findings, offer deeper dives on subtopics

Key Principles:

Strictly READ-ONLY — no code changes allowed
MUST read anti-hallucination-protocol.md and knowledge-graph-template.md before starting
Evidence-based: validate every assumption with actual code references

目标： 对现有功能和逻辑进行只读探索——在不修改代码的前提下理解代码的工作原理。

步骤	操作	关键说明
1	发现	在代码库中搜索相关文件（实体 > 命令 > 事件 > 控制器）
2	知识图谱	读取并记录每个文件的用途、符号、依赖关系
3	流映射	追踪从入口点到出口点的完整流程
4	分析	提取业务规则、验证逻辑、授权机制、错误处理
5	综合	撰写包含关键文件和流程图的执行摘要
6	呈现	交付调查结果，针对子主题提供深入探讨

核心原则：

严格只读——不允许修改任何代码
开始前必须阅读anti-hallucination-protocol.md和knowledge-graph-template.md
基于证据：所有假设必须通过实际代码引用验证

Mode Selection

模式选择

Mode	Use When	Workflow
Interactive	User available, exploratory question	Real-time collaboration, iterative tracing
Autonomous	Deep analysis, complex cross-service tracing	Structured 4-phase workflow with analysis artifact

模式	使用场景	工作流
交互式	用户在场，进行探索性提问	实时协作，迭代式追踪
自主式	深度分析、复杂跨服务追踪	结构化的4阶段工作流，生成分析成果

Workflow

工作流

Discovery - Search codebase for all files related to the feature/question. Prioritize: Entities > Commands/Queries > EventHandlers > Controllers > Consumers > Components.
Knowledge Graph - Read and analyze each file. Document purpose, symbols, dependencies, data flow. Batch in groups of 10, update progress after each batch.
Flow Mapping - Trace entry points through processing pipeline to exit points. Map data transformations, persistence, side effects, cross-service boundaries.
Analysis - Extract business rules, validation logic, authorization, error handling. Document happy path and edge cases.
Synthesis - Write executive summary answering the original question. Include key files, patterns used, and text-based flow diagrams.
Present - Deliver findings using the structured output format. Offer deeper dives on subtopics.

发现 - 在代码库中搜索与功能/问题相关的所有文件。优先顺序：实体 > 命令/查询 > 事件处理程序 > 控制器 > 消费者 > 组件。
知识图谱 - 读取并分析每个文件。记录用途、符号、依赖关系、数据流。以10个文件为一组进行批量处理，每组完成后更新进度。
流映射 - 追踪从入口点到出口点的处理流程。记录数据转换、持久化、副作用、跨服务边界。
分析 - 提取业务规则、验证逻辑、授权机制、错误处理。记录正常流程和边缘情况。
综合 - 撰写回答原始问题的执行摘要，包含关键文件、使用的模式和基于文本的流程图。
呈现 - 以结构化输出格式交付调查结果，针对子主题提供深入探讨。

⚠️ MUST READ Before Investigation

⚠️ 调查前必读

IMPORTANT: You MUST read these files before starting. Do NOT skip.

⚠️ MUST READ
```
.claude/skills/shared/anti-hallucination-protocol.md
```
— Assumption validation, evidence chains, context anchoring

⚠️ MUST READ

.claude/skills/shared/knowledge-graph-template.md

— Per-file analysis structure

If preceded by
/scout
: Use Scout's numbered file list as analysis targets. Skip redundant discovery. Prioritize HIGH PRIORITY files first.

重要提示：开始前必须阅读以下文件，请勿跳过。

⚠️ 必读
```
.claude/skills/shared/anti-hallucination-protocol.md
```
— 假设验证、证据链、上下文锚定

⚠️ 必读

.claude/skills/shared/knowledge-graph-template.md

— 单文件分析结构

如果以
/scout
开头：使用Scout提供的编号文件列表作为分析目标，跳过重复的发现步骤。优先处理高优先级文件。

Investigation Techniques

调查技巧

Discovery Search Patterns

发现搜索模式

File Discovery by Feature Name

按功能名称发现文件

regex

.*EventHandler.*{FeatureName}|{FeatureName}.*EventHandler
.*BackgroundJob.*{FeatureName}|{FeatureName}.*BackgroundJob
.*Consumer.*{FeatureName}|{FeatureName}.*Consumer
.*Service.*{FeatureName}|{FeatureName}.*Service
.*Component.*{FeatureName}|{FeatureName}.*Component

regex

.*EventHandler.*{FeatureName}|{FeatureName}.*EventHandler
.*BackgroundJob.*{FeatureName}|{FeatureName}.*BackgroundJob
.*Consumer.*{FeatureName}|{FeatureName}.*Consumer
.*Service.*{FeatureName}|{FeatureName}.*Service
.*Component.*{FeatureName}|{FeatureName}.*Component

Priority Order for Analysis

分析优先顺序

Domain Entities - Core business objects
Commands/Queries - CQRS entry points (
```
UseCaseCommands/
```
,
```
UseCaseQueries/
```
)
Event Handlers - Side effects (
```
UseCaseEvents/
```
,
```
*EventHandler.cs
```
)
Controllers - API endpoints (
```
Controllers/
```
,
```
*Controller.cs
```
)
Consumers - Cross-service (
```
*Consumer.cs
```
,
```
*BusMessage.cs
```
)
Background Jobs - Scheduled processing (
```
*BackgroundJob*.cs
```
,
```
*Job.cs
```
)
Components/Stores - Frontend (
```
*.component.ts
```
,
```
*.store.ts
```
)
Services/Helpers - Supporting logic (
```
*Service.cs
```
,
```
*Helper.cs
```
)

领域实体 - 核心业务对象
命令/查询 - CQRS入口点（
```
UseCaseCommands/
```
、
```
UseCaseQueries/
```
）
事件处理程序 - 副作用（
```
UseCaseEvents/
```
、
```
*EventHandler.cs
```
）
控制器 - API端点（
```
Controllers/
```
、
```
*Controller.cs
```
）
消费者 - 跨服务（
```
*Consumer.cs
```
、
```
*BusMessage.cs
```
）
后台作业 - 调度处理（
```
*BackgroundJob*.cs
```
、
```
*Job.cs
```
）
组件/存储 - 前端（
```
*.component.ts
```
、
```
*.store.ts
```
）
服务/助手 - 支持逻辑（
```
*Service.cs
```
、
```
*Helper.cs
```
）

Dependency Tracing

依赖追踪

Backend (C#)

后端（C#）

Looking for	Search pattern
Who calls this method	Grep method name across `*.cs`
Who injects this service	Grep interface name in constructors
What events this entity raises	Grep `PlatformCqrsEntityEvent<EntityName>`
Cross-service consumers	Grep `*BusMessage` type across all services
Repository usage	Grep `IRepository<EntityName>` or `IPlatformQueryableRootRepository<EntityName`

查找目标	搜索模式
谁调用了此方法	在所有 `*.cs` 文件中搜索方法名
谁注入了此服务	在构造函数中搜索接口名
此实体触发了哪些事件	搜索 `PlatformCqrsEntityEvent<EntityName>`
跨服务消费者	在所有服务中搜索 `*BusMessage` 类型
仓储使用情况	搜索 `IRepository<EntityName>` 或 `IPlatformQueryableRootRepository<EntityName`

Frontend (TypeScript)

前端（TypeScript）

Looking for	Search pattern
Who uses this component	Grep selector `app-component-name` in `*.html`
Who imports this service	Grep service class name in `*.ts`
Store effects chain	Trace `effectSimple` -> API call -> `tapResponse` -> state update
Route entry	Grep component name in `routing.ts`

查找目标	搜索模式
谁使用了此组件	在 `*.html` 中搜索选择器 `app-component-name`
谁导入了此服务	在 `*.ts` 中搜索服务类名
存储效果链	追踪 `effectSimple` -> API调用 -> `tapResponse` -> 状态更新
路由入口	在 `routing.ts` 中搜索组件名

Data Flow Mapping

数据流映射

Document flow as text diagram:

text

[Entry Point] --> [Step 1: Validation] --> [Step 2: Processing] --> [Step 3: Persistence]
                                                  |
                                                  v
                                          [Side Effect: Event]

以文本图形式记录流程：

text

[Entry Point] --> [Step 1: Validation] --> [Step 2: Processing] --> [Step 3: Persistence]
                                                  |
                                                  v
                                          [Side Effect: Event]

Flow Documentation Checklist

流程文档检查清单

Entry Points - API endpoint, UI action, scheduled job, message bus
Processing Pipeline - Step-by-step through handlers
Data Transformations - How data changes at each step
Persistence Points - Where data is saved/loaded
Exit Points - Responses, events, side effects
Cross-Service Flows - Message bus boundaries

入口点 - API端点、UI操作、调度作业、消息总线
处理流程 - 逐步追踪处理程序
数据转换 - 数据在每个步骤的变化方式
持久化点 - 数据保存/加载的位置
出口点 - 响应、事件、副作用
跨服务流程 - 消息总线边界

Common Investigation Scenarios

常见调查场景

"How does feature X work?"

"功能X是如何工作的？"

Find entry points (API, UI, job)
Trace through command/query handlers
Document entity changes
Map side effects (events, notifications)

找到入口点（API、UI、作业）
追踪命令/查询处理程序
记录实体变化
映射副作用（事件、通知）

"Where is the logic for Y?"

"Y的逻辑在哪里？"

Search keywords in commands, queries, entities
Check event handlers for side effect logic
Look in helper/service classes
Check frontend stores and components

在命令、查询、实体中搜索关键词
检查事件处理程序中的副作用逻辑
查看助手/服务类
检查前端存储和组件

"What happens when Z occurs?"

"当Z发生时会发生什么？"

Identify trigger (user action, event, schedule)
Trace the handler chain
Document all side effects
Map error handling

识别触发因素（用户操作、事件、调度）
追踪处理程序链
记录所有副作用
映射错误处理

"Why does A behave like B?"

"为什么A的行为像B？"

Find the relevant code path
Identify decision points
Check configuration/feature flags
Document business rules

找到相关代码路径
识别决策点
检查配置/功能标志
记录业务规则

Platform Pattern Recognition

平台模式识别

Backend Patterns

后端模式

```
PlatformCqrsCommand
```
/
```
PlatformCqrsQuery
```
- CQRS entry points

PlatformCqrsEntityEventApplicationHandler

- Side effects

```
PlatformApplicationMessageBusConsumer
```
- Cross-service consumers
```
IPlatformQueryableRootRepository
```
- Data access
```
PlatformValidationResult
```
- Validation logic
```
[PlatformAuthorize]
```
- Authorization

```
PlatformCqrsCommand
```
/
```
PlatformCqrsQuery
```
- CQRS入口点

PlatformCqrsEntityEventApplicationHandler

- 副作用

```
PlatformApplicationMessageBusConsumer
```
- 跨服务消费者
```
IPlatformQueryableRootRepository
```
- 数据访问
```
PlatformValidationResult
```
- 验证逻辑
```
[PlatformAuthorize]
```
- 授权

Frontend Patterns

前端模式

```
AppBaseVmStoreComponent
```
- State management components
```
PlatformVmStore
```
- Store implementations
```
effectSimple
```
/
```
tapResponse
```
- Effect handling
```
observerLoadingErrorState
```
- Loading/error states
API services extending
```
PlatformApiService
```

```
AppBaseVmStoreComponent
```
- 状态管理组件
```
PlatformVmStore
```
- 存储实现
```
effectSimple
```
/
```
tapResponse
```
- 效果处理
```
observerLoadingErrorState
```
- 加载/错误状态
继承
```
PlatformApiService
```
的API服务

Evidence Collection

证据收集

Analysis File Setup

分析文件设置

Autonomous mode writes analysis to

.ai/workspace/analysis/[feature-name]-investigation.md

with:

markdown

undefined

自主模式下，分析结果将写入

.ai/workspace/analysis/[feature-name]-investigation.md

，格式如下：

markdown

undefined

Metadata

Original question: [user's exact question]

Investigation Question

[Clearly stated investigation goal]

Progress

Phase: 1
Items Processed: 0 / [total]
Current Focus: [original question]

Phase: 1
Items Processed: 0 / [total]
Current Focus: [original question]

File List

[All discovered files, grouped by priority]

Knowledge Graph

[Per-file analysis entries - see template below]

Data Flow

[Flow diagrams and pipeline documentation]

Findings

[Populated in Phase 2+]

undefined

[Populated in Phase 2+]

undefined

Per-File Analysis Entry

单文件分析条目

For each file, document in

## Knowledge Graph

对于每个文件，在

## Knowledge Graph

中记录：

Core Fields

核心字段

```
filePath
```
: Full path
```
type
```
: Component classification (Entity, Command, Handler, Controller, Component, Store, etc.)
```
architecturalPattern
```
: Design pattern used
```
content
```
: Purpose and logic summary
```
symbols
```
: Key classes, interfaces, methods
```
dependencies
```
: Imports/injections
```
relevanceScore
```
: 1-10 (to investigation question)
```
evidenceLevel
```
: "verified" or "inferred"

```
filePath
```
: 完整路径
```
type
```
: 组件分类（实体、命令、处理程序、控制器、组件、存储等）
```
architecturalPattern
```
: 使用的设计模式
```
content
```
: 用途和逻辑摘要
```
symbols
```
: 关键类、接口、方法
```
dependencies
```
: 导入/注入项
```
relevanceScore
```
: 1-10（与调查问题的相关性）
```
evidenceLevel
```
: "verified"或"inferred"

Investigation-Specific Fields

调查特定字段

```
entryPoints
```
: How this code is triggered/called
```
outputPoints
```
: What this code produces/returns
```
dataTransformations
```
: How data is modified
```
conditionalLogic
```
: Key decision points and branches
```
errorScenarios
```
: What can go wrong, error handling
```
externalDependencies
```
: External services, APIs, databases

```
entryPoints
```
: 此代码的触发/调用方式
```
outputPoints
```
: 此代码生成/返回的内容
```
dataTransformations
```
: 数据的修改方式
```
conditionalLogic
```
: 关键决策点和分支
```
errorScenarios
```
: 可能出现的问题及错误处理
```
externalDependencies
```
: 外部服务、API、数据库

Cross-Service Fields (if applicable)

跨服务字段（如适用）

```
messageBusMessage
```
: Message type consumed/produced
```
messageBusProducers
```
: Who sends this message
```
crossServiceIntegration
```
: Cross-service data flow

Rule: After every 10 files, update progress and re-check alignment with original question.

```
messageBusMessage
```
: 消费/生产的消息类型
```
messageBusProducers
```
: 发送此消息的对象
```
crossServiceIntegration
```
: 跨服务数据流

规则： 每处理10个文件后，更新进度并重新检查与原始问题的一致性。

Structured Findings Format

结构化结果格式

Phase 2: Comprehensive Analysis

阶段2：综合分析

Workflow Analysis

工作流分析

Happy Path - Normal successful execution flow
Error Paths - How errors are handled at each stage
Edge Cases - Special conditions
Authorization - Permission checks
Validation - Input validation at each layer

正常流程 - 正常成功执行的流程
错误流程 - 每个阶段的错误处理方式
边缘情况 - 特殊条件
授权 - 权限检查
验证 - 各层的输入验证

Business Logic Extraction

业务逻辑提取

Core Business Rules - What rules govern this feature
State Transitions - Entity state changes
Side Effects - Notifications, events, external calls

核心业务规则 - 管理此功能的规则
状态转换 - 实体状态变化
副作用 - 通知、事件、外部调用

Phase 3: Synthesis

阶段3：综合

Executive Summary

执行摘要

One-paragraph answer to user's question
Top 5-10 key files
Key patterns used

回答用户问题的一段摘要
前5-10个关键文件
使用的关键模式

Detailed Explanation

详细说明

Step-by-step walkthrough with
```
file:line
```
references
Architectural decisions explained

带
```
file:line
```
引用的逐步讲解
架构决策说明

Diagrams

图表

text

+-----------+     +-----------+     +-----------+
| Component |---->|  Command  |---->|  Handler  |
+-----------+     +-----------+     +-----------+
                                          |
                                          v
                                    +-----------+
                                    |Repository |
                                    +-----------+

text

+-----------+     +-----------+     +-----------+
| Component |---->|  Command  |---->|  Handler  |
+-----------+     +-----------+     +-----------+
                                          |
                                          v
                                    +-----------+
                                    |Repository |
                                    +-----------+

Output Format

输出格式

markdown

undefined

markdown

undefined

Answer

[Direct answer in 1-2 paragraphs]

How It Works

1. [Step] - [Explanation with

file:line

reference]

1. [Step] - [Explanation with

file:line

reference]

2. [Step] - [Explanation with

file:line

reference]

2. [Step] - [Explanation with

file:line

reference]

Key Files

File	Purpose

File	Purpose

Data Flow

[Text diagram: Entry -> Processing -> Persistence -> Side Effects]

Want to Know More?

[Subtopic 1]
[Subtopic 2]

undefined

[Subtopic 1]
[Subtopic 2]

undefined

Guidelines

指南

Evidence-based: Every claim needs code evidence. Mark unverified claims as "inferred".
Question-focused: Tie all findings back to the original question.
Read-only: Never suggest changes unless explicitly asked.
Layered explanation: Start simple, offer deeper detail on request.

基于证据: 所有结论需要代码证据支持。未验证的结论标记为"inferred"。
聚焦问题: 所有调查结果必须与原始问题相关。
只读: 除非明确要求，否则绝不建议修改代码。
分层解释: 从简单开始，根据需求提供更深入的细节。

Related Skills

IMPORTANT Task Planning Notes

重要任务规划说明

Always plan and break many small todo tasks
Always add a final review todo task to review the works done at the end to find any fix or enhancement needed

始终规划并拆分为多个小型待办任务
始终添加最终审查待办任务，在结束时检查已完成的工作，寻找需要修复或改进的地方