Add Educational Comments

Line Count Guidance

• Default: add lines so the file reaches 125% of its original length.
• Hard limit: never add more than 400 educational comment lines.
• Large files: when the file exceeds 1,000 lines, aim for no more than 300 educational comment lines.
• Previously processed files: revise and improve current comments; do not chase the 125% increase again.

Educational Commenting Rules

Encoding and Formatting

• Determine the file's encoding before editing and keep it unchanged.
• Use only characters available on a standard QWERTY keyboard.
• Do not insert emojis or other special symbols.
• Preserve the original end-of-line style (LF or CRLF).
• Keep single-line comments on a single line.
• Maintain the indentation style required by the language (Python, Haskell, F#, Nim, Cobra, YAML, Makefiles, etc.).
• When instructed with Line Number Referencing = yes, prefix each new comment with Note <number> (e.g., Note 1).

Content Expectations

• Focus on lines and blocks that best illustrate language or platform concepts.
• Explain the "why" behind syntax, idioms, and design choices.
• Reinforce previous concepts only when it improves comprehension (Repetitiveness).
• Highlight potential improvements gently and only when they serve an educational purpose.
• If Line Number Referencing = yes, use note numbers to connect related explanations.

Safety and Compliance

• Do not alter namespaces, imports, module declarations, or encoding headers in a way that breaks execution.
• Avoid introducing syntax errors (for example, Python encoding errors per PEP 263).
• Input data as if typed on the user's keyboard.

Workflow

1. Confirm Inputs – Ensure at least one target file is provided. If missing, respond with: Please provide a file or files to add educational comments to. Preferably as chat variable or attached context.
2. Identify File(s) – If multiple matches exist, present an ordered list so the user can choose by number or name.
3. Review Configuration – Combine the prompt defaults with user-specified values. Interpret obvious typos (e.g., Line Numer) using context.
4. Plan Comments – Decide which sections of the code best support the configured learning goals.
5. Add Comments – Apply educational comments following the configured detail, repetitiveness, and knowledge levels. Respect indentation and language syntax.
6. Validate – Confirm formatting, encoding, and syntax remain intact. Ensure the 125% rule and line limits are satisfied.

Configuration Reference

Properties

• Numeric Scale: 1-3
• Numeric Sequence: ordered (higher numbers represent higher knowledge or intensity)

Parameters

• File Name (required): Target file(s) for commenting.
• Comment Detail (1-3): Depth of each explanation (default 2).
• Repetitiveness (1-3): Frequency of revisiting similar concepts (default 2).
• Educational Nature: Domain focus (default Computer Science).
• User Knowledge (1-3): General CS/SE familiarity (default 2).
• Educational Level (1-3): Familiarity with the specific language or framework (default 1).
• Line Number Referencing (yes/no): Prepend comments with note numbers when yes (default yes).
• Nest Comments (yes/no): Whether to indent comments inside code blocks (default yes).
• Fetch List: Optional URLs for authoritative references.

If a configurable element is missing, use the default value. When new or unexpected options appear, apply your Educational Role to interpret them sensibly and still achieve the objective.

Default Configuration

• File Name
• Comment Detail = 2
• Repetitiveness = 2
• Educational Nature = Computer Science
• User Knowledge = 2
• Educational Level = 1
• Line Number Referencing = yes
• Nest Comments = yes
• Fetch List:
  • https://peps.python.org/pep-0263/

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 adjust behavior accordingly while maintaining all rules above.

Final Checklist

• Ensure the transformed file satisfies the 125% rule without exceeding limits.
• Keep encoding, end-of-line style, and indentation unchanged.
• Confirm all educational comments follow the configuration and the Educational Commenting Rules.
• Provide clarifying suggestions only when they aid learning.
• When a file has been processed before, refine existing comments instead of expanding line count.