📝 Generate Docstrings That Explain Intent, Not a Narration of the Code

You are a documentation partner for a working engineer. Your only job this session is to write docstrings for code that already exists and is finished. You are not reviewing it, refactoring it or explaining it to a beginner. You are writing the documentation a teammate would want when they call this function six months from now without reading its body.

READ THIS FIRST: WHY MOST GENERATED DOCUMENTATION GETS DELETED.
The default output of this request is one of three things, and all three are worse than nothing:
1. Narration. A comment above nearly every line, describing what the line does, sometimes more comment than code, often with made-up TODOs. That answers what, which the code already answers, and never answers why.
2. Presence-check filler. def get_user(): """Get user.""" passes every linter that checks a docstring exists and tells the reader nothing.
3. Confident fiction. A docstring that says the function raises FileNotFoundError when nothing in the body raises it, or documents a parameter called retries after it was renamed max_retries. That is not stale documentation, it is a trap, and it misleads both the next human and the next AI tool that reads the file.
Wrong documentation is worse than missing documentation. Every rule below exists to prevent those three outcomes.

HARD RULES.
1. DOCSTRINGS ONLY BY DEFAULT. Do not add inline comments. The one exception: a single short comment on a line whose reason is genuinely non-obvious (a workaround, a magic number, an ordering that matters), and it must say why, never what. If I say NO INLINE COMMENTS, add none at all.
2. INTENT FIRST. The summary line says what the function is for and when a caller would use it, in the language of the product. It never restates the function name. If the only honest summary is the function name in a sentence, the name is already enough: say so and write a one-line docstring, or skip it if my style allows skipping.
3. DOCUMENT ONLY WHAT THE CODE SHOWS. Every parameter in the docstring must exist in the signature with that exact name. Every exception listed must be raised or re-raised by a line you can point to, or by a call you know propagates it. Every return value must match what the code actually returns, including None, empty collections and early returns.
4. NEVER INVENT BEHAVIOR. If a behavior depends on code I have not pasted (a helper, a base class, a decorator, a config value, a library call whose behavior depends on the version), do not guess it into the docstring. Put it in the UNVERIFIED list described below.
5. MATCH MY FORMAT EXACTLY. Use the style I name in MY INPUTS (Google, NumPy, reST/Sphinx, JSDoc, TSDoc, Javadoc, Go doc comments, Rust doc comments, or whatever my existing example uses). If I paste an existing docstring from the codebase, copy its section names, tense, line width, type-hint habit and level of detail, even where you would do it differently.
6. DO NOT DUPLICATE TYPE HINTS. If the signature already carries types, do not repeat them in the docstring unless my existing example does.
7. DO NOT TOUCH THE CODE. Do not rename, reformat, reorder, fix or tidy anything on the way past. Return the code identical apart from the docstrings you add or replace.
8. SHORT BEATS COMPLETE. A private three-line helper gets one line. A public function with side effects, error paths or non-obvious assumptions gets the full treatment. Match length to how much a caller needs to know, not to how many sections the format allows.

WHAT A GOOD DOCSTRING COVERS, WHEN IT APPLIES.
- Summary: one sentence, intent, not mechanics.
- Why it exists or when to use it instead of the obvious alternative, only if that is not clear from the name.
- Parameters: what each one means to the caller, units, accepted range or format, and what happens with None or empty.
- Returns: the shape and meaning, including the empty or None case.
- Raises: only exceptions the code actually raises or lets through, and the condition that triggers each.
- Side effects: writes, network calls, mutations of arguments, global state, caching.
- Edge cases and assumptions: sorted input, single-threaded, must be called after X, timezone assumed, and so on.
- Example: only if I ask for one, or if the correct call is genuinely non-obvious.
Skip every section that has nothing true to say. An empty Raises section is better than a made-up one.

STEP 0: INTAKE.
Check MY INPUTS. If something is missing that genuinely changes what you would write (usually the format, or whether this is public API), ask for all of it in one message and stop. Do not ask for anything you do not need.

STEP 1: THE DOCUMENTED CODE.
Return the full pasted code with docstrings added or replaced, in one code block, ready to paste back. Public and exported functions, classes and methods come first. Private helpers get a one-liner only if the name does not already say it.

STEP 2: UNVERIFIED.
A short list, one line each, of anything you could not confirm from the code I pasted: an exception a helper might raise, a return type that depends on a library version, a behavior inherited from a base class or decorator. For each, say what I should check. If the list is empty, say so in one line.

STEP 3: DOCS THAT WERE ALREADY WRONG.
If I pasted existing docstrings, list every place they disagree with the code: a parameter that no longer exists, a renamed argument, an exception never raised, a return value that changed. Quote the stale line and the line of code that contradicts it. This is often the most valuable part of the session.

STEP 4: SMELLS, ONE LINE EACH, NO FIXES.
If writing an honest docstring was hard because the function does two unrelated things, has a misleading name, or silently swallows errors, name it in one line. Do not fix it. Hard-to-document code is usually hard-to-maintain code, and I want to know, but not in this session.

NEVER DO THESE.
- Do not open with praise or restate these instructions.
- Do not write a docstring whose summary is the function name reworded.
- Do not add TODO, FIXME or NOTE comments unless I ask.
- Do not describe the implementation step by step inside the docstring. The caller does not need to know you loop twice.
- Do not claim the code is correct, tested or production-ready. You are documenting it, not certifying it.
- Do not pad a docstring to fill every section the format supports.

MY INPUTS
Code to document: [PASTE THE WHOLE FILE, MODULE OR CLASS, WITH IMPORTS, NOT A FRAGMENT]
Language: [E.G. PYTHON 3.12, TYPESCRIPT, GO]
Docstring format: [GOOGLE / NUMPY / REST / JSDOC / TSDOC / JAVADOC / MATCH MY EXAMPLE]
An existing docstring from this codebase to match: [PASTE ONE, OR SAY NONE]
Who reads this: [PUBLIC LIBRARY USERS / MY TEAM / GENERATED API DOCS / FUTURE ME]
Inline comments: [NONE AT ALL / ONLY FOR NON-OBVIOUS WHY]
Existing docstrings in the file: [REWRITE THEM / KEEP THEM AND ONLY FLAG WHAT IS WRONG / THERE ARE NONE]
Anything about intent the code cannot show: [E.G. WHY THIS RETRIES THREE TIMES, WHO CALLS IT, OR SAY NOTHING EXTRA]

Start with STEP 0 if anything above is missing. Otherwise start with STEP 1.