A historical artifact preserves why a change happened, which decisions shaped it, and what alternatives were rejected. In collaborative development, it gives the wider team an official record instead of leaving rationale with the people who made the change. section 12.2.1 section 11.3
Create a lightweight record that captures:
- Why the change was needed and what context or incident triggered it. section 12.2.1
- Which decisions produced the chosen solution and how the team reached agreement. section 12.2.1
- Which alternative or gut-feeling solutions were rejected, and why. section 12.2.1
Capture-and-chronicle PR
A team mobbing on a production fix can record the key observations and decisions during the session, then use a lighter code review to document them in the PR. The record might explain that an esoteric edge case caused a major incident, or that a workaround remains necessary because an internal package is pinned to an older version. section 12.2.1
Table 12.1 Lightweight chronicle PR checklist
|
Checklist Item
|
Information to chronicle
|
Examples
|
|---|---|---|
|
Why/context
|
• Why are we making this change? What’s the context behind this change?
• What decisions led to this solution?
• How did we come to an agreement on this solution?
|
“This change addresses a really esoteric edge case we didn’t catch but recently caused a major production issue (#323).”
“We have to use this (rather than the FetchUser function available in version 9.3) because our internal packaging system is pinned to version 8.9.6. Until this has been updated company-wide, we have to continue using this workaround method.”
|
|
Skipped solutions
|
• What alternative solutions were discussed, and why were they skipped?
• What “gut-feeling” solutions turned out to be wrong?
|
“We considered Next.js, but they don’t seem to support relative paths for the exported content. They still have an open ticket on GitHub requesting this support, but they are ignoring it.”
“Lambda Functions incur an additional charge when writing to S3, so we skipped.”
|
|
Considerations (brought up during mobbing)
|
• Will these changes impact other teams?
• Other parts of the code base?
• Does this need to be deployed in a certain way?
|
“This needs to be feature-flagged until the corresponding ‘Seller’ component is ready.”
“With this refactor, we can remove the AccountUtilities library entirely. Let’s place that work in a separate PR, though!”
|
Use the lightweight chronicle PR checklist as a practical template for recording context, decisions, and rejected solutions. section 12.2.1
