Turn a decision into an ADR or the docs you skipped
Documentation is the task developers most want to hand off — writing code comments or documentation and summarizing recent code changes are top-five AI tasks, and documenting code is where 31% already rely mostly on AI. Architecture Decision Records especially: the reasoning is fresh in your head but writing it up is the chore that gets skipped, leaving the next engineer to reverse-engineer why the system is the way it is.
You are a staff engineer who writes crisp technical documentation. Turn my notes into a clear {{doc_type}} for other engineers. Audience and where this will live: {{audience}} My rough notes — the decision, the context, and the trade-offs I weighed: {{notes}} For an ADR, use this structure: Title; Status; Context (the problem and constraints); Decision (what we chose, stated plainly); Consequences (trade-offs, what gets harder, what we are now committed to); Alternatives considered (each with why we rejected it). Rules: - Use only the facts, decisions, and trade-offs in my notes. Do not invent benchmarks, requirements, dates, or alternatives I did not mention. Where a needed detail is clearly missing, insert "[TODO: confirm]" rather than filling it in. - Keep it concise and skimmable — short sections, active voice, no marketing language. - Preserve my technical decisions exactly; you are writing them up, not re-deciding them. - End with a short list of open questions a reviewer should resolve.
Fill in your details and the prompt updates live — then copy.
Title: Use Postgres row-level security for tenant isolation Status: Proposed Context: We host multiple tenants in one database. Application-level filtering has caused two cross-tenant data leaks this quarter. Decision: Enforce isolation with Postgres row-level security policies keyed on tenant_id, set per connection. Consequences: Strong database-level guarantee; every connection must set the tenant id or queries return nothing. Migrations get more complex. [TODO: confirm] performance impact under our load. Alternatives considered: separate database per tenant — rejected for operational overhead; continue app-level filtering — rejected after repeated leaks. Open questions: connection-pooler compatibility; rollout order across services.
The full workflow
- Brain-dump the decision, context, and trade-offs into rough notes first
- Generate the ADR or doc, then read it against what you actually decided
- Fill every "[TODO: confirm]" with a real value and delete anything the model inferred on its own
- Commit the doc alongside the code so it stays discoverable and versioned
Watch out for
The model fills gaps by inventing rationale, requirements, or alternatives you never considered. Docs are a source of truth other engineers act on — verify that every claim reflects the real decision.
Do not paste confidential architecture, security details, or proprietary code into a consumer tool. Internal design docs are trade secrets; use an approved, training-disabled tool.
AI can restate a decision but cannot own it. The engineering judgment in an ADR is yours, and a reviewer should still sign off on it.
Where this comes from
Every use case on this site is grounded in real reports from working software developers — not invented by us.