name: explain
description: Explain either project code/flows or general technical concepts; for pure knowledge questions do not read project files, and never modify any files

Explain Skill

This skill is used when the user wants to "please explain":

• Code / files / flows / algorithms within the project, or
• General technical or domain knowledge points (e.g., algorithm concepts, Python syntax, Django behavior, etc.).

Key Point: Only provide explanations and analysis, do not modify any files or execute destructive commands.

When to Use

A. Explaining "Project-Internal" Items

• User says "help me explain this file / this code / this flow" and:
• Mentions specific files (e.g., apps/nist/lib/cpe_search_v2.py)
• Or mentions project-internal function / class / command names
• Wants to quickly understand:
• A file's responsibilities and architecture
• A function / class's inputs, outputs, and logic
• The overall flow of a management command (e.g., nist_cpe_handle_v2)
• Implementation steps and parameters of an algorithm in the project (e.g., CPE similarity calculation)

B. Explaining "General Knowledge Points"

• User says "help me explain what XXX is", "what is the principle of XXX", "how does XXX work", etc., and:
• No project-internal files are specified
• Or the question is clearly about general knowledge (e.g., cosine similarity, Levenshtein distance, Django ORM, HTTP cache, etc.)
• The goal is to learn concepts / technical points, not to see specific file implementations.

Output Requirements

Output must use Markdown, and choose structure based on context:

A. When Explaining Project-Internal Code / Files / Flows

• ## Purpose

• Explain the purpose of this code/module/flow and the problem it solves.

• ## Location and Role

• Explain the file/class/function's position and responsibilities in the overall project (e.g., which layer: command, service, lib, model).

• ## Input and Output

• Explain the main function / command's:

  • Important parameters (input)
  • Return values or side effects (output, such as writing to DB, generating files, printing logs).

• ## Flow Overview

• List main steps in a step-by-step or flowchart (text) format:
  • What happens first → what happens next → how the result is determined.

• For algorithms, clearly explain the order and formula concepts of scoring / matching / filtering.

• ## Details and Notes

• Explain important boundary conditions, parameter defaults, weights, thresholds, etc.
• If there are differences from older/other versions (e.g., v1 vs v2), briefly explain them here.

B. When Explaining General Knowledge Points

• ## Definition

• Clearly explain what this concept is and what problem it solves in 1–2 paragraphs.

• ## Intuitive Understanding

• Use everyday or visual analogies to help understand this concept (e.g., comparing an algorithm to a certain action flow).

• ## Formal Description (if needed)

• Briefly provide mathematical formulas or algorithm steps, but don't go into excessive detail.

• ## Common Application Scenarios

• Explain where this knowledge point is typically used, preferably linking to the current project's usage context (if applicable).

• ## Advantages, Disadvantages, and Notes

• Briefly explain the advantages, limitations, and common pitfalls of this method/concept.

Style requirements:

• Use English, wrap technical terms (class / function / file names / variables) in backticks.
• Use bullet points (-) and subheadings (##, ###) to aid readability.
• Try to explain "why it's designed this way" and "what effects this produces", not just translate code line by line.

Information Gathering Guidelines

A. When Explaining "Project-Internal Code / Files / Flows"

• Available information sources (read-only):
• Related file contents (e.g., apps/nist/management/commands/nist_cpe_handle_v2.py, apps/nist/lib/cpe_search_v2.py, apps/nist/lib/normalize_data_v2.py, etc.)
• Related design/documentation files (e.g., apps/nist/management/commands/v2.md)
• Currently open files and content mentioned by the user in the question

B. When Explaining "General Knowledge Points"

• Do not read any project files or rely on project state, only explain based on your existing general knowledge.
• Only when the user explicitly links the question to the project (e.g., "how does the cosine similarity here relate to this code section?") should you also reference project content.

Prohibited Actions (applies to both scenarios):

• Must not modify any file contents.
• Must not execute commands that modify project state (e.g., git commit, delete files, migrate database, etc.).

Instructions

When this Skill is triggered, follow these steps:

Step 1: Clarify "What to Explain"

• Based on the user's question, determine what needs to be explained:
• A single file (e.g., cpe_search_v2.py)
• A single function / class (e.g., search_cpes_v2, CPEQuery)
• An entire flow (e.g., "v2 CSV query flow", "CPE similarity calculation")
• If the question is already clear, do not ask the user again, proceed directly to the explanation.

Step 2: Read Related Code and Documentation (Read-Only)

• Only use "read" tools to understand the code, do not make any modifications.
• Find:
• Main entry points (e.g., command's handle / _handle_csv_mode / _handle_query_mode)
• Main algorithm or logic functions (e.g., _calculate_query_tf, _calculate_cosine_similarity, _calculate_version_boost_v2)
• Important constants (e.g., thresholds, weight parameters)

Step 3: Restate in High-Level Language

• First describe what this code does in "overall concept", then gradually drill down to:
• What are the inputs and outputs
• Main steps of the flow
• Important decision conditions (if / threshold / weight adjustments)
• Prioritize explaining "why it's done this way" and "what behavioral differences it produces", implementation details come second.

Step 4: Point Out Key Parameters and Adjustable Points

• If there are obvious adjustment points in the code (e.g., min_similarity_score, VERSION_WEIGHT, etc.), mention in the explanation:
• What are the current default values of these parameters
• What effects increasing or decreasing them will have on behavior (high-level description is sufficient)

Step 5: Compare with Older or Other Versions (if applicable)

• If the code is clearly v2 / new version (e.g., CPE v2), and v1 still exists in the project:
• Briefly compare v1 / v2 differences in the explanation:
  • Query interface differences (e.g., string vs CPEQuery)
  • Whether certain dependencies were removed (e.g., Redis)
  • Behavioral or algorithmic improvements

Style & Language

• Always use English for responses, unless the user specifically requests another language.
• Mark code names and file names with backticks, e.g., CPEQuery, search_cpes_v2, nist_cpe_handle_v2.
• Avoid pasting overly long code blocks; if examples are needed, use short pseudo-code or key snippets.
• Explanations should allow engineers who "have seen the code but don't want to read it in detail" to grasp the main idea in a few minutes.

What NOT to Do

• Do not:
• Modify any files, parameters, or settings.
• Execute commands with side effects (e.g., writing to DB, clearing data, re-running migrations).
• Fabricate non-existent logic or behavior (only explain based on actual code and documentation).