Free Code Documentation Prompt Generator

def invalidate(user_id: str, scopes: list[str], force: bool = False) -> int:
    """Invalidate cache entries.

    Args:
        user_id: The user ID.
        scopes: A list of scopes.
        force: Whether to force. Defaults to False.

    Returns:
        An integer.
    """

def invalidate(user_id: str, scopes: list[str], force: bool = False) -> int:
    """Drop this user's cached entries for the given scopes.

    Scopes are dropped one at a time rather than in a batch, because the
    upstream store applies its own per-key rate limit and a batch delete
    silently drops the tail. Do not "optimise" this into a single call.

    Args:
        user_id: Owner of the entries. Entries for other users are never
            touched, even if a scope is shared.
        scopes: Scope names to drop. An empty list is a no-op, not a
            wildcard — passing [] to clear everything is a common bug.
        force: Skip the last-write-wins check. Only safe during migration,
            when no writer is running.

    Returns:
        Number of entries actually removed, which may be lower than
        len(scopes) if an entry had already expired.
    """

CONTEXT I AM SUPPLYING — treat as ground truth, do not infer, do not invent:
- Why it works this way:
- What it must NOT do:
- What breaks if this changes:
- Alternative we rejected, and why:
- Known callers that depend on current behaviour:
(Leave a line blank and I will accept the omission. Do not fill it yourself.)

Document only what you can read in the source I gave you.
Where you must infer, prefix that sentence with [INFERRED] and name the
evidence you inferred it from. Do not remove the marker in later passes.
If a fact is neither readable nor supplied, write [UNKNOWN — needs author]
instead of a plausible sentence.

Write a docstring for the function below, following the Google Python Style
Guide section 3.8. Use the section headings Args:, Returns: (or Yields: for a
generator), and Raises:, each ending in a colon, with a hanging indent of four
spaces. Omit a section that does not apply. Do not repeat a type that is already
in the annotation. Do not document exceptions raised when the documented API is
itself violated.

Open with one imperative or descriptive summary line, consistent with the rest of
the file (I will tell you which if it matters). Then a blank line, then any
extended description, then the sections.

Document only what you can read. Prefix any inference with [INFERRED] and name
the evidence. Write [UNKNOWN — needs author] rather than guessing.

CONTEXT I AM SUPPLYING — ground truth, do not infer:
- Why it works this way:
- What it must NOT do:
- What breaks if this changes:
- Rejected alternative:

FUNCTION:
<paste>

Write a numpydoc-style docstring for the function below, following the numpydoc
style guide. Use the section order: short summary, extended summary, Parameters,
Returns, Raises, See Also, Notes, Examples. Underline every section heading with
hyphens matching the heading length. In Parameters, put a space before the colon
and give the type after it; mark optional arguments with ", optional". Enclose
parameter names in single backticks when referring to them in prose. Omit any
section that does not apply.

Do not put implementation detail or background theory in the extended summary —
that belongs in Notes.

Document only what you can read. Prefix any inference with [INFERRED]. Write
[UNKNOWN — needs author] rather than guessing.

CONTEXT I AM SUPPLYING — ground truth, do not infer:
- Why it works this way:
- What it must NOT do:
- What breaks if this changes:

FUNCTION:
<paste>

Write a docstring for the function below using Sphinx info field lists, as
recognised by the Sphinx Python domain. Use :param name: for each argument,
:type name: only where there is no annotation to read, :returns: for the return
value, :rtype: only where there is no annotation, and one :raises ExceptionType:
line per exception. Keep the one-line summary above the field list, separated by
a blank line. Do not mix in Google or NumPy section headings.

Document only what you can read. Prefix any inference with [INFERRED]. Write
[UNKNOWN — needs author] rather than guessing.

CONTEXT I AM SUPPLYING — ground truth, do not infer:
- Why it works this way:
- What it must NOT do:
- What breaks if this changes:

FUNCTION:
<paste>

Write a JSDoc comment for the function below, following jsdoc.app. Use
@param {Type} name - description for each parameter, with the type in curly
braces and a hyphen before the description. Document object properties with
additional dotted @param entries such as @param {string} options.retries.
Use @returns with a braced type, @yields instead of @returns for a generator,
and one @throws {ErrorType} line per error the function can throw.
Add @example only if you can write one from the code without inventing an API.

Document only what you can read. Prefix any inference with [INFERRED]. Write
[UNKNOWN — needs author] rather than guessing.

CONTEXT I AM SUPPLYING — ground truth, do not infer:
- Why it works this way:
- What it must NOT do:
- What breaks if this changes:

FUNCTION:
<paste>

Write a TSDoc comment for the function below, following tsdoc.org. Do NOT put
types in curly braces — TypeScript already declares them. Use
@param name - description with a hyphen. Keep the first paragraph as the summary
and start the detail with @remarks. Use @returns for the return value,
@typeParam for generics, and a separate @throws block per exception type, each
starting with a line containing only the exception name. Use @defaultValue where
a default exists and @deprecated where it applies.

Document only what you can read. Prefix any inference with [INFERRED]. Write
[UNKNOWN — needs author] rather than guessing.

CONTEXT I AM SUPPLYING — ground truth, do not infer:
- Why it works this way:
- What it must NOT do:
- What breaks if this changes:

FUNCTION:
<paste>

Write a Javadoc comment for the method below. Order the tags: @param (one per
argument, in declaration order), @return, @throws (alphabetical by exception
name), @see, @since, @deprecated. Use angle brackets around type parameter names,
as @param <T>. Omit @return on a void method. Prefer the inline {@return ...}
form only if the summary would otherwise repeat it.

Write the first sentence as a complete summary — it is what appears in the
index. Do not restate the signature.

Document only what you can read. Prefix any inference with [INFERRED]. Write
[UNKNOWN — needs author] rather than guessing.

CONTEXT I AM SUPPLYING — ground truth, do not infer:
- Why it works this way:
- What it must NOT do:
- Thread-safety guarantees I am promising:

METHOD:
<paste>

Write a Go doc comment for the declaration below, following go.dev/doc/comment.
Start with a complete sentence whose subject is the symbol name itself. There are
no tags in Go — write prose. For a boolean-returning function use the phrase
"reports whether". Refer to named parameters and results directly, without
backquotes. If the function is safe or unsafe for concurrent use in a way a
caller would not assume, say so. If it is deprecated, add a paragraph starting
exactly with "Deprecated: " and name the replacement.

Document only what you can read. Prefix any inference with [INFERRED]. Write
[UNKNOWN — needs author] rather than guessing.

CONTEXT I AM SUPPLYING — ground truth, do not infer:
- Why it works this way:
- What it must NOT do:
- Concurrency guarantee:

DECLARATION:
<paste>

Write a rustdoc comment for the item below using /// outer doc comments and
CommonMark. Structure: one summary line, blank line, detail, then a fenced
Examples section the reader can copy and run. Add a # Panics section if any path
can panic, a # Errors section describing each error variant if it returns Result,
and a # Safety section listing the caller's invariants if the function is unsafe.
Do not restate the types — the signature already has them, and rustdoc links
them. In examples, use ? rather than unwrap.

Document only what you can read. Prefix any inference with [INFERRED]. Write
[UNKNOWN — needs author] rather than guessing.

CONTEXT I AM SUPPLYING — ground truth, do not infer:
- Why it works this way:
- Invariants the caller must uphold:
- What breaks if this changes:

ITEM:
<paste>

Write a module-level docstring for the file below, following PEP 257 for
formatting. One summary line, blank line, then prose. Cover: what this module is
responsible for, the one or two entry points a new reader should start from, and
any module-level state or import side effects. Do not enumerate every public
symbol — the generated index already does that. Do not describe internal helpers.

Prefix any inference with [INFERRED]. Write [UNKNOWN — needs author] rather than
guessing.

CONTEXT I AM SUPPLYING:
- Why this module exists separately from its neighbours:
- What does NOT belong in it:

MODULE:
<paste>

Write a package comment for the Go package below, per go.dev/doc/comment. The
first sentence must begin with "Package <name>". Describe what the package does,
name the primary types and the constructor a caller starts with, and state the
meaning of the zero value where it is useful. Put it in exactly one file of the
package. If any exported name is deprecated, add a "Deprecated: " paragraph
naming the replacement.

Prefix any inference with [INFERRED]. Write [UNKNOWN — needs author] rather than
guessing.

CONTEXT I AM SUPPLYING:
- Why this package exists:
- What must NOT be added to it:

PACKAGE FILES:
<paste>

Write crate-level documentation for lib.rs using //! inner doc comments. First
line: one sentence a reader can use to decide whether this crate solves their
problem. Then a copy-pasteable example that works without shortcuts, then the
crate's features and any cargo feature flags. Link to items with intra-doc link
syntax. Do not compare the crate to other crates.

Prefix any inference with [INFERRED]. Write [UNKNOWN — needs author] rather than
guessing.

CONTEXT I AM SUPPLYING:
- The problem this crate solves that alternatives do not:
- Non-goals:

CRATE ROOT AND PUBLIC MODULES:
<paste>

Write a README for the repository below, for a developer deciding in ninety
seconds whether to adopt it. Sections, in order: one-sentence description; the
problem it solves; install; a minimal working example that runs as written; a
second example showing the most common real configuration; requirements and
supported versions; where the full docs live; licence.

Rules: no badge wall. No file tree. No "Features" bullet list that restates the
API index. Nothing about contribution or code of conduct — those are separate
files. If you cannot produce a runnable example from what I gave you, write
[UNKNOWN — needs author] rather than an invented one.

CONTEXT I AM SUPPLYING:
- Who this is for:
- Who it is NOT for:
- The closest alternative, and when to use that instead:

REPOSITORY (package manifest, entry point, public API):
<paste>

Write a README for the internal service below, for a teammate who has been paged
about it at 2am and has never seen it. Sections: what it does in one sentence;
what breaks downstream if it is down; how to run it locally; required environment
variables and where their values come from; how to tell whether it is healthy;
where the logs, dashboards and runbook are; who owns it.

Do not write marketing copy. Do not include an architecture diagram description
you inferred. Where you do not know a value, write [UNKNOWN — needs author].

CONTEXT I AM SUPPLYING:
- Owning team and escalation path:
- Downstream consumers:
- The failure mode that has actually happened before:

SERVICE (entrypoint, config, deployment manifest):
<paste>

Document the HTTP endpoint below as reference material. For each endpoint give:
method and path; path, query and body parameters with types and whether each is
required; a request example; a success response example with every field
annotated; every error status the handler can return and the condition that
produces it.

Read the status codes and error conditions from the handler body — do not assume
a conventional set. For each of these, answer or mark [UNKNOWN — needs author]:
is it idempotent, is it paginated and how, is it rate limited, is it
authenticated and with what.

Prefix any inference with [INFERRED].

HANDLER AND ROUTE DEFINITION:
<paste>

Produce a reference page for the type below. Structure: purpose in one sentence;
construction, including what an uninitialised or default instance means; the
public members grouped by task rather than alphabetically; the lifecycle
(what must be called before what, what must be released); thread-safety;
one worked example.

Group by task, not by visibility. If two members must be called in order, say so
explicitly — that constraint is invisible in an alphabetical index.

Prefix any inference with [INFERRED]. Write [UNKNOWN — needs author] rather than
guessing.

CONTEXT I AM SUPPLYING:
- Ordering constraints between members:
- Members that are public but not intended for external use:

TYPE:
<paste>

Turn my notes into an architecture decision record with exactly five sections:
Title, Context, Decision, Status, Consequences.

Title: a short noun phrase, not a sentence.
Context: the forces at play — technical, organisational, and local to this
project. Value-neutral. State the tensions between them explicitly.
Decision: full sentences, active voice, beginning "We will".
Status: proposed or accepted.
Consequences: positive, negative and neutral, all of them. Include what becomes
harder.

Write prose in paragraphs, not bullet fragments. One to two pages.
Do not invent a force or a consequence I did not give you. Where the record needs
something I have not supplied, list it at the end under "Questions for the
author" instead of filling it in.

MY NOTES:
<paste>

I am about to write an ADR for the decision below. Before drafting anything, ask
me the questions a future maintainer would ask, in priority order, up to ten.
Cover at minimum: what alternatives were considered and why each was rejected,
what has to be true for this to remain the right call, what would make us reverse
it, who is affected outside this team, and what this makes harder.

Ask only. Do not draft the ADR and do not answer your own questions.

DECISION:
<paste>

Write changelog entries for the diff below, following keepachangelog.com. Group
strictly under the applicable headings from: Added, Changed, Deprecated, Removed,
Fixed, Security. Put them under ## [Unreleased].

Write for a user of this software, not a contributor: describe what changed for
them, not which functions were edited. One line per change. No commit hashes, no
merge commits, no internal refactors that produce no observable difference —
omit those entirely rather than padding.

If a change is breaking, say so in the line itself and name what the reader must
do. If you cannot tell whether a change is observable from outside, list it under
"Needs author review" at the end instead of guessing a heading.

DIFF:
<paste>

Write release notes for version <X.Y.Z> from the changelog entries below.
Structure: one-paragraph summary of what this release is about; Breaking changes
with a migration line each; then Added, Fixed, Security. Order by what most
affects a reader upgrading, not by size of change.

State the version increment and whether it is compatible with the previous
version. If the entries include a breaking change under a minor or patch bump,
flag that contradiction rather than smoothing it.

CHANGELOG ENTRIES:
<paste>

Write a migration guide for the breaking change below, addressed to someone whose
build has just failed. Structure: what broke, in the words of the error they are
seeing; why it changed, in two sentences; the before-and-after code, minimal and
complete; the mechanical steps in order; what cannot be migrated automatically
and what to do instead; how to verify the migration worked.

Lead with the symptom, not the rationale. Include the actual error text if you
can read it from the source or from what I supplied; otherwise write
[UNKNOWN — needs author].

CONTEXT I AM SUPPLYING:
- Why we made this change:
- What we considered and rejected to avoid breaking it:
- The deprecation path, if any:

BEFORE AND AFTER:
<paste>

Write a deprecation notice for the symbol below, in the convention of its
language. For Go, a paragraph beginning exactly "Deprecated: " in the doc
comment. For Java, the @deprecated block tag plus the @Deprecated annotation.
For TypeScript, the @deprecated TSDoc tag. For Python, a note in the docstring
plus whatever runtime warning the project already uses.

Every notice must contain three things: that it is deprecated, what to use
instead by name, and the version or date after which it may be removed. If I have
not told you the replacement or the removal date, write
[UNKNOWN — needs author] rather than "a future version".

SYMBOL AND REPLACEMENT:
<paste>

Read the function below and add inline comments ONLY where a competent reader of
this language would otherwise have to stop and work something out. Candidates: a
non-obvious algorithmic choice, a workaround for an external bug, an ordering
constraint, a magic number, a deliberate deviation from the surrounding style, a
performance trade-off.

Do not comment anything that restates the line. Do not add a comment to every
block. If nothing in this function qualifies, say "no comments needed" and stop —
that is a valid answer and I would rather have it than filler.

For each comment, prefix it with [INFERRED] if you are reasoning from the code
rather than reading a fact, and I will replace it or delete it.

FUNCTION:
<paste>

For each literal constant in the code below that is not self-evident, tell me
what you can and cannot determine: where the value came from if it is traceable
in the source, what breaks if it is changed in either direction, and whether it
must agree with a value defined somewhere else.

Output a table, one row per constant, with a column for "known from source" and a
column for "needs the author". Do not write the comment yet. I will fill in the
second column and then ask you to write it.

CODE:
<paste>

Write a runbook for the procedure below, for an on-call engineer who has never
run it. Structure:
1. When to run this — the exact alert or symptom, quoted.
2. Preconditions and access required.
3. Numbered steps. One action per step. For each: the exact command, what a
   successful result looks like, and what to do if it does not appear.
4. Verification — how to confirm the problem is actually resolved.
5. Rollback — how to undo each step that is undoable, and which are not.
6. Stop condition — when to stop and escalate, and to whom.

No prose paragraphs. No step that says "investigate" without saying where to
look. Mark any command you have not been shown as [UNKNOWN — needs author]
rather than inventing plausible syntax — an invented command run at 3am is the
worst possible outcome of this prompt.

CONTEXT I AM SUPPLYING:
- Escalation contact:
- Steps that are irreversible:
- What has gone wrong with this procedure before:

PROCEDURE NOTES, SCRIPTS AND DASHBOARDS:
<paste>

From the incident writeup below, extract a runbook for the same failure happening
again. Take only what the writeup evidences. For every step, cite the sentence in
the writeup it came from.

Then list separately: things the responders did that the writeup does not explain
well enough to repeat, and the detection gap — what would have caught this
sooner. Do not merge those into the steps.

WRITEUP:
<paste>

Below is a function and a doc block that claims to describe it. Do not rewrite
anything. For each factual claim in the doc block, output one row:

CLAIM | SUPPORTED / CONTRADICTED / NOT DETERMINABLE | evidence (line or reason)

A claim is SUPPORTED only if you can point at the code that makes it true.
Anything about intent, performance, thread-safety or downstream effects that is
not visible in this file is NOT DETERMINABLE — do not mark it supported because
it sounds right.

Then list, separately: behaviour the code has that the doc block omits.

CODE:
<paste>

DOC BLOCK:
<paste>

Below is a source file. Read every doc block, docstring and inline comment in it
and report drift only. For each problem, one line:

LOCATION | ISSUE | current code says | doc says

Issue types: CONTRADICTED (doc states something the code does not do), STALE
(refers to a parameter, return value, error or symbol that no longer exists),
INCOMPLETE (a documented function gained a parameter, error path or side effect
that is undocumented), OR NOISE (the block only restates the signature).

Do not rewrite anything. Do not report style. If a file is clean, say so.

FILE:
<paste>

Here is a diff. For each changed symbol, tell me whether its documentation must
change too, and why. Consider: signature changes, new or removed error paths,
changed defaults, changed side effects, changed thread-safety, and anything the
doc block asserts that the diff falsifies.

Output: symbol | doc needs update? yes/no | what specifically is now wrong.
Then list documentation elsewhere in the repository that likely references these
symbols and should be checked — README, migration guides, runbooks — naming the
file if it appears in the diff context.

Do not write the updated docs. I want the list first.

DIFF:
<paste>

Regenerate the doc block for the function below from the current source, in
<convention>. Then output a second section, "What changed and why", listing every
sentence in the old block that you dropped or altered, with the reason.

Preserve verbatim any line in the old block marked as author-supplied context,
any [UNKNOWN — needs author] marker still unanswered, and any rationale that the
code does not contradict — that content did not come from the source and you
cannot regenerate it.

OLD BLOCK:
<paste>

CURRENT SOURCE:
<paste>

For the module below, produce a coverage table: every public symbol, whether it
has documentation, and whether that documentation includes each of — purpose,
parameters, return value, error conditions, and any rationale beyond restating
the signature.

Then rank the undocumented and thinly-documented symbols by how much a reader
would suffer without docs: exported and non-obvious first, exported and obvious
next, internal last. Do not write any documentation yet.

MODULE:
<paste>