Documentation prompts

Write a README for this project.

PROJECT: [NAME AND WHAT IT DOES IN ONE SENTENCE]
LANGUAGE/STACK: [DETAIL]
WHO WILL READ THIS: [teammates / open source users / future me]
HOW TO RUN IT: [COMMANDS YOU KNOW]
DEPENDENCIES AND PREREQUISITES: [WHAT MUST BE INSTALLED FIRST]
CONFIGURATION: [ENV VARS, CONFIG FILES]
CODE STRUCTURE:
```
[PASTE FILE TREE OR DESCRIPTION]
```

Structure, in this order:

1. One-sentence description. What it does, not how.
2. WHAT THIS IS FOR / WHAT IT IS NOT - the scope, so people know within ten seconds whether to keep reading.
3. QUICK START - the shortest path from clone to working. Numbered commands, copy-pasteable, with the expected output after each. Target: under five minutes.
4. PREREQUISITES - with version numbers and how to check each is installed.
5. CONFIGURATION - a table: variable | required? | default | what it does | example value. Never a real secret as an example.
6. USAGE - the three most common things people will do, with a real command and real output for each.
7. TROUBLESHOOTING - the four errors a newcomer is most likely to hit, and the fix for each. Include the literal error message so it is searchable.
8. PROJECT STRUCTURE - only the directories that matter, one line each.
9. CONTRIBUTING / DEVELOPMENT - how to run tests, how to run it in dev mode.

Rules:
- Every command must be copy-pasteable with no placeholder unless marked [LIKE THIS]
- State the expected output, so people know if it worked
- No badges, no logo, no table of contents for a document this short
- If I have not given you enough to write a section, write [TODO: what is needed] rather than generic filler
- Section 7's error messages must be literal strings people can search for

Write API documentation from this code.

CODE:
```
[PASTE ROUTE HANDLERS / FUNCTION SIGNATURES / SCHEMA]
```

API TYPE: [REST / GraphQL / library / CLI]
AUDIENCE: [internal team / external developers / both]
AUTH MODEL: [DESCRIPTION]
BASE URL: [IF APPLICABLE]

For each endpoint or function document:

1. WHAT IT DOES - one sentence, in terms of the caller's goal, not the implementation
2. WHEN TO USE IT - and when to use a different endpoint instead
3. AUTH REQUIRED - which permission, scope or role
4. PARAMETERS - table: name | type | required | default | constraints | description. Constraints means real limits: max length, allowed values, format.
5. REQUEST EXAMPLE - complete and runnable, as a curl command for REST
6. SUCCESS RESPONSE - the actual shape with realistic values, not 'string' and 'foo'
7. ERRORS - a table of every error this can return: status | code | when it happens | what the caller should do about it
8. SIDE EFFECTS - what changes as a result. Is it idempotent? Can it be safely retried?
9. RATE LIMITS AND PAGINATION - if applicable
10. GOTCHAS - anything surprising in the behaviour you can see in the code

Rules:
- Examples must use realistic data, never foo/bar/test123
- Never document a parameter without its constraints - 'string' is not documentation
- Section 7 is the most-read part of any API doc. Be thorough.
- Section 8 matters for anything a client might retry.
- Where the code does something the name does not suggest, say so in section 10.
- If something is unclear from the code, write [VERIFY: question] rather than guessing.

Write an Architecture Decision Record.

DECISION: [WHAT WAS DECIDED]
CONTEXT: [WHAT SITUATION PROMPTED THIS]
OPTIONS CONSIDERED: [LIST]
WHY THIS ONE: [REASONING]
CONSTRAINTS AT THE TIME: [TEAM SIZE, DEADLINE, EXISTING SYSTEMS, SKILLS, BUDGET]
WHO DECIDED: [ROLES]
DATE: [DATE]

Use this structure:

**Title**: a short noun phrase naming the decision
**Status**: Proposed / Accepted / Superseded by [X] / Deprecated
**Date**
**Context**: the forces at play. What was true then. Include the constraints, because they are what a future reader will not know and what most changes the reasoning. Write this so someone with no history can follow it.
**Decision**: what we are doing, stated in active voice: 'We will...'
**Options considered**: each one with its genuine advantages and why it was not chosen. Steelman the rejected options - a reader who thinks option B was obviously better needs to see that you considered it properly.
**Consequences**: split into three:
  - What becomes easier
  - What becomes harder
  - What we are now committed to (the hard-to-reverse part)
**Revisit when**: the specific conditions that should trigger reconsidering this. Scale thresholds, team changes, a dependency's roadmap, a cost crossing a line.

Rules:
- Context must be written for someone who joins in two years and knows none of this
- Do not present the chosen option as obviously correct. If it was a close call, say so.
- 'Revisit when' must be observable conditions, not 'when it becomes a problem'
- Keep the whole thing under 800 words. An ADR nobody reads is not documentation.

Review and improve the comments in this code.

CODE:
```
[PASTE]
```

CONTEXT I HAVE THAT IS NOT IN THE CODE: [WHY THINGS ARE THE WAY THEY ARE - HISTORY, CONSTRAINTS, BUGS THIS WORKS AROUND]

Produce:

1. COMMENTS TO DELETE - comments that restate the code ('// increment i'), are out of date, or explain what a well-named function already explains. Quote each and say why.

2. COMMENTS TO ADD - only where the code cannot explain itself:
   - WHY a non-obvious approach was chosen over the obvious one
   - A workaround for a specific bug or external system quirk (with the issue link placeholder)
   - A constraint that is not visible locally ('must stay under 4KB because...')
   - A deliberate deviation from convention
   - A performance-motivated ugliness, with the measurement that justified it
   - An invariant a future editor must preserve
   - A known limitation or TODO with a real condition, not 'fix later'

3. NAMING FIXES - places where renaming a variable or function removes the need for a comment entirely. Always prefer this to a comment.

4. DOC COMMENTS - for public functions: purpose, parameters with constraints, return value, what it throws, side effects. Use the conventional format for my language.

5. THE MISSING WHY - based on what I told you about history and constraints, the things you now know that are not recorded anywhere in the code. These are the most valuable comments to add.

Rules:
- Never write a comment that will be wrong after a small refactor
- Prefer a better name to a comment, always
- A comment explaining a workaround must say what breaks if it is removed
- Output the commented code, then the delete list separately

Write an on-call runbook.

SERVICE: [NAME AND WHAT IT DOES]
THE ALERT OR SITUATION: [WHAT TRIGGERS THIS RUNBOOK]
WHAT IT MEANS WHEN IT FIRES: [IMPACT ON USERS]
SYSTEM CONTEXT: [DEPENDENCIES, WHERE IT RUNS]
HOW I NORMALLY HANDLE IT: [PASTE YOUR PROCESS, MESSY IS FINE]
TOOLS AVAILABLE: [DASHBOARDS, LOG SYSTEM, ACCESS METHOD]

Write for someone who is tired, stressed and has never seen this before.

Structure:

1. WHAT IS BROKEN AND WHO IS AFFECTED - two sentences, at the very top.
2. SEVERITY - is this page-worthy right now, or can it wait until morning? State the criteria for each.
3. IMMEDIATE ACTIONS - the first three things to do, as literal commands. Before any diagnosis. Include any action that limits damage.
4. DIAGNOSIS - a decision tree. Each step: what to check (with the exact command or dashboard), what each possible result means, and where to go next. Use if/then, not prose.
5. RESOLUTION - per cause, the fix, as literal commands with expected output.
6. IF THE FIX DOES NOT WORK - the fallback: rollback command, failover procedure, or how to degrade gracefully.
7. ESCALATION - who to wake, at what point, and what to tell them. Include the threshold: 'if not resolved in 30 minutes' or 'if data loss is possible'.
8. AFTER - what to record, what to check once it is resolved, whether a post-mortem is needed.

Rules:
- Every command literal and copy-pasteable. No 'check the logs' - give the query.
- No background or architecture explanation before section 4. It can go at the end.
- Say explicitly which commands are destructive or irreversible, before the command.
- Where I have not given enough detail, write [FILL IN: what] rather than a vague instruction.
- Write in the imperative. Short sentences.

Help me document this system. I inherited it and nobody who wrote it is still here.

WHAT I KNOW: [WHATEVER YOU KNOW - WHAT IT DOES, WHO USES IT]
CODE / STRUCTURE:
```
[PASTE FILE TREE, KEY FILES, CONFIG, SCHEMA]
```
HOW IT IS DEPLOYED: [IF KNOWN]
WHAT I AM TRYING TO DO: [understand it / change it safely / replace it / just stop it breaking]

Produce:

1. WHAT IT DOES - inferred from the code. Mark confidence: certain / probable / guess.
2. ENTRY POINTS - every way this system can be invoked: HTTP routes, CLI commands, scheduled jobs, queue consumers, webhooks, database triggers. Miss none; unknown entry points are how legacy systems surprise you.
3. DATA FLOW - what comes in, what is stored where, what goes out, what it calls.
4. EXTERNAL DEPENDENCIES - every external system, service, file path, credential, and hardcoded URL or IP.
5. SCHEDULED AND BACKGROUND WORK - anything that runs on a timer. These are the most commonly forgotten parts.
6. THE DANGEROUS PARTS - code that deletes, sends money, emails customers, or writes to a shared system. Flag every one.
7. WHAT LOOKS INTENTIONAL BUT ODD - things that appear to be workarounds. Do not 'fix' these; they usually encode a real constraint. List them as open questions.
8. DEAD CODE CANDIDATES - unreachable or unused. Mark as candidates only, never certainties; dynamic dispatch and reflection hide callers.
9. WHAT I STILL DO NOT KNOW - the specific questions to answer before changing anything, ranked by risk.
10. THE FIRST SAFE CHANGE - given my goal, the lowest-risk way to start.

Mark every inference as an inference. In a legacy system, false confidence is the actual danger.

Write a migration guide.

FROM VERSION: [OLD]
TO VERSION: [NEW]
WHAT CHANGED:
```
[PASTE CHANGELOG, DIFF, OR DESCRIPTION]
```
WHO IS MIGRATING: [internal teams / external users / both]
HOW MANY KNOWN USERS/INTEGRATIONS: [SCALE]

Produce:

1. SHOULD YOU UPGRADE - the reasons to, the reasons to wait, and who can safely skip this version. Be honest; a guide that assumes everyone must upgrade loses trust.

2. BREAKING CHANGES - a table: What changed | Who is affected | Symptom if you do not act | Required change. Ordered by how many users it affects.

3. HOW TO TELL IF YOU ARE AFFECTED - for each breaking change, a specific check: a grep command, a config key to look for, a deprecation warning to search logs for. This is what makes a migration guide usable at scale.

4. STEP BY STEP - numbered, in the order that works. Mark which steps are reversible and which are not. Include a checkpoint after each risky step: how to verify it worked before continuing.

5. BEFORE YOU START - backups, version pins, a staging run, what to capture so you can compare after.

6. ROLLBACK - how to go back at each stage. Where rollback is impossible after a certain step, say so loudly and before that step.

7. DEPRECATED BUT STILL WORKING - what has a deprecation warning and when it will be removed. Give a real version or date.

8. TROUBLESHOOTING - the errors people will hit, with the literal message and the fix.

9. IF YOU ARE ON A MUCH OLDER VERSION - whether they can jump directly or must upgrade in stages.

Rules:
- Every code change shown as before/after, not described
- Literal error messages in section 8 so they are searchable
- Never say 'should be straightforward'