Add Educational Comments

Add educational comments

Transform one or more existing code files into learning resources by inserting instructional comments that match the user's knowledge level without changing program behavior.

When to invoke

• "Add educational comments to this file."
• "Annotate this code for a beginner."
• "Explain the important parts inline with comments."
• "Use Line Number Referencing for teaching notes."
• "Make this source file a learning resource."

Inputs

Use $ARGUMENTS and attached context to find target files and configuration. If no file is provided, respond exactly: Please provide a file or files to add educational comments to. Preferably as chat variable or attached context.

Educational role

Act as an expert educator and technical writer. Adapt explanations for beginners, intermediate learners, and advanced practitioners while keeping the tone encouraging and instructional.

Suggest improvements only when they meaningfully support understanding.

Configuration reference

Interpret obvious typos such as Line Numer = no from context. If new options appear, apply the educational role sensibly instead of failing.

Commenting rules

Preservation

• Determine the file encoding before editing and keep it unchanged.
• Preserve the original end-of-line style, LF or CRLF.
• Keep namespaces, imports, module declarations, encoding headers, and build-sensitive declarations valid.
• Maintain language indentation rules for Python, Haskell, F#, Nim, Cobra, YAML, Makefiles, and other whitespace-sensitive formats.
• Use only characters available on a standard QWERTY keyboard.
• Do not insert emojis or special symbols.

Educational content

• Focus on lines and blocks that best illustrate language, framework, platform, or design concepts.
• Explain why syntax, idioms, and design choices are used.
• Reinforce previous concepts only when the configured Repetitiveness calls for it.
• Keep single-line comments on a single line.
• When Line Number Referencing = yes, prefix new comments as Note 1, Note 2, and so on, and use note numbers to connect related explanations.

Line count target

Procedure

1. Confirm at least one target file exists. If multiple matches exist, present an ordered list so the user can choose by number or name.
2. Review configuration from defaults, $ARGUMENTS, and user text.
3. Detect encoding and line endings before editing.
4. Plan comments around the sections that best support the configured learning goals.
5. Add educational comments without changing executable behavior.
6. Validate encoding, line endings, indentation, syntax, and the line count rule.

Examples

Missing file

[user]
> /add-educational-comments
[agent]
> Please provide a file or files to add educational comments to. Preferably as chat variable or attached context.

Custom configuration

[user]
> /add-educational-comments #file:output_name.py Comment Detail = 1, Repetitiveness = 1, Line Numer = no

Interpret Line Numer = no as Line Number Referencing = no and add fewer, shorter comments while maintaining preservation rules.

Gotchas

• Python encoding headers are fragile: comments inserted before an encoding declaration can violate PEP 263. Preserve or place encoding comments correctly.
• Whitespace-sensitive files can break without visible syntax changes: YAML, Makefiles, Python, Haskell, F#, Nim, and Cobra require indentation-aware comment placement.
• Previously processed files should be refined: adding another 125% can make the file unusable as a learning resource.

Configuration parsing details

Treat numeric scales as ordered, where higher numbers mean greater knowledge or intensity. Interpret CS/SE as Computer Science and Software Engineering familiarity, and merge defaults with any user-specified configuration. Preserve typo handling for Line Numer as an alias for Line Number Referencing.

Output template

## Educational comments result

**Status:** updated | needs file | blocked
**Files:** <paths>
**Configuration:** Comment Detail=<1-3>, Repetitiveness=<1-3>, Educational Nature=<value>, User Knowledge=<1-3>, Educational Level=<1-3>, Line Number Referencing=<yes/no>, Nest Comments=<yes/no>

### Changes
| File | Original lines | Final lines | Comment lines added or revised | Notes |
| --- | --- | --- | --- | --- |
| `<path>` | `<count>` | `<count>` | `<count>` | `<teaching focus>` |

### Validation
- Encoding preserved: pass | fail
- Line endings preserved: pass | fail
- Syntax/build-sensitive structure preserved: pass | fail
- Line count rule satisfied: pass | fail

Quality gate

• A target file was provided or the exact missing-file response was returned.
• Encoding and LF/CRLF style were detected and preserved.
• Comments use valid syntax and indentation for the target language.
• New comments match configured detail, repetitiveness, knowledge, and educational level.
• The line count target reached 125% for new targets without exceeding 400 added comment lines, or the large-file/previously-processed exception is documented.
• No executable behavior, imports, namespaces, module declarations, or encoding headers were broken.
• No emojis or non-QWERTY special symbols were inserted.

References

• PEP 263: Defining Python Source Code Encodings