Artifact Templates

These templates are intentionally compact. Expand them only when the added detail changes a decision or avoids a real implementation mistake.

ADR Template

# ADR-00X: <Decision title>

## Status
Proposed | Accepted | Superseded

## Context
- What problem exists?
- What constraints matter?
- What change pressure is driving the decision?

## Options Considered
1. Option A
2. Option B
3. Option C

## Decision
What was chosen and why now?

## Trade-offs
- Cost we are accepting
- Risk we are accepting
- What becomes easier
- What becomes harder

## Consequences
- Immediate implications
- Migration implications
- Signals that would tell us to revisit this

RFC Template

# RFC: <Change title>

## Problem
What is broken, slow, risky, or constrained?

## Proposal
Describe the new direction at system level.

## Non-Goals
What this RFC does not try to solve.

## Affected Surfaces
- Routes
- APIs
- Modules
- Teams
- Release process

## Alternatives
What else was considered and why it is not preferred.

## Risks
- Runtime risk
- Migration risk
- Organizational risk

## Rollout
- Adoption path
- Backward-compatibility policy
- Success metrics

Performance Budget Template

# Frontend Performance Budget

## Route / Surface
- Name:
- Audience:
- Device/network profile:

## Budgets
- LCP:
- INP:
- CLS:
- Initial JS:
- Hydration time:

## Enforcement
- CI check:
- Production monitoring:
- Owner:

## Exception Process
- Who approves a temporary exception?
- When does it expire?

Migration Plan Template

# Migration Plan: <Capability or surface>

## Current State
- What exists today?
- What pain does it create?

## Target State
- What boundary or behavior should exist after migration?

## Phases
1. Stabilize current usage
2. Introduce new path
3. Migrate consumers
4. Remove legacy path

## Safety Checks
- Compatibility checks
- Observability checkpoints
- Rollback criteria

## Owners
- Primary owner
- Supporting teams

Deprecation Checklist

• Name the deprecated artifact clearly.
• Publish the replacement path.
• Mark the compatibility window.
• Add tooling warnings where possible.
• Track remaining consumers.
• Remove only after the communicated deadline or explicit migration completion.

Integrity Note for Public Artifacts

When publishing architecture artifacts externally, label them honestly:

• Real, sanitized: based on shipped work with private details removed
• Composite: combines several real experiences into one teaching example
• Illustrative: invented example used to explain a pattern

Credibility improves when the reader can tell which kind of artifact they are looking at.