add-educational-comments

$2a

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

• 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.

• Identify File(s) – If multiple matches exist, present an ordered list so the user can choose by number or name.

• Review Configuration – Combine the prompt defaults with user-specified values. Interpret obvious typos (e.g., Line Numer) using context.

• Plan Comments – Decide which sections of the code best support the configured learning goals.

• Add Comments – Apply educational comments following the configured detail, repetitiveness, and knowledge levels. Respect indentation and language syntax.

• 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.