Design Docs and RFCs skill for Codex

Done well means a reviewer who has never seen the code can understand the problem, see why this design beats the alternatives, find the risks and how they are contained, and answer “approve, change, or reject” after one read. The doc is as long as the decision needs: two pages for a new internal endpoint, ten for a storage migration.

Before writing

1. Read AGENTS.md, then look for the team’s existing template and process: rg -il "rfc|design doc" docs/ .github/ --glob "*.md", folders such as docs/rfcs, docs/design, adr/. Use their template and numbering; do not invent a parallel one.
2. Gather facts from the repo: the modules involved, current data model, traffic or data volumes if available, existing ADRs that constrain the design. Cite paths.
3. Identify the decision makers and the deadline. A doc without an owner and a decision date drifts for months.
4. Ask the user for what code cannot tell you: business motivation, deadlines, who depends on the outcome, constraints from other teams. Do not invent numbers; mark unknowns as open questions.

Size the document

Change	Format
Local, reversible, one team (new endpoint, internal refactor)	No doc, or a half-page in the PR description
One significant, hard-to-reverse choice (pick a queue, a database)	Architecture decision record
New system, cross-team API, data migration, security-sensitive change	Full design doc / RFC
Org-wide standard or process change	RFC with a comment period and named approvers

Template

# RFC-0042: <Verb phrase: "Move session storage from Postgres to Redis">

| Status | Draft / In review / Accepted / Rejected / Superseded by RFC-00xx |
|---|---|
| Author(s) | |
| Reviewers / approvers | <names and the area each owns> |
| Decision needed by | <date> |
| Last updated | <date> |

## Summary
Three to five sentences: the problem, the proposal, the main trade-off.

## Context and problem
What is true today, with numbers and links. Why now. Who is affected.

## Goals
- Measurable outcomes ("p99 session lookup under 5 ms at 3x current load").

## Non-goals
- Things reviewers will assume are in scope but are not.

## Proposed design
Overview diagram, components, data model changes, API contracts, key algorithms.
Walk one request or record through the new system end to end.

## Alternatives considered
For each: what it is, why it was rejected (cost, risk, time, capability). Always include
"do nothing" and its cost.

## Migration and rollout
Phases, feature flags, backfills, dual-running, rollback at each phase, success criteria
for moving forward.

## Cross-cutting concerns
- Security and abuse: authn/authz changes, new trust boundaries, secrets.
- Privacy and data: new personal data, retention, residency.
- Reliability: failure modes, SLO impact, capacity.
- Observability: metrics, logs, traces, alerts added.
- Cost: infra and operational, now and at 10x.
- Operational load: on-call, runbooks, manual steps.

## Risks and mitigations
| Risk | Likelihood | Impact | Mitigation |

## Open questions
Numbered, each with an owner.

## Decision log
Date, decision, who decided, link to discussion.

Drop sections that truly do not apply, but write “Not applicable because …” for security, privacy and rollout rather than deleting them; reviewers look for those first.

Writing rules

• Lead with the decision being requested, not the history. Put the background in Context.
• Quantify: “the table has 180M rows, grows 4M per month” beats “the table is large”.
• Non-goals prevent half of all review arguments; write at least two.
• Alternatives must be real contenders described fairly. A straw-man list signals the decision was made before the doc.
• Every risk needs a mitigation or an explicit acceptance with an owner.
• Diagrams: one system context or sequence diagram in Mermaid usually beats three paragraphs. Keep source in the doc so it can be edited.
• Separate facts (cited), estimates (show the math) and opinions (labelled).
• Write for the reviewer who will skim: descriptive headings, short paragraphs, tables for comparisons.

Reviewing someone else’s doc

Read the summary and goals first, then ask:

Question	Red flag
Is the problem real and quantified?	No numbers, or the motivation is “best practice”
Do the goals and non-goals bound the scope?	Goals that cannot be measured
Does the design meet each goal?	A goal no section addresses
Were credible alternatives weighed?	Only straw men; no “do nothing”
How does it fail?	No failure modes, no rollback
How does it ship?	Big-bang cutover of data or traffic
What does it cost to run?	No capacity or cost estimate for a new system
Who operates it?	New infrastructure with no owner or runbook

Write review comments with a label (blocking, suggestion, question) and propose the change, as in a code review. Summarise into an overall recommendation.

Lifecycle

1. Draft: share with one or two close reviewers first to fix the obvious gaps.
2. In review: announce with a deadline (typically one to two weeks) and the specific feedback wanted. Publishing to a wider channel or sending the announcement is an outward-facing action: show the user the message and get a clear yes before posting.
3. Decision: record status, date, and approvers in the header and the decision log.
4. After build: link the implementation PRs; if the design changed materially, add an “As built” note rather than rewriting history. Superseded docs point to the successor.

Verification

• Every claim about the current system cites a file, dashboard or query. Spot-check three citations by opening them.
• Every goal maps to a section of the design and to a metric in rollout success criteria.
• The rollout has a rollback step for each phase that writes data.
• Run a markdown link check and render any Mermaid blocks if the tools are available.
• Ask: could a reviewer reject this doc with a reason the doc does not already address? If yes, add it to alternatives, risks, or open questions.

Gotchas

• Writing the doc after the code is merged turns review into rubber-stamping. If code exists, say so and frame the doc as a decision about whether to keep it.
• Solution-first summaries (“We will adopt Kafka”) hide the problem and invite tool debates. State the problem and constraints first.
• Ten-page docs for two-day changes train people to skip reading docs.
• Leaving open questions without owners or dates means they never close.

Output

Deliver the doc as a Markdown file at the team’s path (for example docs/rfcs/0042-session-storage.md) plus a chat summary:

**Drafted:** docs/rfcs/0042-session-storage.md (Status: Draft)
**Decision requested:** <one line>
**Facts verified from code:** <list with paths>
**Needs input from you:** <business numbers, deadlines, approver names>
**Open questions:** <count, top two>