diff-intake

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

diff-intake

Follow this skill step by step. You are step 1 of the analytics instrumentation workflow. Produce a compact YAML change brief that downstream skills (discover-event-surfaces, instrument-events) will consume. Keep the output machine-readable and precise — no prose around the YAML block.

按照以下步骤执行此Skill。你是分析工具集成工作流的第一步。生成简洁的YAML变更摘要，供下游技能（discover-event-surfaces、instrument-events）使用。确保输出机器可读且精确——YAML块周围不要添加任何说明文字。

Step 1: Gather changed files and categorize

步骤1：收集变更文件并分类

Fetch the list of changed files from the source, then categorize each one.

从来源获取变更文件列表，然后对每个文件进行分类。

Fetching changes

获取变更

PR URL

gh pr view <number-or-url>

gh pr view <pr-number> --json files --jq '.files[] | "\(.path)\t+\(.additions) -\(.deletions)\t"'

Branch comparison

git log <main|master>..<branch>

git diff --stat <main|master>..<branch>

Ambiguous mention (PR number, branch name): infer the right form and fetch without asking unless auth fails.

PR URL

gh pr view <number-or-url>

gh pr view <pr-number> --json files --jq '.files[] | "\(.path)\t+\(.additions) -\(.deletions)\t"'

分支对比

git log <main|master>..<branch>

git diff --stat <main|master>..<branch>

模糊提及（PR编号、分支名称）：推断正确的形式并获取，除非认证失败，否则无需询问用户。

Categorize files

文件分类

Assign each file to a category based on its path:

Core Logic: application source (e.g. src/auth/login.py, database/models.ts)
Generated: anything with
```
generated
```
in its path
Testing: test files
Config / Dependencies: package.json, docker-compose.yml, etc.
Documentation: READMEs, docs/
Noise: lock-files, .svg, auto-generated migrations

For each file, record: path, category, change type (Added / Modified / Deleted), and analytics likelihood (1–5).

根据路径为每个文件分配分类：

核心逻辑：应用源代码（如src/auth/login.py、database/models.ts）
生成文件：路径中包含
```
generated
```
的文件
测试文件：测试相关文件
配置/依赖：package.json、docker-compose.yml等
文档：README文件、docs/目录
无效文件：锁文件、.svg、自动生成的迁移文件

为每个文件记录：路径、分类、变更类型（新增/修改/删除）以及分析优先级（1–5）。

Step 2: Build the file summary map

步骤2：构建文件摘要映射

Read every single Core Logic file and create the file summary map. Only process and include Core Logic files.

读取每一个核心逻辑文件并创建文件摘要映射。仅处理并包含核心逻辑文件。

Fetching detailed diffs

获取详细差异

gh pr view <number-or-url> --json baseRefOid,headRefOid

Using the response, get a detailed diff

git diff <baseRefOid>...<headRefOid> -- <file1> <file2> <file_n>

Branch comparison

git diff main..feature/foo  -- <file1> <file2> <file_n>

gh pr view <number-or-url> --json baseRefOid,headRefOid

根据返回结果获取详细差异

git diff <baseRefOid>...<headRefOid> -- <file1> <file2> <file_n>

分支对比

git diff main..feature/foo  -- <file1> <file2> <file_n>

For each file, record

为每个文件记录

```
summary
```
— 2-line summary of what changed
```
stack
```
— frontend, backend, or shared

```
summary
```
— 两行变更内容摘要
```
stack
```
— frontend、backend或shared

Also derive user-facing changes and touched surfaces

同时推导面向用户的变更和涉及的交互面

While reading the diff and the changed files, also produce the higher-level signals that downstream event discovery needs:

```
user_facing_changes
```
— a flat list of concrete behavior changes that matter to a user, PM, or analyst. Each item should describe what a user can now do, see, or experience differently. Omit purely internal refactors.
```
surfaces.components
```
— the UI components, routes, pages, handlers, or other interaction surfaces directly involved in those user-facing changes. Prefer likely instrumentation points over low-level helpers.

For each surface, record:

```
name
```
— component, route, page, hook, or surface name
```
file
```
— repo-relative path
```
change
```
—
```
added
```
,
```
modified
```
, or
```
deleted
```

If the change is backend-only or has no clear interactive surface, omit

surfaces.components

rather than inventing one.

在读取差异和变更文件时，同时生成下游事件发现所需的高层信号：

```
user_facing_changes
```
— 面向用户、产品经理或分析师的具体行为变更扁平列表。每个条目应描述用户现在可以做什么、看到什么或体验到哪些不同。忽略纯内部重构。
```
surfaces.components
```
— 直接涉及这些面向用户变更的UI组件、路由、页面、处理器或其他交互面。优先选择可能的工具集成点，而非底层辅助工具。

为每个交互面记录：

```
name
```
— 组件、路由、页面、钩子或交互面名称
```
file
```
— 仓库相对路径
```
change
```
—
```
added
```
、
```
modified
```
或
```
deleted
```

如果变更仅涉及后端或没有明确的交互面，请省略

surfaces.components

，不要凭空创建。

Step 3: Classify the overall change

步骤3：对整体变更进行分类

Infer the change type and analytics scope:

Type	Analytics implication
feat	High — new surfaces likely need tracking
fix	Low–Medium — may affect existing event conditions
refactor	Low — tracking paths may move, regression risk
perf	Low — usually no tracking impact
revert	Medium — need to check what tracking was lost
style / docs / test / build / ci / chore	None — skip analytics analysis

analytics_scope

= highest implication present:

```
none
```
— only no-impact types
```
low
```
— only perf/refactor
```
medium
```
— fix
```
high
```
— any feature or capability addition

analytics_scope

none

, emit the brief and note that downstream skills are not needed.

推断变更类型和分析范围：

类型	分析影响
feat	高——新增交互面可能需要跟踪
fix	低-中——可能影响现有事件条件
refactor	低——跟踪路径可能迁移，存在回归风险
perf	低——通常无跟踪影响
revert	中——需要检查丢失的跟踪项
style / docs / test / build / ci / chore	无——跳过分析

analytics_scope

= 存在的最高影响级别：

```
none
```
— 仅包含无影响类型
```
low
```
— 仅包含性能优化/重构
```
medium
```
— 问题修复
```
high
```
— 任何功能或能力新增

如果

analytics_scope

为

none

，则输出摘要并注明无需下游技能。

Step 4: Emit the YAML brief

步骤4：输出YAML摘要

Output only the YAML block — no prose before or after. Follow the format exactly. List each file individually in file_summary_map (no globs).

yaml

change_brief:
  classification:
    primary: feat           # dominant conventional commit type
    types: [feat, fix]      # all types detected
    analytics_scope: high   # none | low | medium | high
    stack: frontend         # frontend | backend | fullstack
  summary: "One sentence describing the overall change"
  user_facing_changes:
    - "Users can now upload an avatar with drag-and-drop and preview it before saving."
  surfaces:
    components:
      - name: "AvatarUpload"
        file: "src/components/AvatarUpload.tsx"
        change: modified
  file_summary_map:         # each entry includes a layer field
    - file: "src/components/AvatarUpload.tsx"
      summary: "New component for avatar upload with drag-and-drop and preview"
      layer: frontend       # frontend | backend | shared
    - file: "src/api/upload.ts"
      summary: "Upload endpoint handler, validates file type and persists to S3"
      layer: backend

仅输出YAML块——前后不要添加任何说明文字。严格遵循格式。在file_summary_map中单独列出每个文件（不要使用通配符）。

yaml

change_brief:
  classification:
    primary: feat           # dominant conventional commit type
    types: [feat, fix]      # all types detected
    analytics_scope: high   # none | low | medium | high
    stack: frontend         # frontend | backend | fullstack
  summary: "One sentence describing the overall change"
  user_facing_changes:
    - "Users can now upload an avatar with drag-and-drop and preview it before saving."
  surfaces:
    components:
      - name: "AvatarUpload"
        file: "src/components/AvatarUpload.tsx"
        change: modified
  file_summary_map:         # each entry includes a layer field
    - file: "src/components/AvatarUpload.tsx"
      summary: "New component for avatar upload with drag-and-drop and preview"
      layer: frontend       # frontend | backend | shared
    - file: "src/api/upload.ts"
      summary: "Upload endpoint handler, validates file type and persists to S3"
      layer: backend