Markdown templates with a reason for every section.

# Project name

A one-sentence description of what this project does and who it helps.

## Quick start

1. Install dependencies.
2. Configure the environment.
3. Start the application.

## Usage

Document the smallest successful workflow.

## Architecture

Explain the important boundaries and decisions.

## Contributing

Describe checks, review expectations, and release flow.

# ADR-000: Decision title

- Status: Proposed
- Date: YYYY-MM-DD
- Owners: Team or person

## Context

What decision is needed, and which constraints matter?

## Options considered

### Option A

Benefits and costs.

### Option B

Benefits and costs.

## Decision

State the choice and why it best fits the constraints.

## Consequences

Record positive, negative, and follow-up effects.

# Release 1.0.0

Released YYYY-MM-DD

## Highlights

- Describe the most useful change in user terms.
- Link to the relevant guide or migration.

## Added

- New capability.

## Changed

- Existing behavior that changed.

## Fixed

- User-visible issue that is now resolved.

## Migration notes

Steps required before or after upgrading.

## Known limitations

Be explicit about unfinished or constrained behavior.

# Complete a specific task

Explain the outcome and who this guide is for.

## Before you begin

- Required access
- Supported versions
- Expected time

## Procedure

### 1. Prepare

Explain the action and the evidence of success.

### 2. Make the change

Use a concrete example.

### 3. Verify

Describe how to prove the intended result.

## Troubleshooting

### Common failure

Cause, diagnostic, and safe resolution.

## Next steps

Link to the next meaningful workflow.

# Changelog

All notable changes to this project are documented here.

## Unreleased

### Added

- New capability.

### Changed

- Existing behavior that changed.

### Fixed

- User-visible defect that was corrected.

### Security

- Security-relevant change without exploit details.

## 1.0.0 - YYYY-MM-DD

### Added

- Initial supported release.

# Proposal: outcome-focused title

- Status: Draft
- Owner: Team or person
- Review by: YYYY-MM-DD

## Summary

State the decision and intended outcome in a short paragraph.

## Problem

Describe the user or operational problem with evidence.

## Goals

- Measurable outcome
- Required capability

## Non-goals

- Work intentionally outside this proposal

## Proposed approach

Explain the design, constraints, and important tradeoffs.

## Milestones

- [ ] Milestone one with exit evidence
- [ ] Milestone two with exit evidence

## Risks and mitigations

| Risk | Likelihood | Mitigation |
| --- | --- | --- |
| Example risk | Medium | Concrete response |

## Measurement

Define success, guardrails, and review timing.

## Decision requested

Name the approver and exact decision needed.

# Runbook: service or failure mode

- Owner: Team
- Severity: SEV level
- Last exercised: YYYY-MM-DD

## Trigger

Describe the alert, symptom, and impact threshold.

## Safety checks

- Confirm the environment and tenant scope.
- Preserve request, trace, and job identifiers.
- Do not copy credentials or private content into tickets.

## Diagnose

1. Check liveness and readiness.
2. Inspect privacy-safe metrics and recent deployments.
3. Bound the affected time window and workload.

## Contain

State reversible, authorized containment steps and stop conditions.

## Recover

Document the ordered recovery procedure and rollback.

## Verify

- [ ] Health and readiness are green.
- [ ] A representative user workflow succeeds.
- [ ] Backlog and error rate return to expected bounds.

## Communicate

Name the incident channel, status update owner, and update interval.

## Follow-up

Record evidence, root cause, corrective actions, and the next exercise date.