XS✔ ◾ Merge debt - improve rules

rules/merge-debt/rule.md

@@ -22,7 +22,7 @@ archivedreason: null
 guid: aa0d5e6d-f08a-43cd-9bee-4f72df367b78
 ---
 
-When a PR is created but left open for a long time, it becomes stale. Stale PRs equate to merge debt because the longer the PR stays open, the more changes occur on the main branch and the harder it is to merge back in (Merge Debt).
+When a pull request is left open for a long time, it becomes stale and accumulates merge debt. The longer it remains open, the more changes occur on the main branch, increasing the work needed to update and merge the PR. This can lead to conflicts, bugs, and unhappy developers.
 
 <!--endintro-->
 
@@ -39,18 +39,9 @@ If you are **not** part of the team (i.e. an outside contributor), reviewing the
 **Note:** Remember that before declaring a task 'Done' with a link, your [changes should be live](/include-links-in-emails/#ensure-your-changes-are-live) for verification.
 :::
 
-Merge debt refers to the amount of work a PR has to undergo before it can be merged into the main branch. If the PR is brand new, the amount of work required to merge is near to none, but as the PR stays open, the more work gets done on the main branch, leading to more work needing to be done to ensure the PR is up-to-date and able to be merged.
-
 Merge debt can be avoided by:
 
 * Ensuring PRs don't stay open for too long - you could use [SSW Dory](https://www.sswdory.com) to automatically inform you of any outstanding PRs
 * Conducting daily reviews on repos to ensure all PRs that can be merged are merged
-* Ensuring that once a PR is ready to be merged, an "over-the-shoulder" review occurs
-
-::: bad
-![Figure: Bad example - Pressing commit and forgetting about it. PR has been left open for a over 2 weeks](https://github.com/SSWConsulting/SSW.Website-v3/assets/25432120/5a67d6ed-a301-4d72-af00-8da4277c1b75)
-:::
-
-::: good
-![Figure: Good example - Devs reviewing a PR on a call - no merge debt!](over-the-shoulder-pr.png)
-:::
+* Ensuring that once a PR is ready to be merged, an [over-the-shoulder](/over-the-shoulder) review occurs
+* Following the Single Responsibility Principle (SRP) - if a PR covers multiple tasks, it is harder to review and can create more problems

rules/over-the-shoulder/rule.md

@@ -20,7 +20,7 @@ created: 2023-05-15T21:36:54.519Z
 guid: f20af960-7a60-499c-980b-bd5bb6a0af91
 ---
 
-The PR author is responsible to follow up and get PRs merged as soon as possible. An "over-the-shoulder" review is one of the best ways to [avoid merge debt](/merge-debt).
+The PR author is responsible to [follow up](/tofu) and get PRs merged as soon as possible. An "over-the-shoulder" review is one of the best ways to [avoid merge debt](/merge-debt).
 
 When a pull request (PR) is ready to be reviewed, get someone with you either in-person or on call, and go through the PR together. This not only allows you to demo the content of the PR but also talk with the person taking feedback when needed.
 
@@ -34,3 +34,11 @@ When a pull request (PR) is ready to be reviewed, get someone with you either in
 ## Drafting PRs
 
 A good way to avoid someone merging your PR before you have done an over the shoulder review is to keep the Pull Request in draft mode until you are ready for it to be reviewed for merging.
+
+::: bad
+![Figure: Bad example - Pressing commit and forgetting about it. PR has been left open for a over 2 weeks](over-the-shoulder-old-PR.png)
+:::
+
+::: good
+![Figure: Good example - Devs reviewing a PR on a call - no merge debt!](over-the-shoulder-pr.png)
+:::