Diff Intake

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.

Step 1: Gather changed files and categorize

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.

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).

Step 2: Build the file summary map

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

Fetching detailed diffs

• PR

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>

For each file, record

• summary — 2-line summary of what changed
• stack — frontend, backend, or 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.

Step 3: Classify the overall change

Infer the change type and analytics scope:

analytics_scope = highest implication present:

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

If analytics_scope is none, emit the brief and note that downstream skills are not needed.

Step 4: Emit the YAML brief

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

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