Tech Spec & RFC Library
Engineering teams that review designs before building
Engineering teams: write technical proposals, get them reviewed and log the decision.
Use this templateTech Spec & RFC Library
Write a short spec before building anything that is hard to undo. Reviewers comment, the author decides, and the decision is logged.
Review process
Specs dashboard
Decision log
Engineers
Specs
Open any spec to find the full outline (problem, goals, design, risks, rollout) already inside it.
| Spec | Status | Area | Author | Reviewer | Review deadline | Decision date |
|---|---|---|---|---|---|---|
| Retire the v1 API | Superseded | Marguerite Okoye | Yuki Hasegawa | Jun 10, 2026 | Jun 20, 2026 | |
| Move job queue from cron to a durable scheduler | Implemented | Cormac Delaney-Oyelaran | Anneliese Bergstrom | Jul 10, 2026 | Jul 20, 2026 | |
| Per-tenant rate limits on the public API | Implemented | Marguerite Okoye | Cormac Delaney-Oyelaran | Aug 9, 2026 | Aug 19, 2026 | |
| Adopt structured logging across services | Approved | Anneliese Bergstrom | Yuki Hasegawa | Sep 28, 2026 | Oct 4, 2026 | |
| Split the metrics store by retention tier | Approved | Lars Eriksson-Cho | Cormac Delaney-Oyelaran | Oct 6, 2026 | Oct 10, 2026 | |
| Introduce feature flags for risky releases | In review | Cormac Delaney-Oyelaran | Yuki Hasegawa | Oct 9, 2026 | Oct 29, 2026 | |
| Batch the nightly billing export | In review | Lars Eriksson-Cho | Marguerite Okoye | Oct 14, 2026 | Oct 27, 2026 | |
| Replace session cookies with short-lived tokens | In review | Zainab Farouk | Anneliese Bergstrom | Oct 18, 2026 | Oct 24, 2026 |
Recent decisions
| Decision | Spec | Reason | Decided |
|---|---|---|---|
| Keep 7 days hot, 90 days warm | Split the metrics store by retention tier | Query patterns show nobody reads older data live. | Oct 9, 2026 |
| Emit JSON logs with a request id | Adopt structured logging across services | Search across services needs one shape. | Oct 2, 2026 |
| Limit by tenant, not by IP | Per-tenant rate limits on the public API | Large customers share office addresses. | Aug 17, 2026 |
| Use a managed durable scheduler | Move job queue from cron to a durable scheduler | Cron jobs were lost whenever a host restarted. | Jul 18, 2026 |
| Retire v1 after two releases | Retire the v1 API | Fewer than 2% of calls still use it. | Jun 15, 2026 |
Write the spec from the outline and set a review deadline at least five working days out.
Ask one named reviewer and post the link in the engineering channel.
Comment in the doc. Reviewers say what they would change and why.
Decide by the deadline. The author makes the call and writes the reason.
Log the decision, mark the spec Approved, and link follow-up tasks.
When a spec is not needed
Reversible changes under a few days of work do not need a spec.
When to ask for a second reviewer
Security, billing or anything touching customer data.
| Spec | Status | Area | Author | Reviewer | Review deadline | Decision date |
|---|---|---|---|---|---|---|
| Retire the v1 API | Superseded | Marguerite Okoye | Yuki Hasegawa | Jun 10, 2026 | Jun 20, 2026 | |
| Move job queue from cron to a durable scheduler | Implemented | Cormac Delaney-Oyelaran | Anneliese Bergstrom | Jul 10, 2026 | Jul 20, 2026 | |
| Per-tenant rate limits on the public API | Implemented | Marguerite Okoye | Cormac Delaney-Oyelaran | Aug 9, 2026 | Aug 19, 2026 | |
| Adopt structured logging across services | Approved | Anneliese Bergstrom | Yuki Hasegawa | Sep 28, 2026 | Oct 4, 2026 | |
| Split the metrics store by retention tier | Approved | Lars Eriksson-Cho | Cormac Delaney-Oyelaran | Oct 6, 2026 | Oct 10, 2026 | |
| Introduce feature flags for risky releases | In review | Cormac Delaney-Oyelaran | Yuki Hasegawa | Oct 9, 2026 | Oct 29, 2026 | |
| Batch the nightly billing export | In review | Lars Eriksson-Cho | Marguerite Okoye | Oct 14, 2026 | Oct 27, 2026 | |
| Replace session cookies with short-lived tokens | In review | Zainab Farouk | Anneliese Bergstrom | Oct 18, 2026 | Oct 24, 2026 |
| Spec | Status | Area | Author | Reviewer | Review deadline | Decision date |
|---|---|---|---|---|---|---|
| Retire the v1 API | Superseded | Marguerite Okoye | Yuki Hasegawa | Jun 10, 2026 | Jun 20, 2026 | |
| Move job queue from cron to a durable scheduler | Implemented | Cormac Delaney-Oyelaran | Anneliese Bergstrom | Jul 10, 2026 | Jul 20, 2026 | |
| Per-tenant rate limits on the public API | Implemented | Marguerite Okoye | Cormac Delaney-Oyelaran | Aug 9, 2026 | Aug 19, 2026 | |
| Adopt structured logging across services | Approved | Anneliese Bergstrom | Yuki Hasegawa | Sep 28, 2026 | Oct 4, 2026 | |
| Split the metrics store by retention tier | Approved | Lars Eriksson-Cho | Cormac Delaney-Oyelaran | Oct 6, 2026 | Oct 10, 2026 | |
| Introduce feature flags for risky releases | In review | Cormac Delaney-Oyelaran | Yuki Hasegawa | Oct 9, 2026 | Oct 29, 2026 | |
| Batch the nightly billing export | In review | Lars Eriksson-Cho | Marguerite Okoye | Oct 14, 2026 | Oct 27, 2026 | |
| Replace session cookies with short-lived tokens | In review | Zainab Farouk | Anneliese Bergstrom | Oct 18, 2026 | Oct 24, 2026 |
| Spec | Status | Area | Author | Reviewer | Review deadline | Decision date |
|---|---|---|---|---|---|---|
| Retire the v1 API | Superseded | Marguerite Okoye | Yuki Hasegawa | Jun 10, 2026 | Jun 20, 2026 | |
| Move job queue from cron to a durable scheduler | Implemented | Cormac Delaney-Oyelaran | Anneliese Bergstrom | Jul 10, 2026 | Jul 20, 2026 | |
| Per-tenant rate limits on the public API | Implemented | Marguerite Okoye | Cormac Delaney-Oyelaran | Aug 9, 2026 | Aug 19, 2026 | |
| Adopt structured logging across services | Approved | Anneliese Bergstrom | Yuki Hasegawa | Sep 28, 2026 | Oct 4, 2026 | |
| Split the metrics store by retention tier | Approved | Lars Eriksson-Cho | Cormac Delaney-Oyelaran | Oct 6, 2026 | Oct 10, 2026 | |
| Introduce feature flags for risky releases | In review | Cormac Delaney-Oyelaran | Yuki Hasegawa | Oct 9, 2026 | Oct 29, 2026 | |
| Batch the nightly billing export | In review | Lars Eriksson-Cho | Marguerite Okoye | Oct 14, 2026 | Oct 27, 2026 | |
| Replace session cookies with short-lived tokens | In review | Zainab Farouk | Anneliese Bergstrom | Oct 18, 2026 | Oct 24, 2026 |
High risk, not yet approved
| Spec | Status | Area | Author | Reviewer | Review deadline | Decision date |
|---|---|---|---|---|---|---|
| Retire the v1 API | Superseded | Marguerite Okoye | Yuki Hasegawa | Jun 10, 2026 | Jun 20, 2026 | |
| Move job queue from cron to a durable scheduler | Implemented | Cormac Delaney-Oyelaran | Anneliese Bergstrom | Jul 10, 2026 | Jul 20, 2026 | |
| Per-tenant rate limits on the public API | Implemented | Marguerite Okoye | Cormac Delaney-Oyelaran | Aug 9, 2026 | Aug 19, 2026 | |
| Adopt structured logging across services | Approved | Anneliese Bergstrom | Yuki Hasegawa | Sep 28, 2026 | Oct 4, 2026 | |
| Split the metrics store by retention tier | Approved | Lars Eriksson-Cho | Cormac Delaney-Oyelaran | Oct 6, 2026 | Oct 10, 2026 | |
| Introduce feature flags for risky releases | In review | Cormac Delaney-Oyelaran | Yuki Hasegawa | Oct 9, 2026 | Oct 29, 2026 | |
| Batch the nightly billing export | In review | Lars Eriksson-Cho | Marguerite Okoye | Oct 14, 2026 | Oct 27, 2026 | |
| Replace session cookies with short-lived tokens | In review | Zainab Farouk | Anneliese Bergstrom | Oct 18, 2026 | Oct 24, 2026 |
Reviews due soon
| Spec | Status | Area | Author | Reviewer | Review deadline | Decision date |
|---|---|---|---|---|---|---|
| Retire the v1 API | Superseded | Marguerite Okoye | Yuki Hasegawa | Jun 10, 2026 | Jun 20, 2026 | |
| Move job queue from cron to a durable scheduler | Implemented | Cormac Delaney-Oyelaran | Anneliese Bergstrom | Jul 10, 2026 | Jul 20, 2026 | |
| Per-tenant rate limits on the public API | Implemented | Marguerite Okoye | Cormac Delaney-Oyelaran | Aug 9, 2026 | Aug 19, 2026 | |
| Adopt structured logging across services | Approved | Anneliese Bergstrom | Yuki Hasegawa | Sep 28, 2026 | Oct 4, 2026 | |
| Split the metrics store by retention tier | Approved | Lars Eriksson-Cho | Cormac Delaney-Oyelaran | Oct 6, 2026 | Oct 10, 2026 | |
| Introduce feature flags for risky releases | In review | Cormac Delaney-Oyelaran | Yuki Hasegawa | Oct 9, 2026 | Oct 29, 2026 | |
| Batch the nightly billing export | In review | Lars Eriksson-Cho | Marguerite Okoye | Oct 14, 2026 | Oct 27, 2026 | |
| Replace session cookies with short-lived tokens | In review | Zainab Farouk | Anneliese Bergstrom | Oct 18, 2026 | Oct 24, 2026 |
A decision is one sentence and the reason behind it. Log it the day it is made, link it to the spec it belongs to, and nobody has to remember why in a year.
Write the reason, not just the choice. “We chose Postgres” ages badly; “We chose Postgres because reporting needs joins” does not.
| Decision | Spec | Reason | Decided |
|---|---|---|---|
| Keep 7 days hot, 90 days warm | Split the metrics store by retention tier | Query patterns show nobody reads older data live. | Oct 9, 2026 |
| Emit JSON logs with a request id | Adopt structured logging across services | Search across services needs one shape. | Oct 2, 2026 |
| Limit by tenant, not by IP | Per-tenant rate limits on the public API | Large customers share office addresses. | Aug 17, 2026 |
| Use a managed durable scheduler | Move job queue from cron to a durable scheduler | Cron jobs were lost whenever a host restarted. | Jul 18, 2026 |
| Retire v1 after two releases | Retire the v1 API | Fewer than 2% of calls still use it. | Jun 15, 2026 |
What's inside
3 tables · 10 views · 1 form · 1 row action · 1 agent5 pages
- Tech Spec & RFC Library
- Review process
- Specs dashboard
- Decision log
- Engineers
2 tables
- Specs8 views · 11 sample rows
- Decision log1 view · 5 sample rows
Related workspaces
- Design System DocsDesign and front-end teams: document components, usage rules, owners and status.3 pages · Docs & wikis
- Docs HubTeams that write a lot: every document in one place with status, owner and review.5 pages · Docs & wikis
- Release Notes & API DocsProduct and developer teams: release notes, a public changelog and an API reference.5 pages · Docs & wikis
- Team Wiki & Company HomeCompanies of 10 to 200: a company home with news, team pages and a wiki that stays fresh.5 pages · Docs & wikis
- SOP LibraryTeams: write down how work gets done, with owners, approvers and review dates.4 pages · Docs & wikis
- Account CRM for ConsultantsConsultants and B2B firms: companies first, then their contacts, deals and follow-ups.4 pages · Sales