AGENT SKILL

understand-diff

Use when you need to analyze git diffs or pull requests to understand what changed, affected components, and risks

License 许可
MIT
所属仓库
siddu1004/SFP
最近更新
2026-11-09
Stars
★ 5
Forks
0

01 前言 Front Matter

name
understand-diff
description
Use when you need to analyze git diffs or pull requests to understand what changed, affected components, and risks

03 SKILL.md 正文

/understand-diff

Analyze the current code changes against the knowledge graph in the project's data directory (.ua/knowledge-graph.json, or the legacy .understand-anything/knowledge-graph.json when that directory is present).

Graph Structure Reference

The knowledge graph JSON has this structure:

  • project — {name, description, languages, frameworks, analyzedAt, gitCommitHash}
  • nodes[] — each has {id, type, name, filePath?, summary, tags[], complexity, languageNotes?}
    • Code node types: file, function, class, module, concept
    • Non-code node types: config, document, service, table, endpoint, pipeline, schema, resource
    • Domain/knowledge node types: domain, flow, step, article, entity, topic, claim, source
    • IDs use the node type as prefix, e.g. file:path, function:path:name, config:path, article:path
  • edges[] — each has {source, target, type, direction, weight}
    • Key types: imports, contains, calls, depends_on, configures, documents, deploys, triggers, contains_flow, flow_step, related, cites
  • layers[] — each has {id, name, description, nodeIds[]}
  • tour[] — each has {order, title, description, nodeIds[]}

How to Read Efficiently

  1. Use Grep to search within the JSON for relevant entries BEFORE reading the full file
  2. Only read sections you need — don't dump the entire graph into context
  3. Node names and summaries are the most useful fields for understanding
  4. Edges tell you how components connect — follow imports and calls for dependency chains

Instructions

  1. Resolve the data directory $UA_DIR. Run UA_DIR=$([ -d .understand-anything ] && echo .understand-anything || echo .ua) — this is the legacy .understand-anything/ when it already exists, otherwise the new .ua/. Check that $UA_DIR/knowledge-graph.json exists. If not, tell the user to run /understand first.

  2. Get the changed files list (do NOT read the graph yet):

    • If on a branch with uncommitted changes: git diff --name-only
    • If on a feature branch: git diff main...HEAD --name-only (or the base branch)
    • If the user specifies a PR number: get the diff from that PR
  3. Read project metadata and check graph freshness — use Grep or Read with a line limit to extract the "project" section, including gitCommitHash as GRAPH_COMMIT_RAW, then:

    • Resolve it as a commit before using it in any Git diff. From the project root, compare the resolved commit with git rev-parse HEAD and inspect project-scoped committed and working-tree changes:
      GRAPH_COMMIT=$(git rev-parse --verify --end-of-options "${GRAPH_COMMIT_RAW}^{commit}" 2>/dev/null)
      git rev-parse HEAD
      git diff --name-only "$GRAPH_COMMIT" HEAD -- .
      git diff --cached --name-only -- .
      git diff --name-only -- .
      git ls-files --others --exclude-standard -- .
      
    • The -- . pathspec is required: commits that only touch a sibling monorepo project must not make this graph stale. A hash mismatch alone is not stale when the project diff is empty.
    • Ignore the selected data directory (.ua/ or legacy .understand-anything/) in every command's output because it contains generated graph artifacts, not project source drift.
    • If the committed diff or any working-tree command reports project files, warn before impact analysis that the graph may omit those changes. Suggest: Run /understand to refresh the graph.
    • Run the commit diff only when GRAPH_COMMIT_RAW resolves successfully. If the graph commit or Git metadata is missing, invalid, or unavailable, give a brief best-effort warning and continue instead of blocking.
  4. Find nodes for changed files — for each changed file path, use Grep to search the knowledge graph for:

    • Nodes with matching "filePath" values (e.g., grep "changed/file/path")
    • This finds file-level nodes (including non-code types) AND function/class nodes defined in those files
    • Note the id values of all matched nodes
  5. Find connected edges (1-hop) — for each matched node ID, Grep for that ID in the edges to find:

    • What imports or depends on the changed nodes (upstream callers)
    • What the changed nodes import or call (downstream dependencies)
    • These are the "affected components" — things that might break or need updating
  6. Identify affected layers — Grep for the matched node IDs in the "layers" section to determine which architectural layers are touched.

  7. Provide structured analysis:

    • Changed Components: What was directly modified (with summaries from matched nodes)
    • Affected Components: What might be impacted (from 1-hop edges)
    • Affected Layers: Which architectural layers are touched and cross-layer concerns
    • Risk Assessment: Based on node complexity values, number of cross-layer edges, and blast radius (number of affected components)
    • Suggest what to review carefully and any potential issues
  8. Write diff overlay for dashboard — after producing the analysis, write the diff data to $UA_DIR/diff-overlay.json so the dashboard can visualize changed and affected components. The file contains:

    {
      "version": "1.0.0",
      "baseBranch": "<the base branch used>",
      "generatedAt": "<ISO timestamp>",
      "changedFiles": ["<list of changed file paths>"],
      "changedNodeIds": ["<node IDs from step 4>"],
      "affectedNodeIds": ["<node IDs from step 5, excluding changedNodeIds>"]
    }
    

    After writing, tell the user they can run /understand-anything:understand-dashboard to see the diff overlay visually.

04 同仓库更多 Skills

siddu1004
siddu1004/SFP

scientific-schematics

Generates scientific diagram drafts using Nano Banana 2 AI with smart iterative refinement. Uses Gemini 3.7 Flash for quality review. Refines when the review requests improvement, with at most two generations. Specialized in neural network architectures, system diagrams, flowcharts, biological pathways, and complex scientific visualizations.

★ 5
siddu1004
siddu1004/SFP

polyhaven-texture-apply

Apply realistic PBR textures from PolyHaven to any Blender object. Supports metals, wood, concrete, fabric, and more. Trigger when asked to texture an object, apply a material from PolyHaven, make something look like metal/wood/marble, or change object surface.

★ 5
siddu1004
siddu1004/SFP

polyhaven-studio-setup

Set up a professional product photography studio in Blender using PolyHaven HDRIs and PBR ground materials. Trigger when asked to create a studio setup, add HDRI lighting, set up product photography, or create a showroom scene.

★ 5
siddu1004
siddu1004/SFP

polyhaven-scene-builder

Build complete product scenes using PolyHaven assets — HDRI environment, textured ground/pedestal, and optional props from the 3D model library. Trigger when asked to build a product scene, create a showcase setup, add a pedestal, or compose a product shot.

★ 5
siddu1004
siddu1004/SFP

polyhaven-material-swap

Cycle through multiple PolyHaven materials on a product and render each variant. Great for showing color/finish options. Trigger when asked to show material variants, swap textures, create color options, show finish comparisons, or render product in different materials.

★ 5
siddu1004
siddu1004/SFP

polyhaven-hdri-showcase

Render the same product across multiple HDRI environments and output a comparison grid. Trigger when asked to compare lighting setups, test different environments, show product in multiple settings, or create an HDRI comparison.

★ 5