Skills-Agent / rules

---
description: "Explain code, walk through logic, and help understand architecture or behavior. Use when the user asks what code does, how something works, or wants a walkthrough. Triggers: explain, what does this do, how does this work, giải thích, giải thích code, code này làm gì."
encoding: "UTF-8"
agents: [documentation-writer, backend-specialist, frontend-specialist]
globs: ""
alwaysApply: false
---

## Memory Protocol
**START**: Read `.ai-memory.md` from project root. Check tech stack, architecture notes, past explanations, and domain context.
**END**: Update `.ai-memory.md` using **Memory Compaction Rules** with: what was explained, key insights, misconceptions clarified, and follow-ups.

## Goal
Help the user deeply understand code, logic, architecture, or behavior — at the level of detail they need.

## Agent Routing
- If explaining backend/API logic → read `.kiro/skills/agents/agents/backend-specialist.md` and apply its knowledge
- If explaining UI/component behavior → read `.kiro/skills/agents/agents/frontend-specialist.md` and apply its knowledge
- If explaining database schema/queries → read `.kiro/skills/agents/agents/database-architect.md` and apply its knowledge
- If explaining security mechanisms → read `.kiro/skills/agents/agents/security-auditor.md` and apply its knowledge
- Default → read `.kiro/skills/agents/agents/documentation-writer.md` for clear, structured explanation

## Socratic Gate
Before explaining, verify:
1. Which file, function, or code block should be explained?
2. What level of detail? (high-level overview vs line-by-line walkthrough)
3. What is the user's familiarity level with this area?
If any answer is unclear, ASK before proceeding.

## Workflow
1. **Read Memory** — Load `.ai-memory.md` for project context, tech stack, and architecture.
2. Read the target code thoroughly — understand intent, not just syntax.
3. Identify the explanation scope: single function, module, data flow, or architecture.
4. Explain at the requested level:
   - **High-level**: Purpose, inputs/outputs, how it fits in the system.
   - **Detailed**: Step-by-step logic, control flow, edge cases, design decisions.
   - **Line-by-line**: What each line does and why.
5. Highlight non-obvious logic, hidden side effects, and design trade-offs.
6. Use analogies or diagrams if the concept is complex.
7. Suggest follow-up topics if relevant (e.g., "you may also want to understand X").
8. **Quality Gate** — Read `.kiro/skills/_scripts/checklist.md` for cross-cutting checks.
9. **Update Memory** — Save explanation context and insights to `.ai-memory.md`.

## Output format
- **What it does**: One-sentence summary
- **How it works**: Step-by-step explanation at the requested level
- **Key design decisions**: Why it was built this way
- **Non-obvious details**: Edge cases, side effects, gotchas
- **Related context**: Connected files/modules worth understanding

## Checklist
- [ ] Target code identified and read
- [ ] Explanation level matches user need
- [ ] Logic explained clearly, not just syntax described
- [ ] Non-obvious details highlighted
- [ ] Design decisions explained
- [ ] Follow-up suggestions provided
- [ ] Memory file updated

- [ ] Clean code chuẩn (Standard clean code applied)
- [ ] Cập nhật đầy đủ tất cả các file liên quan (All related files fully updated)

## Rules
- Explain the WHY, not just the WHAT — developers can read syntax themselves.
- Match explanation depth to the user's familiarity level.
- If the code is unclear or has issues, mention them without derailing the explanation.
- Avoid proposing wide changes mid-explanation; if improvement requires broader edits, ASK before switching to implementation.
- Always read and update the memory file.
 - Code encoding: All code snippets and files referenced or produced must be UTF-8 encoded. When providing example files, ensure they use UTF-8 and indicate `encoding: "UTF-8"` in front-matter where applicable.

## Related Skills
- `/debug` → read `.kiro/skills/debug/SKILL.md` — If explanation reveals bugs
- `/enhance` → read `.kiro/skills/enhance/SKILL.md` — If explanation reveals improvement opportunities
- `/status` → read `.kiro/skills/status/SKILL.md` — For project-wide understanding