ai-for-dummies/submitted-skills/Matheus Rocha/skills/generated-code-explanation/SKILL.md

name, description

name	description
generated-code-explanation	Explain code that is being introduced or changed in the Netcracker Telekom demo project. Use when summarizing implementation intent, design rationale, trade-offs, or the reasoning behind a chosen approach.

Generated Code Explanation

Use this skill whenever the task requires explaining code that was (or will be) generated, modified, or reviewed. The goal is to make the what and the why explicit for readers, reviewers, and future maintainers.

When to Use This Skill

• After implementing a feature or fix and the user asks for an explanation.
• When writing commit messages, PR descriptions, inline comments, or documentation.
• When reviewing code and summarizing what it does and why it was done this way.
• When onboarding someone to a module, component, or algorithm.
• When the user explicitly asks: “explain what this code does” or “why did you choose this approach?”

Core Rules

1. Explain the “what” first, then the “why.”

   • Start with a concise summary of the behavior or structure.
   • Follow with the reasoning, constraints, or trade-offs that shaped it.

2. Stay concrete and anchored to the code.

   • Reference file paths, function/class names, and key lines where relevant.
   • Avoid vague or generic statements that could apply to any codebase.

3. Match the audience.

   • For junior developers: explain domain concepts, naming choices, and control flow.
   • For reviewers: emphasize trade-offs, risks, and alternatives considered.
   • For non-technical stakeholders: translate the implementation into business impact.

4. Be honest about limitations.

   • If a choice was made because of time, compatibility, or training-project constraints, say so.
   • Do not invent or assume motivations not supported by the code or project context.

5. Preserve project conventions.

   • In this repo, respect module boundaries (catalog-core, catalog-api, catalog-import, catalog-app, frontend/src/...).
   • Do not introduce new frameworks, databases, or production-grade integrations just to make explanation easier.

Explanation Template

For any non-trivial change, structure the explanation like this:

## What is being implemented?

- Brief overview of the change (one to three sentences).
- Specific files/classes/functions affected.
- Inputs, outputs, and side effects.

## Why this approach?

- Problem being solved.
- Alternatives considered and why they were rejected.
- Constraints (stack, scope, demo nature, existing patterns).
- Trade-offs accepted (complexity, performance, readability, maintainability).

## How to verify

- Commands to run.
- Expected outcomes.
- Manual checks if relevant.

Example Applications

Backend (Quarkus)

When explaining a new endpoint, DTO, mapper, or service method:

• What: describe the resource path, HTTP method, request/response shapes, and which domain object it exposes.
• Why: explain MapStruct usage, immutability, why a DTO was introduced, and how it preserves traceability fields.

Frontend (React + Redux Toolkit)

When explaining a new page, component, RTK Query hook, or slice:

• What: describe the route, UI states (loading/empty/error), data flow, and props.
• Why: explain the choice of RTK Query over a raw fetch, why Redux Toolkit state is shared, or why an Ant Design component was selected.

Catalog Import (Apache POI)

When explaining importer logic:

• What: describe the sheet being read, the normalization steps, and the generated JSON structure.
• Why: explain why validation warnings are preferred over silent drops, why a fixed import date is used for training determinism, and how traceability fields are preserved.

What to Avoid

• Pure code dumps without narrative.
• Jargon-heavy explanations that skip the actual behavior.
• Claims like “this is the best approach” without evidence or context.
• Misrepresenting demo/training constraints as production requirements.
• Adding explanation-only scaffolding (extra files, comments, or docs) that does not serve a clear reader.

Verification

If the explanation accompanies a code change:

1. Re-read the explanation against the actual diff.
2. Confirm every claim about behavior is supported by the code.
3. Run the relevant tests or build commands listed in the target skill (e.g., quarkus-catalog-backend, react-catalog-shop).
4. Update the explanation if the code changes.