Drafts an architecture decision record (ADR) that documents why a technical choice was made, what alternatives were considered, and what consequences to expect. Use it whenever you make a significant design or infrastructure decision so the reasoning survives beyond the meeting.
SYSTEM OR SERVICE NAME ·DECISION TITLE ·CONTEXT AND PROBLEM ·DECISION ·ALTERNATIVES CONSIDERED ·CONSEQUENCES AND TRADE-OFFS ·STATUS ·DATE AND OWNER
## Context
You are a technical writing assistant helping an engineer or architect document a significant design decision. The audience is the engineering team and future maintainers who need to understand not just what was decided but why, and what the team gave up by not choosing the alternatives.
System or service name: [SYSTEM OR SERVICE NAME]
Decision title: [DECISION TITLE]
Context and problem being solved: [CONTEXT AND PROBLEM]
Decision made: [DECISION]
Alternatives considered: [ALTERNATIVES CONSIDERED]
Consequences and trade-offs: [CONSEQUENCES AND TRADE-OFFS]
Status (proposed, accepted, deprecated, superseded): [STATUS]
Date and decision owner: [DATE AND OWNER]
## Task
Draft an ADR with these sections: Title, Status, Context, Decision, Alternatives Considered, Consequences, and Notes.
## Standards
- Plain technical language. Write for an engineer who was not in the room.
- Context states the problem as it existed before the decision, not the solution.
- Decision is one or two sentences naming exactly what was chosen and why it beat the alternatives.
- Alternatives Considered lists each option with its key trade-off. Minimum two alternatives.
- Consequences states what the team gains and what it gives up. Include operational, security, and maintenance implications where applicable.
- Do not invent technology names, version numbers, performance figures, or integration details the user did not supply.
- Notes section is optional. Use it only for links, follow-on decisions, or review dates the user provides.
- Do not fabricate CVEs, known vulnerabilities, or security claims for any technology named.
- If any named input is missing or ambiguous, ask before drafting.
## Verification checklist (embedded reminder)
Before using this ADR: confirm every technology name and version, confirm every trade-off claim against your team's actual testing or documented knowledge, and confirm status with the decision owner.
BEFORE YOU RUN IT
- The exact decision made, in one or two plain sentences
- At least two alternatives that were genuinely considered, with the reason each was rejected
- Known consequences: what the team gains, what it gives up, and any follow-on decisions created
- Confirm all technology names, version numbers, and performance claims come from your team's own research or testing, not from the AI
- Redact any credentials, internal IP ranges, customer data, or classified information before pasting context, per your org policy
- Status of the decision and the name or role of the decision owner
VERIFY BEFORE IT LEAVES YOUR HANDS
- Every technology name and version number checked against your actual environment or procurement records
- Trade-off claims verified against your team's testing, spike results, or documented benchmarks, not the AI's general knowledge
- No CVEs or known vulnerabilities cited that the AI introduced without your supplying them
- Alternatives section reflects what your team actually considered, not plausible options the AI added on its own
- Consequences match your team's real experience with the chosen technology
- Status and owner confirmed with the person named before the ADR is committed to your repo
- ADR reviewed by at least one other engineer who was present for the decision before it is marked accepted
Sample output
Sample output. Generated by AI from sample inputs:
# ADR-014: Use PostgreSQL for the Northwind Inventory Service
**Status:** Accepted
**Date:** 2026-06-10
**Owner:** Platform Engineering, J. Calloway
## Context
The Northwind Inventory Service needs a persistent store for SKU records, stock levels, and transaction history. The team evaluated storage options during the Q2 architecture review. The service handles roughly 40,000 writes per day with moderate read traffic. Strong consistency on stock-level updates is a hard requirement; a double-decrement on the same SKU causes fulfillment errors.
## Decision
Use PostgreSQL 16 as the primary data store. It provides the ACID (atomicity, consistency, isolation, durability) guarantees the stock-level update pattern requires, and the team already operates a managed PostgreSQL cluster on the company's cloud platform.
## Alternatives Considered
**DynamoDB:** Offers near-unlimited scale and low operational overhead, but eventual consistency on stock counters without careful application-side locking would require significant extra work to avoid double-decrements. Rejected because the consistency model adds complexity that offsets the operational savings.
**MongoDB:** Document model fits the SKU catalog well, but multi-document transactions carry a performance cost and the team lacks MongoDB operational experience. Rejected on operational risk.
## Consequences
Gains: Strong consistency on stock writes, familiar operational tooling, straightforward migration path from the existing prototype. Gives up: horizontal write scaling beyond a single primary node; if write volume grows beyond current projections, a sharding strategy will be needed. Follow-on decision required: connection pool sizing for the inventory service container fleet.
## Notes
Revisit if daily write volume exceeds 500,000. See ADR-011 for the managed database platform choice.
CUSTOMIZATION Add a Compliance or Security section if your org requires documenting security implications of architectural choices, such as data residency or encryption decisions. For government or regulated environments, link the ADR to the relevant control framework control, for example NIST SP 800-53 (National Institute of Standards and Technology Special Publication) or FedRAMP (Federal Risk and Authorization Management Program). Teams using a numbered ADR format should include the number in the title variable. If your organization uses a specific ADR template, paste it as a formatting guide.
Outage Postmortem
OPEN SAMPLE Drafts a blameless outage postmortem from your incident timeline and notes. Use it within 48 to 72 hours of an incident, while the details are fresh, to capture what happened and what the team is doing about it.
INCIDENT TITLE AND ID ·DATE AND DURATION ·SEVERITY ·SERVICES AFFECTED ·IMPACT SUMMARY ·INCIDENT TIMELINE ·ROOT CAUSE ANALYSIS ·CONTRIBUTING FACTORS ·WHAT WENT WELL ·ACTION ITEMS
## Context
You are a technical writing assistant helping an engineering team produce a blameless postmortem after a production incident. The audience is the engineering team, engineering management, and in some organizations, affected customers or stakeholders. The goal is to understand what happened and prevent recurrence, not to assign blame.
Incident title and ID: [INCIDENT TITLE AND ID]
Date and duration: [DATE AND DURATION]
Severity: [SEVERITY]
Services affected: [SERVICES AFFECTED]
Impact summary: [IMPACT SUMMARY]
Incident timeline (chronological, with timestamps): [INCIDENT TIMELINE]
Root cause analysis: [ROOT CAUSE ANALYSIS]
Contributing factors: [CONTRIBUTING FACTORS]
What went well: [WHAT WENT WELL]
Action items with owners and due dates: [ACTION ITEMS]
## Task
Draft a postmortem with these sections: Incident Summary, Timeline, Root Cause, Contributing Factors, Impact, What Went Well, Action Items, and Lessons Learned.
## Standards
- Blameless throughout. No individual names tied to mistakes. Engineers as a team made decisions with the information available at the time.
- Timeline is chronological with timestamps from the user's notes. Do not infer or fill in events the user did not supply.
- Root Cause is what the team identified from their own investigation. Do not speculate beyond what the user provides.
- Impact uses the user's numbers. Do not estimate user counts, revenue impact, or error rates the user did not give.
- Action items are specific and assigned: what, who, by when. Mark any field the user left blank as [OWNER?] or [DUE DATE?].
- Do not fabricate log lines, error messages, hostnames, metric values, or alert names.
- Do not invent CVEs, vulnerabilities, or security findings.
- If the timeline has gaps or the root cause is still under investigation, say so clearly rather than filling the gap.
- If any input is missing or ambiguous, ask before drafting.
BEFORE YOU RUN IT
- A chronological incident timeline with real timestamps from your monitoring, ticketing, or on-call tools
- Your team's own root cause conclusion, even if it is preliminary or still under investigation
- Impact numbers from your monitoring tools or support data, not estimates
- Confirm all log excerpts, metric values, hostnames, and error messages come from your own systems, not from the AI
- Redact any customer PII (personally identifiable information), credentials, or sensitive internal data before pasting, per your org policy
- Action items with a named owner and a due date for each, even if approximate
VERIFY BEFORE IT LEAVES YOUR HANDS
- Every timeline event traceable to a real source: a monitoring alert, a ticket, a chat message, a log entry you pulled yourself
- No log lines, metric values, or error messages present that you did not supply
- Root cause section matches what your team concluded, not what the AI inferred from the symptoms
- Impact figures verified against your actual monitoring dashboards or support ticket counts
- Action items reviewed by the owners named before the document is published
- Blameless tone confirmed throughout: re-read every sentence for individual finger-pointing
- Draft shared with the incident commander or engineering lead for accuracy before distribution
Sample output
Sample output. Generated by AI from sample inputs:
# Postmortem: Database Connection Pool Exhaustion (INC-2026-0412)
**Date:** 2026-06-09
**Duration:** 47 minutes (14:22-15:09 UTC)
**Severity:** SEV-2
**Services affected:** Northwind Order API, Northwind Customer Portal
**Written by:** Platform Engineering team
## Incident Summary
On 2026-06-09, the Northwind Order API became unavailable for 47 minutes due to database connection pool exhaustion on DB-PRIMARY-01. Customer-facing order placement was unavailable. Browsing and authentication were unaffected. The incident was resolved by restarting the API service, which released stale connections, and by deploying a configuration change to reduce the per-instance connection limit.
## Timeline
| Time (UTC) | Event |
|---|---|
| 14:22 | PagerDuty alert: Order API health check failing |
| 14:24 | On-call engineer acknowledged alert |
| 14:31 | Database connection count confirmed at 500/500 (pool exhausted) |
| 14:38 | Decision made to restart API pods to release stale connections |
| 14:44 | First API pod restarted; partial recovery observed |
| 14:55 | All API pods restarted; service recovered |
| 15:09 | Incident declared resolved after 10-minute monitoring window |
## Root Cause
A deployment at 13:55 UTC increased the number of Order API instances from 4 to 8 as part of a planned scale-up for the summer traffic period. The per-instance connection pool limit was not adjusted. The 8 instances collectively opened 500 connections, exhausting the database's configured maximum.
## Contributing Factors
- The deployment runbook did not include a step to recalculate the per-instance pool limit when instance count changes.
- The database connection limit was not included in the pre-deployment checklist.
- No alert existed for database connection count approaching the ceiling.
## Impact
Order placement was unavailable for approximately 47 minutes. Per support data, 312 order attempts failed during the window. No data loss occurred.
## What Went Well
- On-call was paged within 2 minutes of the first failing health check.
- The team correctly identified the root cause within 9 minutes of acknowledging the alert.
- The database connection metric was available in the existing dashboard; detection was fast once the engineer looked.
## Action Items
| Action | Owner | Due |
|---|---|---|
| Add per-instance connection pool recalculation step to scale-up runbook | T. Reyes | 2026-06-16 |
| Create alert for database connections above 80% of configured maximum | D. Park | 2026-06-16 |
| Add database connection ceiling to pre-deployment checklist | Platform Engineering | 2026-06-20 |
## Lessons Learned
Scale-up events need a connection budget review as a required step, not an afterthought. A single alert on database connection headroom would have surfaced this before customers were affected.
CUSTOMIZATION For customer-facing postmortems, strip internal hostnames and tool names and replace them with plain descriptions. If your org tracks a five-whys analysis, add a [FIVE WHYS] input variable and request a five-whys section after Root Cause. Security incidents may require a separate security-specific postmortem format for audit or compliance purposes; check with your security team before using this template for a security incident.