feat: migrate skills review desk to astro

2026-09-05 16:54:37 +00:00
parent 107e429fb9
commit 71e4775573
66 changed files with 8184 additions and 96 deletions
@@ -0,0 +1,104 @@
+---
+name: generated-code-explanation
+description: 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:
+
+```markdown
+## 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.