Author and maintain Architecture Decision Records (ADRs) for Salesforce implementations: capture chosen approach, rejected alternatives, constraints, and consequences. Trigger keywords: adr, architecture decision record, design decision log, technical decision. NOT for making the design decision itself, e.g. Flow vs Apex — use architect/solution-design-patterns. NOT for a formal architecture review that produces findings — use architect/well-architected-review.
An ADR's real product is not the decision. It is the recorded premise — the
volumes, limits, and requirements the decision depended on. That is what lets a
future team test whether the choice still holds rather than re-litigating it,
and it is the part most ADRs omit.
On Salesforce specifically, two things make ADR discipline harder than
elsewhere: three major releases a year expire premises fast, and the platform's
lifecycle churn (product end-of-sale, feature retirement, GA dates) invites
confident unsourced claims into a document that is deliberately never updated.
ADR Candidacy
Promote a decision to ADR when any of these holds:
Multi-quarter impact — platform choice (Flow vs Apex vs Agentforce),
pattern adoption (Trigger Handler, Selector Layer), org topology (single-org
vs multi-org), integration approach, sharing model, licensing posture.
Reversal of an earlier recorded choice — always a new ADR that supersedes;
never a deletion, never an edit.
The 6-month test — a joiner will ask "why did we do this?" and needs a
document to read.
Out of scope:
Applying an existing ADR to a new object or class. That is a line in the
PR description — "Follows ADR-0003 (TriggerHandler framework)."
Task-level tradeoffs.
Anything fully internal to one feature's lifecycle.
The test: if it fits in a PR description, it is not an ADR.
The corollary, which is more useful: if you cannot name two alternatives a
competent person could actually have chosen, the decision was not open — you are
documenting a standard, not deciding.
ADRs And Decision Trees Are Different Layers
This repository has standards/decision-trees/. An ADR that re-derives one of
those trees is a fork waiting to diverge — and the first tree update makes them
contradict each other.
Decision tree
ADR
Scope
organisation-wide routing rule
one situation
Answers
"which technology for this shape of problem?"
"which branch applied here, and what was true?"
Lifecycle
updated as the platform changes
frozen on acceptance
When a tree routes the decision, the ADR records the branch and the
inputs, not the reasoning:
## Decision Trees Consulted
- `automation-selection.md` — Q1 (scheduled clock) → Q10 (>50k records) → Batch Apex
- `async-selection.md` — Q9 (needs ad hoc re-run) → Schedulable wrapper
Inputs at the time of this decision:
- 1.9M Account rows today; ~3.4M projected after the Q3 acquisition
- Business requirement: accurate by 07:00 daily
Two cases still need an ADR even when a tree answered:
You are deviating from the tree. Record the branch, why this situation is
the exception, and what would end the exception. A deviation with no ADR is
indistinguishable from an error.
The tree does not cover the scenario. Write the ADR, and raise the gap so
the tree can be extended — do not force-fit.
And the inverse: when the same decision recurs identically across teams, it
belongs in the tree, not in a fourth ADR.
Required Sections
Standard Nygard structure, one file per decision in docs/adr/:
Title — ADR-XXXX: <one-line decision>
Status — Proposed / Accepted / Rejected / Superseded by ADR-YYYY (with date)
Context — the forces, the constraints, and the inputs the decision depended on
Decision — the choice, in the active voice
Consequences — positive and at least one specific, checkable negative
Alternatives Considered — at least two that a competent person could have chosen
Date — the decision date, ISO-8601, never updated
Deciders — named people with the role they held at the time, plus the forum
Plus, on Salesforce:
Decision Trees Consulted — branch and question numbers, or an explicit "no tree covers this"
Review Trigger — where the decision rests on a current platform limitation rather than a principle, with a named owner
Sourcing Platform Claims
An ADR is the worst possible place for an unsourced lifecycle date, because
ADRs are deliberately not updated. A wrong date in a design doc is corrected
next sprint; a wrong date in an ADR stays load-bearing forever.
Every lifecycle, retirement, GA, or limit claim needs one of:
a Salesforce-hosted URL, or
a named person and the date they confirmed it.
Consultancy blogs are not sources for an architecture record. Where a claim
cannot be verified, mark it inline rather than laundering it:
<!-- UNVERIFIED: a specific end-of-sale date of 27 March 2025 circulates
widely in consultancy writing. Not confirmed from a Salesforce source. -->
The same applies to managed-package constraints: record the package name, the
version tested, and how the constraint was established, so a future reader
can re-test it instead of assuming it still holds.
Recommended Workflow
Apply the candidacy test. If it fits in a PR description, or you cannot name
two viable alternatives, stop — this is not an ADR.
Check standards/decision-trees/ before writing. If a tree routes this,
record the branch and the inputs rather than re-deriving the reasoning. If
you are deviating from the tree, say so explicitly and name what would end
the exception.
Draft from templates/adr-template.md (Status = Proposed only if a real
review forum exists; otherwise write it Accepted and retrospective), and
source every platform claim as you go — Salesforce URL, or a named person
and date. Mark anything unverifiable inline. Record package name, version
tested, and method for package-attributed constraints.
Force the negatives. Ask what the team writing the superseding ADR will
complain about, and write that down. If nothing comes to mind, this was not
a tradeoff.
Add a Review Trigger with a named owner wherever the decision rests on a
current platform limitation or on a pending vendor decision. A calendar date
is not a trigger — a condition is.
Mark Accepted with the date and named deciders, update docs/adr/INDEX.md
including the open review triggers table, and cite the ADR number in
subsequent PR descriptions.
On supersession: write a new ADR, flip the old one's Status line and nothing
else, link both ways, and state whether a premise expired or a mistake
was found — they teach different lessons.
Review Checklist
Passes the candidacy test; two genuinely viable alternatives exist
Decision trees checked; branch cited, or "no tree covers this" stated
Deviation from a tree, if any, is explicit with an end condition
Context records the inputs (volumes, limits, requirements), not just narrative
Every platform lifecycle claim has a Salesforce URL or a named confirmer + date
Unverifiable claims marked inline, not asserted
Managed-package constraints carry package name, version tested, and method
At least one specific, checkable negative consequence
Review Trigger present where the decision rests on a current limitation, with an owner
Deciders are named people with roles held at the time
Date is the decision date and has never been updated
Global four-digit numbering, one directory, in the repo the decision governs
INDEX.md updated, including the open-triggers table
Supersession links resolve both ways; the superseded body is untouched
Fits on roughly one page; the design doc is linked, not inlined
Worked Examples (see references/examples.md)
A decision the tree already answers — record the branch, not the reasoning
A sharing model decision — where the ordering is the decision
A platform lifecycle decision — deciding to wait, with named triggers
Supersession done properly — a premise expiring, not a mistake
A decision that should not have been an ADR — and where it belongs instead
The index — including the open-review-triggers table
Common Gotchas (see references/gotchas.md)
An ADR that re-derives a decision tree is a fork waiting to diverge
Three releases a year expire ADR premises faster than most platforms
"Decide to wait" is a decision, and the one nobody writes down
A named managed-package constraint is a fact with a version number
Org strategy ADRs need the licensing consequence, not just the topology
Never edit the body of a superseded ADR
Proposed ADRs rot silently
Top LLM Anti-Patterns (full list in references/llm-anti-patterns.md)
Re-deriving a decision tree inside the ADR
Alternatives Considered populated with strawmen
Consequences that are all positive
Editing the superseded ADR instead of superseding it
An ADR for every decision
An ADR as a design specification
Stating platform lifecycle facts without sourcing or dating them
"Decide to wait" left unwritten, or written without triggers
Related
architect/solution-design-patterns — for making the decision. This skill
is for recording it.
architect/well-architected-review — a review that produces findings, which
is a different artifact with a different lifecycle.
standards/decision-trees/README.md — the layer above ADRs. Read the
relevant tree before writing an ADR about a technology choice.
Official Sources Used
See references/well-architected.md for the full source list, including an
explicit caveat on the CPQ lifecycle claims used in the worked examples.
1---2name: architecture-decision-records3description: "Author and maintain Architecture Decision Records (ADRs) for Salesforce implementations: capture chosen approach, rejected alternatives, constraints, and consequences. Trigger keywords: adr, architecture decision record, design decision log, technical decision. NOT for making the design decision itself, e.g. Flow vs Apex — use architect/solution-design-patterns. NOT for a formal architecture review that produces findings — use architect/well-architected-review."4category: architect5salesforce-version: "Spring '25+"6well-architected-pillars:7 - Operational Excellence8 - Reliability9triggers:10 - architecture decision record11 - adr template12 - design decision log13 - technical rationale document14 - how do we record why we chose this approach15tags:16 - architect17 - adr18 - governance19 - documentation20 - decision-log21inputs:22 - A non-trivial technical decision (platform choice, pattern adoption, org topology)23 - Alternatives considered and the evaluation criteria24outputs:25 - One ADR file per decision, numbered, dated, statused26 - Index updated with new entry + any superseded links27dependencies:28 - architect/solution-design-patterns29version: 1.0.130author: Pranav Nagrecha31updated: 2026-08-1432metadata:33 source: https://skillmd.com/skills/pranavnagrecha/architecture-decision-records34---3536# Architecture Decision Records3738An ADR's real product is not the decision. It is the recorded **premise** — the39volumes, limits, and requirements the decision depended on. That is what lets a40future team test whether the choice still holds rather than re-litigating it,41and it is the part most ADRs omit.4243On Salesforce specifically, two things make ADR discipline harder than44elsewhere: three major releases a year expire premises fast, and the platform's45lifecycle churn (product end-of-sale, feature retirement, GA dates) invites46confident unsourced claims into a document that is deliberately never updated.4748---4950## ADR Candidacy5152Promote a decision to ADR when **any** of these holds:5354- **Multi-quarter impact** — platform choice (Flow vs Apex vs Agentforce),55 pattern adoption (Trigger Handler, Selector Layer), org topology (single-org56 vs multi-org), integration approach, sharing model, licensing posture.57- **Reversal of an earlier recorded choice** — always a new ADR that supersedes;58 never a deletion, never an edit.59- **The 6-month test** — a joiner will ask "why did we do this?" and needs a60 document to read.6162Out of scope:6364- Applying an **existing** ADR to a new object or class. That is a line in the65 PR description — `"Follows ADR-0003 (TriggerHandler framework)."`66- Task-level tradeoffs.67- Anything fully internal to one feature's lifecycle.6869**The test:** if it fits in a PR description, it is not an ADR.70**The corollary, which is more useful:** if you cannot name two alternatives a71competent person could actually have chosen, the decision was not open — you are72documenting a standard, not deciding.7374---7576## ADRs And Decision Trees Are Different Layers7778This repository has `standards/decision-trees/`. An ADR that re-derives one of79those trees is a fork waiting to diverge — and the first tree update makes them80contradict each other.8182| | Decision tree | ADR |83|---|---|---|84| Scope | organisation-wide routing rule | one situation |85| Answers | "which technology for this *shape* of problem?" | "which branch applied *here*, and what was true?" |86| Lifecycle | updated as the platform changes | frozen on acceptance |8788When a tree routes the decision, the ADR records the **branch** and the89**inputs**, not the reasoning:9091```markdown92## Decision Trees Consulted93- `automation-selection.md` — Q1 (scheduled clock) → Q10 (>50k records) → Batch Apex94- `async-selection.md` — Q9 (needs ad hoc re-run) → Schedulable wrapper9596Inputs at the time of this decision:97- 1.9M Account rows today; ~3.4M projected after the Q3 acquisition98- Business requirement: accurate by 07:00 daily99```100101Two cases still need an ADR even when a tree answered:1021031. **You are deviating from the tree.** Record the branch, why this situation is104 the exception, and what would end the exception. A deviation with no ADR is105 indistinguishable from an error.1062. **The tree does not cover the scenario.** Write the ADR, and raise the gap so107 the tree can be extended — do not force-fit.108109And the inverse: when the same decision recurs identically across teams, it110belongs in the *tree*, not in a fourth ADR.111112---113114## Required Sections115116Standard Nygard structure, one file per decision in `docs/adr/`:1171181. **Title** — `ADR-XXXX: <one-line decision>`1192. **Status** — Proposed / Accepted / Rejected / Superseded by ADR-YYYY (with date)1203. **Context** — the forces, the constraints, and the **inputs** the decision depended on1214. **Decision** — the choice, in the active voice1225. **Consequences** — positive **and** at least one specific, checkable negative1236. **Alternatives Considered** — at least two that a competent person could have chosen1247. **Date** — the decision date, ISO-8601, never updated1258. **Deciders** — named people with the role they held at the time, plus the forum126127Plus, on Salesforce:1281299. **Decision Trees Consulted** — branch and question numbers, or an explicit "no tree covers this"13010. **Review Trigger** — where the decision rests on a *current platform limitation* rather than a principle, with a named owner131132---133134## Sourcing Platform Claims135136An ADR is the worst possible place for an unsourced lifecycle date, because137ADRs are deliberately not updated. A wrong date in a design doc is corrected138next sprint; a wrong date in an ADR stays load-bearing forever.139140Every lifecycle, retirement, GA, or limit claim needs one of:141142- a **Salesforce-hosted URL**, or143- a **named person and the date they confirmed it**.144145Consultancy blogs are not sources for an architecture record. Where a claim146cannot be verified, mark it inline rather than laundering it:147148```markdown149<!-- UNVERIFIED: a specific end-of-sale date of 27 March 2025 circulates150widely in consultancy writing. Not confirmed from a Salesforce source. -->151```152153The same applies to managed-package constraints: record the package name, the154**version tested**, and *how* the constraint was established, so a future reader155can re-test it instead of assuming it still holds.156157---158159## Recommended Workflow1601611. Apply the candidacy test. If it fits in a PR description, or you cannot name162 two viable alternatives, stop — this is not an ADR.1632. Check `standards/decision-trees/` before writing. If a tree routes this,164 record the branch and the inputs rather than re-deriving the reasoning. If165 you are deviating from the tree, say so explicitly and name what would end166 the exception.1673. Draft from `templates/adr-template.md` (Status = Proposed only if a real168 review forum exists; otherwise write it Accepted and retrospective), and169 source every platform claim as you go — Salesforce URL, or a named person170 and date. Mark anything unverifiable inline. Record package name, version171 tested, and method for package-attributed constraints.1724. Force the negatives. Ask what the team writing the superseding ADR will173 complain about, and write that down. If nothing comes to mind, this was not174 a tradeoff.1755. Add a **Review Trigger** with a named owner wherever the decision rests on a176 current platform limitation or on a pending vendor decision. A calendar date177 is not a trigger — a condition is.1786. Mark Accepted with the date and named deciders, update `docs/adr/INDEX.md`179 including the **open review triggers** table, and cite the ADR number in180 subsequent PR descriptions.1817. On supersession: write a new ADR, flip the old one's Status line and nothing182 else, link both ways, and state whether a premise **expired** or a mistake183 was **found** — they teach different lessons.184185---186187## Review Checklist188189- [ ] Passes the candidacy test; two genuinely viable alternatives exist190- [ ] Decision trees checked; branch cited, or "no tree covers this" stated191- [ ] Deviation from a tree, if any, is explicit with an end condition192- [ ] Context records the **inputs** (volumes, limits, requirements), not just narrative193- [ ] Every platform lifecycle claim has a Salesforce URL or a named confirmer + date194- [ ] Unverifiable claims marked inline, not asserted195- [ ] Managed-package constraints carry package name, version tested, and method196- [ ] At least one specific, checkable negative consequence197- [ ] Review Trigger present where the decision rests on a current limitation, with an owner198- [ ] Deciders are named people with roles held at the time199- [ ] Date is the decision date and has never been updated200- [ ] Global four-digit numbering, one directory, in the repo the decision governs201- [ ] `INDEX.md` updated, including the open-triggers table202- [ ] Supersession links resolve both ways; the superseded body is untouched203- [ ] Fits on roughly one page; the design doc is linked, not inlined204205---206207## Worked Examples (see `references/examples.md`)208209- *A decision the tree already answers* — record the branch, not the reasoning210- *A sharing model decision* — where the ordering **is** the decision211- *A platform lifecycle decision* — deciding to wait, with named triggers212- *Supersession done properly* — a premise expiring, not a mistake213- *A decision that should not have been an ADR* — and where it belongs instead214- *The index* — including the open-review-triggers table215216## Common Gotchas (see `references/gotchas.md`)217218- An ADR that re-derives a decision tree is a fork waiting to diverge219- Three releases a year expire ADR premises faster than most platforms220- "Decide to wait" is a decision, and the one nobody writes down221- A named managed-package constraint is a fact with a version number222- Org strategy ADRs need the licensing consequence, not just the topology223- Never edit the body of a superseded ADR224- Proposed ADRs rot silently225226## Top LLM Anti-Patterns (full list in `references/llm-anti-patterns.md`)227228- Re-deriving a decision tree inside the ADR229- Alternatives Considered populated with strawmen230- Consequences that are all positive231- Editing the superseded ADR instead of superseding it232- An ADR for every decision233- An ADR as a design specification234- Stating platform lifecycle facts without sourcing or dating them235- "Decide to wait" left unwritten, or written without triggers236237---238239## Related240241- **architect/solution-design-patterns** — for making the decision. This skill242 is for recording it.243- **architect/well-architected-review** — a review that produces findings, which244 is a different artifact with a different lifecycle.245- **standards/decision-trees/README.md** — the layer above ADRs. Read the246 relevant tree before writing an ADR about a technology choice.247248## Official Sources Used249250See `references/well-architected.md` for the full source list, including an251explicit caveat on the CPQ lifecycle claims used in the worked examples.
Run npx get-skill add pranavnagrecha/architecture-decision-records in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.
Author and maintain Architecture Decision Records (ADRs) for Salesforce implementations: capture chosen approach, rejected alternatives, constraints, and consequences. Trigger keywords: adr, architecture decision record, design decision log, technical decision. NOT for making the design decision itself, e.g. Flow vs Apex — use architect/solution-design-patterns. NOT for a formal architecture review that produces findings — use architect/well-architected-review. It is listed under Coding & Dev Tools on SkillMD.
This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: PASS, Skill Scanner: PASS. Capability flags: executes scripts. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.
This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.
Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.
PranavNagrecha (@pranavnagrecha) published this skill. Their other Agent Skills are listed on their SkillMD profile.