AI prompts for code review and technical writing

Explain the following code as if to a competent developer who is unfamiliar with this specific codebase.

For each logical block (not each line — group sensibly):
1. What it does in one sentence.
2. Why it might be written this way (the non-obvious motivation).
3. Any side effects, hidden state, or gotchas.

At the end, list:
- Three questions I should ask the original author before changing it.
- One thing that looks like a bug or smell, if any.

Language/framework: language and framework
Code:
"""
paste code here
"""

Refactor the function below. Constraints, in priority order:

1. **Behavior MUST be identical** — same inputs produce same outputs, same side effects.
2. Prefer clarity over cleverness.
3. Prefer fewer lines only if clarity is not sacrificed.
4. Extract named helpers for any block that has its own concept.
5. Add a 1-line comment ONLY where the "why" is non-obvious. No narration comments.

Before output, list the changes you are about to make as a bulleted plan.
Then output the refactored function in a single code block.
Then list 3 test cases that would catch a behavior regression.

Function:
"""
paste function here
"""

Write a technical spec from the product requirement below.

PRD or requirement:
"""
prd or requirement
"""

Language / stack: stack

Produce:
1. **Proposed approach** — the implementation strategy in plain language, before any code.
2. **Data model changes** — new tables, fields, or schema modifications required.
3. **API contract** — endpoint(s), request/response shape, error states.
4. **Edge cases the PRD doesn't mention** — scenarios the product requirement left ambiguous or omitted.
5. **Open questions for the PM** — things that must be answered before implementation can start.
6. **Complexity estimate**: S / M / L / XL with a one-sentence rationale.

Write for an engineer picking this up cold. The PM who wrote the requirement is not the audience.

Write a pull request description from the changes below.

What changed (diff, commit list, or summary):
"""
changes
"""

Context: context (e.g. "fixing a bug in the auth flow" or "adding a new API endpoint")

Produce:
1. **What changed** — one sentence.
2. **Why** — one sentence. Not "as requested" — the actual reason.
3. **What the reviewer should look at closely** — only the parts that need judgment.
4. **How to test this locally** — three steps, specific enough to follow without asking.
5. **What was NOT changed** that a reviewer might expect to see — to prevent false alarms.

No bullet storms. Keep the total under 200 words.

Help me debug this. Do not suggest fixes yet.

Symptom, as observed: symptom
When it started, and what changed around then: timeline
Reproducibility: repro steps
What I have already ruled out, and how: ruled out
Relevant environment: environment
Code or logs:
"""
paste code or logs here
"""

Do this in order:
1. Restate the symptom precisely, separating what was observed from what has been inferred. Flag any inference I have been treating as an observation.
2. List candidate causes ranked by prior probability given the timeline. Ignore how interesting each one is
3. For each candidate, the cheapest check that distinguishes it from the others, and what result would eliminate it
4. Identify the single check that splits the candidate space most evenly, and say to run that one first
5. Name what would make this not reproduce for me but reproduce for the reporter

Do not propose a fix until I come back with results. If the information given cannot narrow it, say what to collect instead.

Produce a test plan for this change.

What the change is meant to do: intent
Risk tolerance for this area: risk context
Existing test coverage here: existing coverage
Diff:
"""
paste diff here
"""

Produce:
1. What behavior changed, derived from the diff itself. Flag any difference between the diff and my description.
2. Tests worth writing, in priority order, each with the specific failure it would catch
3. Edge cases visible in the diff: nulls, empty collections, boundaries, concurrency, ordering, partial failure
4. Blast radius: what else depends on the changed code that the diff does not show, and what to check there
5. What cannot be covered by automated tests here, and the manual check instead
6. Tests not worth writing, and why — coverage that would only assert the implementation back to itself

Do not propose a test for every changed line. Rank by the cost of the failure it prevents.

Draft a postmortem from this incident.

What happened, as a timeline: timeline
Impact: who, how many, how long: impact
How it was detected: detection
How it was resolved: resolution
What made diagnosis slow: diagnosis friction

Produce:
1. Summary: what broke, for whom, for how long — three sentences
2. Timeline, with detection, escalation, and mitigation marked
3. Contributing causes, plural. Distinguish the trigger from the conditions that made the trigger harmful.
4. For each cause, which of these it is: a missing guardrail, a missing signal, a design assumption that no longer held, or a process gap
5. What went right — including anything that limited the impact, which is usually invisible
6. Action items, each with the specific failure mode it prevents and whether it prevents recurrence or reduces impact. Cut any that are "be more careful".
7. The question this incident raises that the action items do not answer

Rules:
- No individual is named as a cause. If a person could make this mistake, the system allowed it.
- Do not settle on a single root cause. Incidents that reach production have several.

Write reference documentation for this API from its implementation.

Who reads these docs and what they know already: audience
Stability guarantees we make: stability
Code:
"""
paste code here
"""

For each endpoint or function, document:
1. What it does, in one sentence, in terms of the caller's goal
2. Parameters: type, whether required, default, and the constraint — including constraints that only validation enforces and the type does not express
3. Return shape, including the shape on partial success
4. Every error the caller can receive, what causes it, and whether it is retryable
5. Side effects, including ones the name does not suggest
6. A working example with realistic values. No "foo" or "bar"

Then, separately:
- Behavior that is currently true but not guaranteed, so callers do not depend on it
- Anything in the implementation that looks unintentional and should be confirmed before being documented as a contract

Do not document what the code should do. Document what it does.

Plan this dependency upgrade.

Dependency and version change: dependency change
How it is used in our codebase: usage pattern
What is downstream of it: downstream
Changelog or migration notes: changelog
Deploy and rollback mechanics: deploy process
Why we are upgrading: motivation

Produce:
1. Breaking changes that affect us specifically, separated from breaking changes that do not
2. Behavioral changes that are not listed as breaking but will change our output — usually defaults, error handling, or serialisation
3. A sequence of independently shippable steps, each with its own rollback. If it cannot be split, say so and say why.
4. For each step: what to verify before moving on
5. What will only fail in production, and how to detect it quickly. Name the earliest signal, ahead of the eventual symptom
6. The rollback that is genuinely available at each step, including any point after which rollback stops being possible
7. Whether this upgrade is worth doing now, given the stated motivation

Be direct on point 7 if the motivation is "we are behind". Being behind is a real cost, but it is not urgent, and this plan may not be worth its risk this quarter.

Review this pull request.

What it is meant to do: intent
Context a reviewer needs: context
Our conventions that matter here: conventions
Diff:
"""
paste diff here
"""

Review in this order, and label every comment with its category:
1. CORRECTNESS — does it do what it claims? Name the input that produces the wrong result.
2. SAFETY — data loss, security, permissions, resource leaks, unhandled failure
3. BLAST RADIUS — what else this affects that the diff does not show
4. CLARITY — what a reader in six months will misread, and why
5. CONVENTION — deviations from the stated conventions
6. PREFERENCE — everything else, clearly marked as optional

Rules:
- Each comment must state the consequence as well as the observation.
- Do not raise style issues a formatter or linter handles.
- If you find nothing in categories 1 to 3, say so explicitly. Do not promote a preference to fill the space.
- End with: merge, merge after fixes (list which), or needs rework.