code-learning-reports

name	code-learning-reports
description	Create beginner-friendly HTML learning reports for coding slices, PRs, or feature work. Use when a user wants to understand what changed, how the code works, how data flows, what tests ran, and what concepts matter.

Code Learning Reports

Quick Start

When this skill runs:

1. Inspect the task, the diff, and the changed files.
2. Identify the user-facing goal of the coding slice or PR.
3. Create a self-contained HTML learning report in the repository.
4. Explain what changed, why it changed, how the code works, and how to test it.
5. Link the report path in the final response, PR summary, or handoff note.

Use REFERENCE.md for the report standard and EXAMPLES.md for sample sections and prompts. Use templates/report-template.html as a starting point when you need a ready-made HTML structure.

Default Output Path

Use the repository's existing report location when one exists.

If the repository has no convention yet, prefer:

docs/code-reports/<feature-or-slice>-<version-or-date>.html

For demo repositories that already use an output/ folder, this is also acceptable:

output/code-learning-report.html

Report Requirements

The report must be:

• A self-contained static HTML file.
• Readable on desktop and mobile.
• Free of external runtime dependencies unless the repository already permits them.
• Written for a beginner who is learning the stack.
• Grounded in the actual changed files, commands, and test results.

Include these sections unless the user asks for a shorter report:

• Title and short feature summary.
• User-facing outcome.
• Changed files table.
• Architecture, data-flow, or event-flow explanation.
• Code walkthrough with short snippets.
• Styling or UI notes when relevant.
• Tests and verification commands with real results.
• Beginner glossary.
• Risks, tradeoffs, and follow-up ideas.

Workflow

1. Inspect the work

Read the user request, repository instructions, changed files, and test output. If the report is for a PR, inspect the PR diff instead of guessing from the working tree.

2. Map the slice

Write down:

• What problem the slice solves.
• Which files changed.
• Which functions, components, styles, routes, commands, or configuration entries matter.
• What a beginner will likely find confusing.

3. Pull teaching snippets

Use short snippets from the real code. Prefer examples that explain:

• State and data shape.
• Derived values.
• Event handlers.
• Function boundaries.
• API calls or persistence.
• Rendering branches.
• CSS classes and layout decisions.
• Tests that prove the behavior.

Do not paste whole files into the report.

4. Explain in plain language

For each important snippet, explain:

• What inputs it receives.
• What it produces.
• Why it is shaped that way.
• How it connects to the user-facing feature.
• Any tradeoff or simplification.

5. Document verification honestly

Only list commands that actually ran. Include whether each command passed, failed, or was skipped. If something could not be verified, say why.

6. Save and link the report

Save the HTML report at the agreed path, then mention that path wherever the user or reviewer will see it.

Final Response Pattern

Use a concise completion note like:

Created code learning report:

docs/code-reports/<report-name>.html

It covers:
- changed files
- data flow
- important code snippets
- verification commands
- beginner glossary

If the platform supports file attachments, attach or share the generated HTML file. If it does not, provide the repository path and commit/PR link.

What Not To Do

• Do not invent test results or command output.
• Do not include secrets, tokens, cookies, or private credentials.
• Do not depend on a specific agent platform.
• Do not assume the reader knows React, TypeScript, Python, Power Apps, or any other stack unless the user says so.
• Do not turn the report into a changelog only; it must teach the code.