Intent
Add clear, interviewer-friendly teaching comments to an existing file WITHOUT changing runtime behavior. This skill is about making code easier to explain while scrolling, not about rewriting the code.
Key principles:
- •Comment-only by default. Do not change logic unless explicitly required for correctness.
- •Keep comments structural and stable (purpose, inputs/outputs, failure modes, where it fits).
- •Keep comments ASCII-only and plain English.
- •Prefer small, high-signal comment blocks at meaningful boundaries (do not comment every line).
Workflow (apply in this order)
0) Guardrails (before editing)
- •Do not change function signatures, imports, constants, list ordering, schemas, or outputs.
- •Do not rename variables/params just to match commentary.
- •Do not reorder code blocks.
- •Do not add dependencies.
- •Preserve existing comments; only clarify/expand them (keep the same intent).
1) Add a top-of-file "INTERVIEW WALKTHROUGH" section (comments)
Place this comment block BEFORE imports (or at the very top of the file):
Template:
code
# ==================================================================================================== # INTERVIEW WALKTHROUGH (Where this fits) # # Purpose (1-2 lines): # - ... # # Where it fits in the system / flow (structural, not story): # - Caller(s): ... # - Called by/depends on: ... # - Produces/consumes artifacts: ... # # Inputs (bullets): # - ... # # Outputs (bullets): # - ... # # Determinism note (ONLY if a seed exists or randomness is involved): # - This simulation/tool uses pseudo-random sampling (arrivals, dwell times, service times). # - `seed` initializes the pseudo-random number generator (PRNG). # - Determinism: same code + same config + same seed -> reproducible outputs. # - Why same seed matters (baseline vs re-run): A/B comparability (reduce random variation). # - Nuance: same seed does NOT guarantee identical per-entity samples if the order/number of RNG draws changes # (e.g., event ordering changes after overrides). # ====================================================================================================
Rules:
- •Keep it short: 10-25 lines is usually enough.
- •Use ASCII only (no unicode arrows or em-dashes).
- •Keep it structural: mention the call chain and artifacts, not a narrative "story".
2) Add per-function teaching blocks (comments)
Add a comment header directly above EACH function in the file. If the file is large, prioritize public entrypoints and "core" functions first, then helpers.
Template:
code
# ----------------------------------------------------------------------------------------------------
# <function_name>
# What it does (simple): ...
# Why it exists in the flow: ...
# Inputs: ...
# Outputs: ...
# Key edge cases / failure modes: ...
# ----------------------------------------------------------------------------------------------------
def <function_name>(...):
...
Rules:
- •Keep explanations "as-simple-as-that".
- •Mention edge cases only if the code actually handles them (or throws).
- •Do not invent behaviors, metrics, or claims not supported by the code.
3) Add a few inline "talk track" comments (sparingly)
Inside the most important function(s), add short inline comments at major boundaries:
- •Validate inputs / early returns
- •Read/load inputs
- •Core compute step
- •Persist artifacts
- •Guardrails (caps, allowlists, confidence gates)
- •Return payload shape
Rule of thumb: 5-10 inline comments per main function; avoid narrating every line.
4) Add a bottom "CLOSING NOTE" block (comments)
Place this block near the bottom of the file (typically above the __main__ guard or at EOF):
Template:
code
# ---------------------------------------------------------------------------------------------------- # CLOSING NOTE # # Summary: # - What this file achieves (1-3 bullets). # # How to verify (numbered): # 1) ... # 2) ... # # Next steps / extension points: # - ... # ----------------------------------------------------------------------------------------------------
Rules:
- •Keep verification steps specific, local, and fast (avoid heavy/long jobs unless requested).
- •Next steps should be realistic and grounded in the codebase (no speculative features).
Do not do (hard rules)
- •Do not remove existing comments; only improve/expand them.
- •Do not rename variables/functions just to match commentary.
- •Do not refactor aggressively; prefer comment-only edits.
- •Do not invent metrics, results, thresholds, or "performance claims" not present in code.
- •Do not introduce non-ASCII characters in comments.