interview-ready-comments

---

name: interview-ready-comments description: Adds interviewer-friendly teaching comments (where-it-fits, function walkthroughs, closing block) without changing behavior.

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:

Copy# ====================================================================================================
# 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:

Copy# ----------------------------------------------------------------------------------------------------
# <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:

Copy# ----------------------------------------------------------------------------------------------------
# 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.