From 0f08e7b308c81d340153cb5df69ca6e0949ddd25 Mon Sep 17 00:00:00 2001
From: Ian McGinnis <67600557+ian-noaa@users.noreply.github.com>
Date: Tue, 8 Oct 2024 15:03:34 -0600
Subject: [PATCH 01/15] Initial proposal to adopt ADRs & SDRs

---
 docs/decisions/README.md                      |  6 ++++++
 .../adr-0001-record-architecture-decisions.md | 21 +++++++++++++++++++
 .../sdr-0001-record-scientific-decisions.md   | 21 +++++++++++++++++++
 3 files changed, 48 insertions(+)
 create mode 100644 docs/decisions/README.md
 create mode 100644 docs/decisions/architecture/adr-0001-record-architecture-decisions.md
 create mode 100644 docs/decisions/scientific/sdr-0001-record-scientific-decisions.md

diff --git a/docs/decisions/README.md b/docs/decisions/README.md
new file mode 100644
index 0000000..ce7623b
--- /dev/null
+++ b/docs/decisions/README.md
@@ -0,0 +1,6 @@
+# Decisions
+
+This part of our documentation records decisions we have made for the VxIngest project. We've chosen to:
+
+* use the Architecture/Any Decision Record format for this purpose
+* make a distinction between "architecture" (software & infrastructure-related) and "scientific" (decisions on how to calculate & handle data) records
diff --git a/docs/decisions/architecture/adr-0001-record-architecture-decisions.md b/docs/decisions/architecture/adr-0001-record-architecture-decisions.md
new file mode 100644
index 0000000..b13a3df
--- /dev/null
+++ b/docs/decisions/architecture/adr-0001-record-architecture-decisions.md
@@ -0,0 +1,21 @@
+# 1. Record architecture decisions
+
+Date: 2024-10-08
+
+## Status
+
+Proposed
+
+## Context
+
+We need to record the architectural decisions made on this project.
+
+## Decision
+
+To record significant architecture decisions in this project, we will use Architecture/Any
+Decision Records as [described by Michael Nygard in this
+article](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions).
+
+## Consequences
+
+See Michael Nygard's article, linked above.
diff --git a/docs/decisions/scientific/sdr-0001-record-scientific-decisions.md b/docs/decisions/scientific/sdr-0001-record-scientific-decisions.md
new file mode 100644
index 0000000..fe5abca
--- /dev/null
+++ b/docs/decisions/scientific/sdr-0001-record-scientific-decisions.md
@@ -0,0 +1,21 @@
+# 1. Record scientific decisions
+
+Date: 2024-10-08
+
+## Status
+
+Proposed
+
+## Context
+
+We need to record the scientific decisions made on this project.
+
+## Decision
+
+To record significant scientific decisions in this project, we will use Architecture/Any
+Decision Records as [described by Michael Nygard in this
+article](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions).
+
+## Consequences
+
+See Michael Nygard's article, linked above.

From c0ed84db9509d6ae90cead9a354abf8304aace3f Mon Sep 17 00:00:00 2001
From: Ian McGinnis <67600557+ian-noaa@users.noreply.github.com>
Date: Tue, 8 Oct 2024 15:10:38 -0600
Subject: [PATCH 02/15] Expand the decisions README

---
 docs/decisions/README.md | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/docs/decisions/README.md b/docs/decisions/README.md
index ce7623b..24fd7bf 100644
--- a/docs/decisions/README.md
+++ b/docs/decisions/README.md
@@ -2,5 +2,9 @@
 
 This part of our documentation records decisions we have made for the VxIngest project. We've chosen to:
 
-* use the Architecture/Any Decision Record format for this purpose
-* make a distinction between "architecture" (software & infrastructure-related) and "scientific" (decisions on how to calculate & handle data) records
+- Use the Architecture/Any Decision Record format for this purpose
+- Make a distinction between "architecture" and "scientific" decision records
+  - Architecture decisions are decisions focused on software & infrastructure patterns & use.
+  - Scientific decisions are decisions focused on how to calculate & handle data
+
+This is largely inspired by the work done in the beta.weather.gov rewrite. You can [see their usage of ADRs in their GitHub repo here](https://github.com/weather-gov/weather.gov/tree/main/docs/architecture/decisions)

From c746191ba1957bf0a261c83d1823f7c9c4a9e24c Mon Sep 17 00:00:00 2001
From: Ian McGinnis <67600557+ian-noaa@users.noreply.github.com>
Date: Tue, 8 Oct 2024 15:12:39 -0600
Subject: [PATCH 03/15] Don't run CI for the docs directory

---
 .github/workflows/ci.yml | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 6228280..4454508 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -3,6 +3,7 @@ on:
   push:
     paths-ignore:
       - "meta_update_middleware/**"
+      - "docs/**"
     tags:
       - "[0-9]+.[0-9]+.[0-9]+"
       - "[0-9]+.[0-9]+.[0-9]+-rc[0-9]+"
@@ -10,6 +11,7 @@ on:
   pull_request:
     paths-ignore:
       - "meta_update_middleware/**"
+      - "docs/**"
   workflow_dispatch: # Manually
 env:
   REGISTRY: ghcr.io/noaa-gsl/vxingest

From 1176489dc33138a7ce6f001529260a1ee0c5c2c9 Mon Sep 17 00:00:00 2001
From: "randy.pierce" <randy.pierce@noaa.gov>
Date: Wed, 9 Oct 2024 10:20:51 -0600
Subject: [PATCH 04/15] new sdr

---
 ...-will-recalculate-all-heights-for-RAOBS.md | 21 +++++++++++++++++++
 1 file changed, 21 insertions(+)
 create mode 100644 docs/decisions/scientific/1.0-PrepBufr-we-will-recalculate-all-heights-for-RAOBS.md

diff --git a/docs/decisions/scientific/1.0-PrepBufr-we-will-recalculate-all-heights-for-RAOBS.md b/docs/decisions/scientific/1.0-PrepBufr-we-will-recalculate-all-heights-for-RAOBS.md
new file mode 100644
index 0000000..1949c09
--- /dev/null
+++ b/docs/decisions/scientific/1.0-PrepBufr-we-will-recalculate-all-heights-for-RAOBS.md
@@ -0,0 +1,21 @@
+# 1. PrepBufr - we will recalculate all heights for RAOBS
+
+Date: 2024-10-01
+
+## Status
+
+Accepted
+
+## Context
+
+This decision was actually made a couple of years ago but recording it now. Because height data from radiosondes was unrelieable a decision was made with the advice of senior meteorologists to always recalculate all height values. Currently all height values are calculated from the lowest reported height using the hypsometric equation and the reported temperature, pressure, and mixing ratio (derived from the specific humidity).
+
+Once the heights are calculated, all variables, including heights, are interpolated to mandatory pressure levels using logarithmic interpolation.
+
+## Decision
+
+We have chosen to always recalculate heights using hypsometric equation, and interpolate heights and variables to mandatory leves based on the calculated heights.
+
+## Consequences
+
+It is important to understand this interpolation technique when comparing our RAOB data to the data in the PrepBufr files. They do not compare one to one.
\ No newline at end of file

From edd9f1d5a587131fc13a44efd8372247ae60c060 Mon Sep 17 00:00:00 2001
From: randytpierce <randy.pierce@noaa.gov>
Date: Wed, 9 Oct 2024 10:48:41 -0600
Subject: [PATCH 05/15] Update
 1.0-PrepBufr-we-will-recalculate-all-heights-for-RAOBS.md

---
 .../1.0-PrepBufr-we-will-recalculate-all-heights-for-RAOBS.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/decisions/scientific/1.0-PrepBufr-we-will-recalculate-all-heights-for-RAOBS.md b/docs/decisions/scientific/1.0-PrepBufr-we-will-recalculate-all-heights-for-RAOBS.md
index 1949c09..1cfbb15 100644
--- a/docs/decisions/scientific/1.0-PrepBufr-we-will-recalculate-all-heights-for-RAOBS.md
+++ b/docs/decisions/scientific/1.0-PrepBufr-we-will-recalculate-all-heights-for-RAOBS.md
@@ -1,4 +1,4 @@
-# 1. PrepBufr - we will recalculate all heights for RAOBS
+# 1.0 PrepBufr - we will recalculate all heights for RAOBS
 
 Date: 2024-10-01
 
@@ -18,4 +18,4 @@ We have chosen to always recalculate heights using hypsometric equation, and int
 
 ## Consequences
 
-It is important to understand this interpolation technique when comparing our RAOB data to the data in the PrepBufr files. They do not compare one to one.
\ No newline at end of file
+It is important to understand this interpolation technique when comparing our RAOB data to the data in the PrepBufr files. They do not compare one to one.

From 927f89d16479981ff0ffdaeebe2adab40612830e Mon Sep 17 00:00:00 2001
From: Ian McGinnis <67600557+ian-noaa@users.noreply.github.com>
Date: Wed, 9 Oct 2024 13:31:00 -0600
Subject: [PATCH 06/15] Add issue templates & automation for ADRs/SDRs

---
 .github/ISSUE_TEMPLATE/adr-template.yaml | 33 ++++++++++
 .github/ISSUE_TEMPLATE/sdr-template.yaml | 33 ++++++++++
 .github/workflows/adr-accepted.yaml      | 83 ++++++++++++++++++++++++
 .github/workflows/adr-proposed.yaml      | 35 ++++++++++
 .github/workflows/sdr-accepted.yaml      | 83 ++++++++++++++++++++++++
 .github/workflows/sdr-proposed.yaml      | 35 ++++++++++
 6 files changed, 302 insertions(+)
 create mode 100644 .github/ISSUE_TEMPLATE/adr-template.yaml
 create mode 100644 .github/ISSUE_TEMPLATE/sdr-template.yaml
 create mode 100644 .github/workflows/adr-accepted.yaml
 create mode 100644 .github/workflows/adr-proposed.yaml
 create mode 100644 .github/workflows/sdr-accepted.yaml
 create mode 100644 .github/workflows/sdr-proposed.yaml

diff --git a/.github/ISSUE_TEMPLATE/adr-template.yaml b/.github/ISSUE_TEMPLATE/adr-template.yaml
new file mode 100644
index 0000000..029efb7
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/adr-template.yaml
@@ -0,0 +1,33 @@
+name: Architecture decision record (ADR)
+description: Open a new draft ADR
+labels: ["ADR"]
+body:
+  - type: textarea
+    id: context
+    validations:
+      required: true
+    attributes:
+      label: Context
+      description: >
+        Describe the motivating factors behind this decision: social, political,
+        technical, etc. Why does this decision need to be made? This section should
+        be a statement of facts.
+  - type: textarea
+    id: decision
+    validations:
+      required: true
+    attributes:
+      label: Decision
+      description: >
+        What was decided? This should be an active-voice statement. For example,
+        "We will use the US Web Design System."
+  - type: textarea
+    id: consequences
+    validations:
+      required: true
+    attributes:
+      label: Consequences
+      description: >
+        What are the consequences of this decision? Consequences can be
+        positive, negative, or neutral, but all known consequences of this
+        decision should be listed here.
\ No newline at end of file
diff --git a/.github/ISSUE_TEMPLATE/sdr-template.yaml b/.github/ISSUE_TEMPLATE/sdr-template.yaml
new file mode 100644
index 0000000..6c6cfc4
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/sdr-template.yaml
@@ -0,0 +1,33 @@
+name: Scientific decision record (SDR)
+description: Open a new draft SDR
+labels: ["SDR"]
+body:
+  - type: textarea
+    id: context
+    validations:
+      required: true
+    attributes:
+      label: Context
+      description: >
+        Describe the motivating factors behind this decision: social, political,
+        scientific, etc. Why does this decision need to be made? This section should
+        be a statement of facts.
+  - type: textarea
+    id: decision
+    validations:
+      required: true
+    attributes:
+      label: Decision
+      description: >
+        What was decided? This should be an active-voice statement. For example,
+        "We will recalculate heights for RAOB observations."
+  - type: textarea
+    id: consequences
+    validations:
+      required: true
+    attributes:
+      label: Consequences
+      description: >
+        What are the consequences of this decision? Consequences can be
+        positive, negative, or neutral, but all known consequences of this
+        decision should be listed here.
\ No newline at end of file
diff --git a/.github/workflows/adr-accepted.yaml b/.github/workflows/adr-accepted.yaml
new file mode 100644
index 0000000..8c79ecf
--- /dev/null
+++ b/.github/workflows/adr-accepted.yaml
@@ -0,0 +1,83 @@
+name: ADR created
+on:
+  issues:
+    types:
+      - closed
+
+jobs:
+  main:
+    name: ADR created
+    runs-on: ubuntu-latest
+
+    # Only run this workflow if the closed issue has the "ADR: accepted" label
+    if: "${{ contains(github.event.issue.labels.*.name, 'ADR: accepted') }}"
+
+    steps:
+      - name: checkout main branch
+        uses: actions/checkout@v4
+        with:
+          ref: main
+
+      - name: get ADR number
+        id: next
+        run: |
+          LAST_ADR=$(ls docs/decisions/architecture/*.md | grep -Eo "architecture/adr-[0-9]+-" | sort | tail -n1 | grep -Eo "[0-9]+")
+          LAST_ADR=$(echo "$LAST_ADR" | sed -E 's/^0+//')
+          NEXT_ADR=$(($LAST_ADR + 1))
+          NEXT_ADR=$(printf "%04i" "$NEXT_ADR")
+          echo "number=$NEXT_ADR" >> "$GITHUB_OUTPUT"
+
+      - name: write the ADR
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require("fs/promises");
+
+            // Use the GitHub toJSON expression to get these as escaped strings.
+            // In Javascript, this will preserve line breaks, and using template
+            // strings further down will preserve all the kinds of quotes.
+            const title = ${{ toJSON(github.event.issue.title) }};
+            const body = ${{ toJSON(github.event.issue.body )}};
+
+            const slug = title
+              .toLowerCase()
+              .trim()
+              .replace(/[^\w\s-]/g, "") // get rid of non-ascii characters
+              .replace(/[\s_-]+/g, "-") // convert whitespace and underscore to dash
+              .replace(/^-+|-+$/g, "");  // git rid of leading/trailing dashes
+
+            const filename = `docs/architecture/decisions/adr-${{ steps.next.outputs.number }}-${slug}.md`;
+
+            // Get the current date as an ISO8601 string, split at the timestamp,
+            // and only keep the date portion.
+            const [date] = new Date().toISOString().split("T");
+
+            const adr = `# ${ title }
+
+            Date: ${ date }
+
+            ### Status
+
+            Accepted
+
+            ${ body }
+            `;
+
+            await fs.writeFile(filename, adr, { encoding: 'utf-8' });
+
+      - name: branch, commit, and open PR
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          BRANCH="adr-auto-${{ steps.next.outputs.number }}"
+          git config --global user.email "mats.gsl@noaa.gov"
+          git config --global user.name "GSL Verification team ADR automation"
+          git checkout -b $BRANCH
+          git add docs/decisions/architecture/*.md
+          git commit -m "add ADR ${{ steps.next.outputs.number }}: ${{ github.event.issue.title }}"
+          git push -f origin $BRANCH
+          gh pr create \
+            --title "Add ADR ${{ steps.next.outputs.number }} to the repo" \
+            --label "ADR" \
+            --body "This pull request was opened automatically because #${{ github.event.issue.number }} was closed after being marked as an approved ADR. It contains a markdown file capturing the ADR body at the time the issue was closed. Please verify that the markdown is correct before merging!" || true
+          gh pr merge $BRANCH --auto --squash
\ No newline at end of file
diff --git a/.github/workflows/adr-proposed.yaml b/.github/workflows/adr-proposed.yaml
new file mode 100644
index 0000000..1c2a369
--- /dev/null
+++ b/.github/workflows/adr-proposed.yaml
@@ -0,0 +1,35 @@
+name: ADR proposed
+on:
+  issues:
+    types:
+      - labeled
+
+jobs:
+  main:
+    name: ADR created
+    runs-on: ubuntu-latest
+
+    # Only run this workflow if the issue is open and has the "ADR" label
+    if: "${{github.event.issue.state == 'open' && contains(github.event.issue.labels.*.name, 'ADR') }}"
+
+    steps:
+      - name: add comment if appropriate
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const { data: comments } = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number
+            });
+
+            const botHasCommented = comments.some(({ user: { login }}) => login === 'github-actions[bot]');
+
+            if(!botHasCommented) {
+              github.rest.issues.createComment({
+                issue_number: context.issue.number,
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                body: 'This issue appears to be a draft or in-progress ADR. When it is completed and accepted, add the `ADR: Accepted` label and close the issue. This will start a process to create the ADR document and add it to the repo automatically. If you close the issue before adding the label, simply re-open and re-close it.'
+              });
+            }
diff --git a/.github/workflows/sdr-accepted.yaml b/.github/workflows/sdr-accepted.yaml
new file mode 100644
index 0000000..ae07510
--- /dev/null
+++ b/.github/workflows/sdr-accepted.yaml
@@ -0,0 +1,83 @@
+name: SDR created
+on:
+  issues:
+    types:
+      - closed
+
+jobs:
+  main:
+    name: SDR created
+    runs-on: ubuntu-latest
+
+    # Only run this workflow if the closed issue has the "SDR: accepted" label
+    if: "${{ contains(github.event.issue.labels.*.name, 'SDR: accepted') }}"
+
+    steps:
+      - name: checkout main branch
+        uses: actions/checkout@v4
+        with:
+          ref: main
+
+      - name: get SDR number
+        id: next
+        run: |
+          LAST_SDR=$(ls docs/decisions/scientific/*.md | grep -Eo "scientific/[0-9]+-" | sort | tail -n1 | grep -Eo "[0-9]+")
+          LAST_SDR=$(echo "$LAST_SDR" | sed -E 's/^0+//')
+          NEXT_SDR=$(($LAST_SDR + 1))
+          NEXT_SDR=$(printf "%04i" "$NEXT_SDR")
+          echo "number=$NEXT_SDR" >> "$GITHUB_OUTPUT"
+
+      - name: write the SDR
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require("fs/promises");
+
+            // Use the GitHub toJSON expression to get these as escaped strings.
+            // In Javascript, this will preserve line breaks, and using template
+            // strings further down will preserve all the kinds of quotes.
+            const title = ${{ toJSON(github.event.issue.title) }};
+            const body = ${{ toJSON(github.event.issue.body )}};
+
+            const slug = title
+              .toLowerCase()
+              .trim()
+              .replace(/[^\w\s-]/g, "") // get rid of non-ascii characters
+              .replace(/[\s_-]+/g, "-") // convert whitespace and underscore to dash
+              .replace(/^-+|-+$/g, "");  // git rid of leading/trailing dashes
+
+            const filename = `docs/architecture/decisions/sdr-${{ steps.next.outputs.number }}-${slug}.md`;
+
+            // Get the current date as an ISO8601 string, split at the timestamp,
+            // and only keep the date portion.
+            const [date] = new Date().toISOString().split("T");
+
+            const sdr = `# ${ title }
+
+            Date: ${ date }
+
+            ### Status
+
+            Accepted
+
+            ${ body }
+            `;
+
+            await fs.writeFile(filename, sdr, { encoding: 'utf-8' });
+
+      - name: branch, commit, and open PR
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          BRANCH="sdr-auto-${{ steps.next.outputs.number }}"
+          git config --global user.email "mats.gsl@noaa.gov"
+          git config --global user.name "GSL Verification team SDR automation"
+          git checkout -b $BRANCH
+          git add docs/decisions/scientific/*.md
+          git commit -m "add SDR ${{ steps.next.outputs.number }}: ${{ github.event.issue.title }}"
+          git push -f origin $BRANCH
+          gh pr create \
+            --title "Add SDR ${{ steps.next.outputs.number }} to the repo" \
+            --label "SDR" \
+            --body "This pull request was opened automatically because #${{ github.event.issue.number }} was closed after being marked as an approved SDR. It contains a markdown file capturing the SDR body at the time the issue was closed. Please verify that the markdown is correct before merging!" || true
+          gh pr merge $BRANCH --auto --squash
\ No newline at end of file
diff --git a/.github/workflows/sdr-proposed.yaml b/.github/workflows/sdr-proposed.yaml
new file mode 100644
index 0000000..7ec8da6
--- /dev/null
+++ b/.github/workflows/sdr-proposed.yaml
@@ -0,0 +1,35 @@
+name: SDR proposed
+on:
+  issues:
+    types:
+      - labeled
+
+jobs:
+  main:
+    name: SDR created
+    runs-on: ubuntu-latest
+
+    # Only run this workflow if the issue is open and has the "SDR" label
+    if: "${{github.event.issue.state == 'open' && contains(github.event.issue.labels.*.name, 'SDR') }}"
+
+    steps:
+      - name: add comment if appropriate
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const { data: comments } = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number
+            });
+
+            const botHasCommented = comments.some(({ user: { login }}) => login === 'github-actions[bot]');
+
+            if(!botHasCommented) {
+              github.rest.issues.createComment({
+                issue_number: context.issue.number,
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                body: 'This issue appears to be a draft or in-progress SDR. When it is completed and accepted, add the `SDR: Accepted` label and close the issue. This will start a process to create the SDR document and add it to the repo automatically. If you close the issue before adding the label, simply re-open and re-close it.'
+              });
+            }

From fa416dd5ab104a8a98e81535aa7315716b2c81c6 Mon Sep 17 00:00:00 2001
From: Ian McGinnis <67600557+ian-noaa@users.noreply.github.com>
Date: Wed, 9 Oct 2024 13:45:51 -0600
Subject: [PATCH 07/15] Standardize file naming

---
 ...for-RAOBS.md => sdr-0002-recalculate-all-heights-for-raobs.md} | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename docs/decisions/scientific/{1.0-PrepBufr-we-will-recalculate-all-heights-for-RAOBS.md => sdr-0002-recalculate-all-heights-for-raobs.md} (100%)

diff --git a/docs/decisions/scientific/1.0-PrepBufr-we-will-recalculate-all-heights-for-RAOBS.md b/docs/decisions/scientific/sdr-0002-recalculate-all-heights-for-raobs.md
similarity index 100%
rename from docs/decisions/scientific/1.0-PrepBufr-we-will-recalculate-all-heights-for-RAOBS.md
rename to docs/decisions/scientific/sdr-0002-recalculate-all-heights-for-raobs.md

From 39910d43fc24b89905ef0af39485969d5433176d Mon Sep 17 00:00:00 2001
From: Ian McGinnis <67600557+ian-noaa@users.noreply.github.com>
Date: Wed, 9 Oct 2024 13:46:23 -0600
Subject: [PATCH 08/15] Update SDR/ADR text to match issue templates &
 automation

---
 .../adr-0001-record-architecture-decisions.md    |  2 +-
 .../sdr-0001-record-scientific-decisions.md      |  2 +-
 ...sdr-0002-recalculate-all-heights-for-raobs.md | 16 +++++++++++-----
 3 files changed, 13 insertions(+), 7 deletions(-)

diff --git a/docs/decisions/architecture/adr-0001-record-architecture-decisions.md b/docs/decisions/architecture/adr-0001-record-architecture-decisions.md
index b13a3df..34c50b2 100644
--- a/docs/decisions/architecture/adr-0001-record-architecture-decisions.md
+++ b/docs/decisions/architecture/adr-0001-record-architecture-decisions.md
@@ -1,4 +1,4 @@
-# 1. Record architecture decisions
+# Record architecture decisions
 
 Date: 2024-10-08
 
diff --git a/docs/decisions/scientific/sdr-0001-record-scientific-decisions.md b/docs/decisions/scientific/sdr-0001-record-scientific-decisions.md
index fe5abca..1b24a19 100644
--- a/docs/decisions/scientific/sdr-0001-record-scientific-decisions.md
+++ b/docs/decisions/scientific/sdr-0001-record-scientific-decisions.md
@@ -1,4 +1,4 @@
-# 1. Record scientific decisions
+# Record scientific decisions
 
 Date: 2024-10-08
 
diff --git a/docs/decisions/scientific/sdr-0002-recalculate-all-heights-for-raobs.md b/docs/decisions/scientific/sdr-0002-recalculate-all-heights-for-raobs.md
index 1cfbb15..f3b92ca 100644
--- a/docs/decisions/scientific/sdr-0002-recalculate-all-heights-for-raobs.md
+++ b/docs/decisions/scientific/sdr-0002-recalculate-all-heights-for-raobs.md
@@ -1,6 +1,6 @@
-# 1.0 PrepBufr - we will recalculate all heights for RAOBS
+# Recalculate all heights for RAOBS
 
-Date: 2024-10-01
+Date: 2024-10-09
 
 ## Status
 
@@ -8,14 +8,20 @@ Accepted
 
 ## Context
 
-This decision was actually made a couple of years ago but recording it now. Because height data from radiosondes was unrelieable a decision was made with the advice of senior meteorologists to always recalculate all height values. Currently all height values are calculated from the lowest reported height using the hypsometric equation and the reported temperature, pressure, and mixing ratio (derived from the specific humidity).
+This decision was actually made a couple of years ago but we are recording it now. Because height data from radiosondes was unreliable a decision was made with the advice of senior meteorologists to always recalculate all height values. Currently all height values are calculated from the lowest reported height using the hypsometric equation and the reported temperature, pressure, and mixing ratio (derived from the specific humidity).
 
 Once the heights are calculated, all variables, including heights, are interpolated to mandatory pressure levels using logarithmic interpolation.
 
 ## Decision
 
-We have chosen to always recalculate heights using hypsometric equation, and interpolate heights and variables to mandatory leves based on the calculated heights.
+We will always recalculate heights using the [hypsometric equation](https://unidata.github.io/MetPy/latest/api/generated/metpy.calc.thickness_hydrostatic.html), and interpolate heights and variables to mandatory levels based on the calculated heights.
 
 ## Consequences
 
-It is important to understand this interpolation technique when comparing our RAOB data to the data in the PrepBufr files. They do not compare one to one.
+### Positive
+
+### Neutral
+
+- It is important to understand this interpolation technique when comparing our RAOB data to the data in the PrepBufr files. They do not compare one to one.
+
+### Negative

From cc476482c8d87796becab2e2c4a3143d2dfa3ec6 Mon Sep 17 00:00:00 2001
From: Ian McGinnis <67600557+ian-noaa@users.noreply.github.com>
Date: Wed, 9 Oct 2024 14:27:30 -0600
Subject: [PATCH 09/15] Fix some formatting issues

---
 .github/workflows/adr-accepted.yaml | 2 +-
 .github/workflows/sdr-accepted.yaml | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/adr-accepted.yaml b/.github/workflows/adr-accepted.yaml
index 8c79ecf..69a2a7b 100644
--- a/.github/workflows/adr-accepted.yaml
+++ b/.github/workflows/adr-accepted.yaml
@@ -80,4 +80,4 @@ jobs:
             --title "Add ADR ${{ steps.next.outputs.number }} to the repo" \
             --label "ADR" \
             --body "This pull request was opened automatically because #${{ github.event.issue.number }} was closed after being marked as an approved ADR. It contains a markdown file capturing the ADR body at the time the issue was closed. Please verify that the markdown is correct before merging!" || true
-          gh pr merge $BRANCH --auto --squash
\ No newline at end of file
+          gh pr merge $BRANCH --auto --squash
diff --git a/.github/workflows/sdr-accepted.yaml b/.github/workflows/sdr-accepted.yaml
index ae07510..8a61c9e 100644
--- a/.github/workflows/sdr-accepted.yaml
+++ b/.github/workflows/sdr-accepted.yaml
@@ -80,4 +80,4 @@ jobs:
             --title "Add SDR ${{ steps.next.outputs.number }} to the repo" \
             --label "SDR" \
             --body "This pull request was opened automatically because #${{ github.event.issue.number }} was closed after being marked as an approved SDR. It contains a markdown file capturing the SDR body at the time the issue was closed. Please verify that the markdown is correct before merging!" || true
-          gh pr merge $BRANCH --auto --squash
\ No newline at end of file
+          gh pr merge $BRANCH --auto --squash

From de01293d5452da5cd957d8694563d39ae8b37146 Mon Sep 17 00:00:00 2001
From: Ian McGinnis <67600557+ian-noaa@users.noreply.github.com>
Date: Wed, 9 Oct 2024 14:29:42 -0600
Subject: [PATCH 10/15] More formatting fixes

---
 .github/ISSUE_TEMPLATE/adr-template.yaml | 2 +-
 .github/ISSUE_TEMPLATE/sdr-template.yaml | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/.github/ISSUE_TEMPLATE/adr-template.yaml b/.github/ISSUE_TEMPLATE/adr-template.yaml
index 029efb7..e842243 100644
--- a/.github/ISSUE_TEMPLATE/adr-template.yaml
+++ b/.github/ISSUE_TEMPLATE/adr-template.yaml
@@ -30,4 +30,4 @@ body:
       description: >
         What are the consequences of this decision? Consequences can be
         positive, negative, or neutral, but all known consequences of this
-        decision should be listed here.
\ No newline at end of file
+        decision should be listed here.
diff --git a/.github/ISSUE_TEMPLATE/sdr-template.yaml b/.github/ISSUE_TEMPLATE/sdr-template.yaml
index 6c6cfc4..98f7ff5 100644
--- a/.github/ISSUE_TEMPLATE/sdr-template.yaml
+++ b/.github/ISSUE_TEMPLATE/sdr-template.yaml
@@ -30,4 +30,4 @@ body:
       description: >
         What are the consequences of this decision? Consequences can be
         positive, negative, or neutral, but all known consequences of this
-        decision should be listed here.
\ No newline at end of file
+        decision should be listed here.

From 9ad61b733ff7de77c0beac2f1ab1aef0e2ba308f Mon Sep 17 00:00:00 2001
From: Ian McGinnis <67600557+ian-noaa@users.noreply.github.com>
Date: Thu, 10 Oct 2024 22:22:41 -0600
Subject: [PATCH 11/15] Update ADR templates & automation

Add error handling to the automation. If an ADR/SDR PR already existed
and was still open, it would be silently overwritten by the next ADR/SDR
---
 .github/ISSUE_TEMPLATE/adr-template.yaml | 15 ++++++-
 .github/ISSUE_TEMPLATE/sdr-template.yaml | 15 ++++++-
 .github/workflows/adr-accepted.yaml      | 51 ++++++++++++++++------
 .github/workflows/adr-proposed.yaml      |  2 +-
 .github/workflows/sdr-accepted.yaml      | 54 ++++++++++++++++++------
 .github/workflows/sdr-proposed.yaml      |  2 +-
 6 files changed, 110 insertions(+), 29 deletions(-)

diff --git a/.github/ISSUE_TEMPLATE/adr-template.yaml b/.github/ISSUE_TEMPLATE/adr-template.yaml
index e842243..9ea4207 100644
--- a/.github/ISSUE_TEMPLATE/adr-template.yaml
+++ b/.github/ISSUE_TEMPLATE/adr-template.yaml
@@ -1,6 +1,7 @@
 name: Architecture decision record (ADR)
 description: Open a new draft ADR
 labels: ["ADR"]
+title: "We will "
 body:
   - type: textarea
     id: context
@@ -8,7 +9,7 @@ body:
       required: true
     attributes:
       label: Context
-      description: >
+      description: >  # Turn new lines into spaces
         Describe the motivating factors behind this decision: social, political,
         technical, etc. Why does this decision need to be made? This section should
         be a statement of facts.
@@ -31,3 +32,15 @@ body:
         What are the consequences of this decision? Consequences can be
         positive, negative, or neutral, but all known consequences of this
         decision should be listed here.
+      value: | # Preserve new lines
+        #### Positive
+
+        - 
+
+        #### Neutral
+
+        - 
+
+        #### Negative
+
+        -
diff --git a/.github/ISSUE_TEMPLATE/sdr-template.yaml b/.github/ISSUE_TEMPLATE/sdr-template.yaml
index 98f7ff5..8fc4a4b 100644
--- a/.github/ISSUE_TEMPLATE/sdr-template.yaml
+++ b/.github/ISSUE_TEMPLATE/sdr-template.yaml
@@ -1,6 +1,7 @@
 name: Scientific decision record (SDR)
 description: Open a new draft SDR
 labels: ["SDR"]
+title: "We will "
 body:
   - type: textarea
     id: context
@@ -8,7 +9,7 @@ body:
       required: true
     attributes:
       label: Context
-      description: >
+      description: > # Turn new lines into spaces
         Describe the motivating factors behind this decision: social, political,
         scientific, etc. Why does this decision need to be made? This section should
         be a statement of facts.
@@ -31,3 +32,15 @@ body:
         What are the consequences of this decision? Consequences can be
         positive, negative, or neutral, but all known consequences of this
         decision should be listed here.
+      value: | # Preserve new lines
+        #### Positive
+
+        - 
+
+        #### Neutral
+
+        - 
+
+        #### Negative
+
+        -
diff --git a/.github/workflows/adr-accepted.yaml b/.github/workflows/adr-accepted.yaml
index 69a2a7b..f4f8e51 100644
--- a/.github/workflows/adr-accepted.yaml
+++ b/.github/workflows/adr-accepted.yaml
@@ -1,4 +1,4 @@
-name: ADR created
+name: ADR Accepted
 on:
   issues:
     types:
@@ -6,7 +6,7 @@ on:
 
 jobs:
   main:
-    name: ADR created
+    name: Create ADR
     runs-on: ubuntu-latest
 
     # Only run this workflow if the closed issue has the "ADR: accepted" label
@@ -28,6 +28,7 @@ jobs:
           echo "number=$NEXT_ADR" >> "$GITHUB_OUTPUT"
 
       - name: write the ADR
+        id: create-adr
         uses: actions/github-script@v7
         with:
           script: |
@@ -46,7 +47,7 @@ jobs:
               .replace(/[\s_-]+/g, "-") // convert whitespace and underscore to dash
               .replace(/^-+|-+$/g, "");  // git rid of leading/trailing dashes
 
-            const filename = `docs/architecture/decisions/adr-${{ steps.next.outputs.number }}-${slug}.md`;
+            const filename = `docs/decisions/architecture/adr-${{ steps.next.outputs.number }}-${slug}.md`;
 
             // Get the current date as an ISO8601 string, split at the timestamp,
             // and only keep the date portion.
@@ -63,6 +64,10 @@ jobs:
             ${ body }
             `;
 
+            # Set outputs for the next step to use
+            core.setOutput('filename', filename);
+            core.setOutput('adr', adr);
+
             await fs.writeFile(filename, adr, { encoding: 'utf-8' });
 
       - name: branch, commit, and open PR
@@ -72,12 +77,34 @@ jobs:
           BRANCH="adr-auto-${{ steps.next.outputs.number }}"
           git config --global user.email "mats.gsl@noaa.gov"
           git config --global user.name "GSL Verification team ADR automation"
-          git checkout -b $BRANCH
-          git add docs/decisions/architecture/*.md
-          git commit -m "add ADR ${{ steps.next.outputs.number }}: ${{ github.event.issue.title }}"
-          git push -f origin $BRANCH
-          gh pr create \
-            --title "Add ADR ${{ steps.next.outputs.number }} to the repo" \
-            --label "ADR" \
-            --body "This pull request was opened automatically because #${{ github.event.issue.number }} was closed after being marked as an approved ADR. It contains a markdown file capturing the ADR body at the time the issue was closed. Please verify that the markdown is correct before merging!" || true
-          gh pr merge $BRANCH --auto --squash
+          # Check if the branch already exists, exit-code 2 means it doesn't, and that creating a new branch is safe.
+          set +e # override set -e since we're hoping for an exit code
+          git ls-remote --exit-code --heads origin refs/heads/$BRANCH > /dev/null
+          branch_exists=$?
+          set -e
+          if [ $branch_exists -eq 2 ]; then
+            git checkout -b $BRANCH
+            git add docs/decisions/architecture/*.md
+            git commit -m "add ADR ${{ steps.next.outputs.number }}: ${{ github.event.issue.title }}"
+            git push -f origin $BRANCH
+            gh pr create \
+                --title "Add ADR ${{ steps.next.outputs.number }} to the repo" \
+                --label "ADR" \
+                --body "This pull request was opened automatically because #${{ github.event.issue.number }} was closed after being marked as an approved ADR. It contains a markdown file capturing the ADR body at the time the issue was closed. Please verify that the markdown is correct before merging!" || true
+          else
+            echo "Error - Branch $BRANCH already exists, PR will need to be created manually. ADR text is below. Exiting."
+            echo " --- "
+            echo "Filename: ${{ steps.create-adr.outputs.filename }}"
+            echo " --- Start File --- "
+            echo "${{ steps.create-adr.outputs.adr }}"
+            echo " --- End File --- "
+
+            # Create a step summary
+            echo "# Error" >> $GITHUB_STEP_SUMMARY
+            echo "Branch $BRANCH already exists, PR will need to be created manually. ADR contents are below. Exiting." >> $GITHUB_STEP_SUMMARY
+            echo "## Filename" >> $GITHUB_STEP_SUMMARY
+            echo "\`${{ steps.create-adr.outputs.filename }}\`" >> $GITHUB_STEP_SUMMARY
+            echo "## ADR Contents" >> $GITHUB_STEP_SUMMARY
+            echo "${{ steps.create-adr.outputs.adr }}" >> $GITHUB_STEP_SUMMARY
+            exit 1
+          fi
diff --git a/.github/workflows/adr-proposed.yaml b/.github/workflows/adr-proposed.yaml
index 1c2a369..022d737 100644
--- a/.github/workflows/adr-proposed.yaml
+++ b/.github/workflows/adr-proposed.yaml
@@ -6,7 +6,7 @@ on:
 
 jobs:
   main:
-    name: ADR created
+    name: ADR proposed
     runs-on: ubuntu-latest
 
     # Only run this workflow if the issue is open and has the "ADR" label
diff --git a/.github/workflows/sdr-accepted.yaml b/.github/workflows/sdr-accepted.yaml
index 8a61c9e..a6c04fb 100644
--- a/.github/workflows/sdr-accepted.yaml
+++ b/.github/workflows/sdr-accepted.yaml
@@ -1,4 +1,4 @@
-name: SDR created
+name: SDR Accepted
 on:
   issues:
     types:
@@ -6,7 +6,7 @@ on:
 
 jobs:
   main:
-    name: SDR created
+    name: Create SDR
     runs-on: ubuntu-latest
 
     # Only run this workflow if the closed issue has the "SDR: accepted" label
@@ -21,13 +21,14 @@ jobs:
       - name: get SDR number
         id: next
         run: |
-          LAST_SDR=$(ls docs/decisions/scientific/*.md | grep -Eo "scientific/[0-9]+-" | sort | tail -n1 | grep -Eo "[0-9]+")
+          LAST_SDR=$(ls docs/decisions/scientific/*.md | grep -Eo "scientific/sdr-[0-9]+-" | sort | tail -n1 | grep -Eo "[0-9]+")
           LAST_SDR=$(echo "$LAST_SDR" | sed -E 's/^0+//')
           NEXT_SDR=$(($LAST_SDR + 1))
           NEXT_SDR=$(printf "%04i" "$NEXT_SDR")
           echo "number=$NEXT_SDR" >> "$GITHUB_OUTPUT"
 
       - name: write the SDR
+        id: create-sdr
         uses: actions/github-script@v7
         with:
           script: |
@@ -46,7 +47,7 @@ jobs:
               .replace(/[\s_-]+/g, "-") // convert whitespace and underscore to dash
               .replace(/^-+|-+$/g, "");  // git rid of leading/trailing dashes
 
-            const filename = `docs/architecture/decisions/sdr-${{ steps.next.outputs.number }}-${slug}.md`;
+            const filename = `docs/decisions/scientific/sdr-${{ steps.next.outputs.number }}-${slug}.md`;
 
             // Get the current date as an ISO8601 string, split at the timestamp,
             // and only keep the date portion.
@@ -63,6 +64,10 @@ jobs:
             ${ body }
             `;
 
+            # Set outputs for the next step to use
+            core.setOutput('filename', filename);
+            core.setOutput('sdr', sdr);
+
             await fs.writeFile(filename, sdr, { encoding: 'utf-8' });
 
       - name: branch, commit, and open PR
@@ -72,12 +77,35 @@ jobs:
           BRANCH="sdr-auto-${{ steps.next.outputs.number }}"
           git config --global user.email "mats.gsl@noaa.gov"
           git config --global user.name "GSL Verification team SDR automation"
-          git checkout -b $BRANCH
-          git add docs/decisions/scientific/*.md
-          git commit -m "add SDR ${{ steps.next.outputs.number }}: ${{ github.event.issue.title }}"
-          git push -f origin $BRANCH
-          gh pr create \
-            --title "Add SDR ${{ steps.next.outputs.number }} to the repo" \
-            --label "SDR" \
-            --body "This pull request was opened automatically because #${{ github.event.issue.number }} was closed after being marked as an approved SDR. It contains a markdown file capturing the SDR body at the time the issue was closed. Please verify that the markdown is correct before merging!" || true
-          gh pr merge $BRANCH --auto --squash
+          # Check if the branch already exists, exit-code 2 means it doesn't, and that creating a new branch is safe.
+          set +e # override set -e since we're hoping for an exit code
+          git ls-remote --exit-code --heads origin refs/heads/$BRANCH > /dev/null
+          branch_exists=$?
+          set -e
+          if [ $branch_exists -eq 2 ]; then
+            git checkout -b $BRANCH
+            git add docs/decisions/scientific/*.md
+            git commit -m "add SDR ${{ steps.next.outputs.number }}: ${{ github.event.issue.title }}"
+            git push -f origin $BRANCH
+            gh pr create \
+              --title "Add SDR ${{ steps.next.outputs.number }} to the repo" \
+              --label "SDR" \
+              --body "This pull request was opened automatically because #${{ github.event.issue.number }} was closed after being marked as an approved SDR. It contains a markdown file capturing the SDR body at the time the issue was closed. Please verify that the markdown is correct before merging!" || true
+            exit 0
+          else
+            echo "Error - Branch $BRANCH already exists, PR will need to be created manually. SDR text is below. Exiting."
+            echo " --- "
+            echo "Filename: ${{ steps.create-sdr.outputs.filename }}"
+            echo " --- Start File --- "
+            echo "${{ steps.create-sdr.outputs.sdr }}"
+            echo " --- End File --- "
+
+            # Create a step summary
+            echo "# Error" >> $GITHUB_STEP_SUMMARY
+            echo "Branch $BRANCH already exists, PR will need to be created manually. SDR contents are below. Exiting." >> $GITHUB_STEP_SUMMARY
+            echo "## Filename" >> $GITHUB_STEP_SUMMARY
+            echo "\`${{ steps.create-sdr.outputs.filename }}\`" >> $GITHUB_STEP_SUMMARY
+            echo "## SDR Contents" >> $GITHUB_STEP_SUMMARY
+            echo "${{ steps.create-sdr.outputs.sdr }}" >> $GITHUB_STEP_SUMMARY
+            exit 1
+          fi
diff --git a/.github/workflows/sdr-proposed.yaml b/.github/workflows/sdr-proposed.yaml
index 7ec8da6..02909d1 100644
--- a/.github/workflows/sdr-proposed.yaml
+++ b/.github/workflows/sdr-proposed.yaml
@@ -6,7 +6,7 @@ on:
 
 jobs:
   main:
-    name: SDR created
+    name: SDR proposed
     runs-on: ubuntu-latest
 
     # Only run this workflow if the issue is open and has the "SDR" label

From aa060b7eef99c3ef459dd4bcbb136790f699c534 Mon Sep 17 00:00:00 2001
From: Ian McGinnis <67600557+ian-noaa@users.noreply.github.com>
Date: Thu, 10 Oct 2024 22:23:38 -0600
Subject: [PATCH 12/15] Update the README with a process overview

Also expand on the intended purpose and format.
---
 docs/decisions/README.md | 39 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/docs/decisions/README.md b/docs/decisions/README.md
index 24fd7bf..834cf77 100644
--- a/docs/decisions/README.md
+++ b/docs/decisions/README.md
@@ -8,3 +8,42 @@ This part of our documentation records decisions we have made for the VxIngest p
   - Scientific decisions are decisions focused on how to calculate & handle data
 
 This is largely inspired by the work done in the beta.weather.gov rewrite. You can [see their usage of ADRs in their GitHub repo here](https://github.com/weather-gov/weather.gov/tree/main/docs/architecture/decisions)
+
+## Purpose
+
+Decision Records are intended to be a useful record for current and new project members. They aren't intended to capture every trivial decision we make as that would quickly become noisy. Decision Records should capture why the team made certain significant decisions. Think of the audience as being yourself two or more years from now, a new project member with no context on the project trying to come up to speed, or a scientist trying to understand how we verify certain values.
+
+Decision records are supposed to be lightweight, so should be fairly quick to fill out. (However, the discussion prior to recording the decision may be more involved)
+
+## Format
+
+The format we will follow is largely [described by Michael Nygard in this article](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions) and is referenced in the issue template.
+
+**Title** The documents have concise titles that reflect the decision and start with "We will ...". For example, "We will record scientific decisions"
+
+**Status** Either `Accepted` or `Superseded`. If `Superseded`, reference its replacement like so: `Superseded by [ADR 0000](adr-0000-the-adr-title.md)`
+
+**Context** A statement of facts describing the motivating factors behind the decision: social, political, technical, scientific, etc. Why does this decision need to be made?
+
+**Decision** What was decided? This should be an active voice statement. For example, "We will ..."
+
+**Consequences** This section describes the resulting context, after applying the decision. All consequences should be listed here, not just the "positive" ones. A particular decision may have positive, negative, and neutral consequences, but all of them affect the team and project in the future.
+
+**Filename** Decision records will be stored in Markdown files. The fileanames will be lower-case copies of the titles, solely with ASCII characters, and with spaces/underscores swapped for dashes (`-`). The title is prefaced by `adr-XXXX-` or `sdr-XXXX-` where `XXXX` is the ADR/SDR number. For example, `adr-0001-we-will-record-scientific-decisions.md`.
+
+## Process
+
+To open an ADR or SDR, you will need to:
+
+1. First, make a significant decision as a team. We will most likely have discussed the core of the decision before the decision record is made.
+2. Open a new issue and choose the appropriate ADR or SDR template.
+3. Fill out the issue template to record the decision.
+4. Ask for feed back in the issue. You can use `@` mentions to loop people in to the conversation.
+5. Incorporate feedback by editing the ADR/SDR issue body until the decision is well captured.
+6. Once the decision has been made, there are two routes:
+
+    - Reject the decision - if we decide not to move forward with the decision, close the issue.
+    - Accept the decision - if we decide to accept the decision, add the appropriate `ADR/SDR: accepted` label and close the issue
+
+7. A PR with the Decision Record will be automatically created. Review the generated Markdown for sanity and merge it promptly.
+8. If a decision record supersedes another, include a link to the superseded decision in the Decision Record's `Context` section. The old/superseded decision record's `Status` section will need to be manually updated in the PR to link to the new decision record. Use a relative markdown link like `Supersedes [ADR 0000](adr-0000-superseded-adr-file.md)`, instead of a GitHub URL to do the linking.

From 889e4196c01362fd98d82cb8bd3b1c66f13d56e1 Mon Sep 17 00:00:00 2001
From: Ian McGinnis <67600557+ian-noaa@users.noreply.github.com>
Date: Thu, 10 Oct 2024 22:23:59 -0600
Subject: [PATCH 13/15] Update SDR 0002 to match the proposed format

---
 .../sdr-0002-recalculate-all-heights-for-raobs.md    | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

diff --git a/docs/decisions/scientific/sdr-0002-recalculate-all-heights-for-raobs.md b/docs/decisions/scientific/sdr-0002-recalculate-all-heights-for-raobs.md
index f3b92ca..a587631 100644
--- a/docs/decisions/scientific/sdr-0002-recalculate-all-heights-for-raobs.md
+++ b/docs/decisions/scientific/sdr-0002-recalculate-all-heights-for-raobs.md
@@ -1,4 +1,4 @@
-# Recalculate all heights for RAOBS
+# We will recalculate all heights for radiosonde observations
 
 Date: 2024-10-09
 
@@ -8,7 +8,7 @@ Accepted
 
 ## Context
 
-This decision was actually made a couple of years ago but we are recording it now. Because height data from radiosondes was unreliable a decision was made with the advice of senior meteorologists to always recalculate all height values. Currently all height values are calculated from the lowest reported height using the hypsometric equation and the reported temperature, pressure, and mixing ratio (derived from the specific humidity).
+This decision was actually made a couple of years ago but we are recording it now. Because height data from radiosondes (RAOBS) was unreliable a decision was made with the advice of senior meteorologists to always recalculate all height values. Currently all height values are calculated from the lowest reported height using the hypsometric equation and the reported temperature, pressure, and mixing ratio (derived from the specific humidity).
 
 Once the heights are calculated, all variables, including heights, are interpolated to mandatory pressure levels using logarithmic interpolation.
 
@@ -20,8 +20,14 @@ We will always recalculate heights using the [hypsometric equation](https://unid
 
 ### Positive
 
+- We will have consistent height levels for computing further verification statistics
+- The height levels will be derived from values we trust more than the recorded height; like temperature, pressure, and specific humidity.
+
 ### Neutral
 
-- It is important to understand this interpolation technique when comparing our RAOB data to the data in the PrepBufr files. They do not compare one to one.
+- It is important to understand this interpolation technique when comparing our RAOB data to the data in the raw PrepBufr-formatted RAOB observation files. They do not compare one to one.
 
 ### Negative
+
+- The height levels will be derived from other data, rather than using the measured values. This could differ from other ways the RAOB observation data is used in models.
+- We will be further interpolating the observations to the mandatory levels.

From f66662edfb8c83e7ab7529b404a914ec19892089 Mon Sep 17 00:00:00 2001
From: Ian McGinnis <67600557+ian-noaa@users.noreply.github.com>
Date: Thu, 10 Oct 2024 22:25:17 -0600
Subject: [PATCH 14/15] Update ADR names to match the proposed format

---
 ...sions.md => adr-0001-we-will-record-architecture-decisions.md} | 0
 ...cisions.md => sdr-0001-we-will-record-scientific-decisions.md} | 0
 ...s.md => sdr-0002-we-will-recalculate-all-heights-for-raobs.md} | 0
 3 files changed, 0 insertions(+), 0 deletions(-)
 rename docs/decisions/architecture/{adr-0001-record-architecture-decisions.md => adr-0001-we-will-record-architecture-decisions.md} (100%)
 rename docs/decisions/scientific/{sdr-0001-record-scientific-decisions.md => sdr-0001-we-will-record-scientific-decisions.md} (100%)
 rename docs/decisions/scientific/{sdr-0002-recalculate-all-heights-for-raobs.md => sdr-0002-we-will-recalculate-all-heights-for-raobs.md} (100%)

diff --git a/docs/decisions/architecture/adr-0001-record-architecture-decisions.md b/docs/decisions/architecture/adr-0001-we-will-record-architecture-decisions.md
similarity index 100%
rename from docs/decisions/architecture/adr-0001-record-architecture-decisions.md
rename to docs/decisions/architecture/adr-0001-we-will-record-architecture-decisions.md
diff --git a/docs/decisions/scientific/sdr-0001-record-scientific-decisions.md b/docs/decisions/scientific/sdr-0001-we-will-record-scientific-decisions.md
similarity index 100%
rename from docs/decisions/scientific/sdr-0001-record-scientific-decisions.md
rename to docs/decisions/scientific/sdr-0001-we-will-record-scientific-decisions.md
diff --git a/docs/decisions/scientific/sdr-0002-recalculate-all-heights-for-raobs.md b/docs/decisions/scientific/sdr-0002-we-will-recalculate-all-heights-for-raobs.md
similarity index 100%
rename from docs/decisions/scientific/sdr-0002-recalculate-all-heights-for-raobs.md
rename to docs/decisions/scientific/sdr-0002-we-will-recalculate-all-heights-for-raobs.md

From 8e0319ebced3cac3d533fc07e48282658e4e22ca Mon Sep 17 00:00:00 2001
From: Ian McGinnis <67600557+ian-noaa@users.noreply.github.com>
Date: Thu, 10 Oct 2024 22:25:56 -0600
Subject: [PATCH 15/15] Update titles to reflect the proposed format

---
 .../adr-0001-we-will-record-architecture-decisions.md           | 2 +-
 .../scientific/sdr-0001-we-will-record-scientific-decisions.md  | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/decisions/architecture/adr-0001-we-will-record-architecture-decisions.md b/docs/decisions/architecture/adr-0001-we-will-record-architecture-decisions.md
index 34c50b2..cf568ba 100644
--- a/docs/decisions/architecture/adr-0001-we-will-record-architecture-decisions.md
+++ b/docs/decisions/architecture/adr-0001-we-will-record-architecture-decisions.md
@@ -1,4 +1,4 @@
-# Record architecture decisions
+# We will record architecture decisions
 
 Date: 2024-10-08
 
diff --git a/docs/decisions/scientific/sdr-0001-we-will-record-scientific-decisions.md b/docs/decisions/scientific/sdr-0001-we-will-record-scientific-decisions.md
index 1b24a19..561d3d0 100644
--- a/docs/decisions/scientific/sdr-0001-we-will-record-scientific-decisions.md
+++ b/docs/decisions/scientific/sdr-0001-we-will-record-scientific-decisions.md
@@ -1,4 +1,4 @@
-# Record scientific decisions
+# We will record scientific decisions
 
 Date: 2024-10-08