Turn design reviews into ADRs with Sapat

authors/tudorian95.md

@@ -0,0 +1,8 @@
+Author: Tudorian95 Title: AI-Assisted Open Source Contributor Description:
+Tudorian95 contributes focused documentation and developer-workflow improvements
+to open-source projects, with an emphasis on reproducible environments, careful
+validation, and practical AI-assisted engineering workflows. Author Image:
+![tudorian95](https://avatars.githubusercontent.com/u/57180878?v=4) Author
+LinkedIn: Author Twitter: Company Name: Independent Company Description:
+Independent contributor working on practical developer tooling and open-source
+documentation. Company Logo Dark: Company Logo White:

definitions/20260604_definition_architecture_decision_record.md

@@ -0,0 +1,23 @@
+---
+title: "Architecture Decision Record"
+description: "A short document that records an important architecture decision, its context, and its consequences."
+date: 2026-06-04
+author: "Tudorian95"
+---
+
+# Architecture Decision Record
+
+## Definition
+
+An Architecture Decision Record, often shortened to ADR, is a concise document
+that records an important technical decision. It usually includes the decision
+context, the options considered, the chosen option, the expected consequences,
+and the current status of the decision.
+
+## Context and Usage
+
+Engineering teams use ADRs to preserve the reasoning behind architectural
+choices. Instead of relying on meeting memory or scattered chat messages, an ADR
+gives future contributors a stable explanation of why a system works the way it
+does. ADRs are especially useful after design reviews, incident follow-ups,
+platform migrations, and API contract changes.

guides/20260604_turn_design_reviews_into_adrs_with_sapat.md

@@ -0,0 +1,335 @@
+---
+title: "Turn Design Reviews into ADRs with Sapat"
+description: "Build a Daytona workflow that turns design-review recordings into reviewable Architecture Decision Record packages with Sapat."
+date: 2026-06-04
+author: "Tudorian95"
+tags: ["daytona", "sapat", "transcription", "adr"]
+---
+
+# Turn Design Reviews into ADRs with Sapat
+
+# Introduction
+
+Design-review calls often contain the details that never make it into the final
+ticket: the rejected options, the reason a team chose one tradeoff over another,
+and the follow-up questions that should not be lost after the meeting ends.
+Transcribing the recording is useful, but a raw transcript is still too loose
+for long-term engineering memory.
+
+This guide shows how to run Sapat in a Daytona workspace and turn a design-review
+recording into a small [Architecture Decision Record](../definitions/20260604_definition_architecture_decision_record.md)
+package. The workflow is deliberately provider-agnostic. It focuses on keeping
+the workspace reproducible, keeping secrets out of the repository, and shaping
+the transcript into a decision artifact that another engineer can review.
+
+## TL;DR
+
+- Create a Daytona workspace from the Sapat repository.
+- Configure one transcription provider through local environment variables.
+- Run Sapat against a design-review recording or a folder of recordings.
+- Convert the transcript into an ADR with context, options, decision,
+  consequences, evidence snippets, and owners.
+- Review the ADR before sharing it so private meeting details and API keys stay
+  out of source control.
+
+![Sapat to ADR workflow](assets/20260604_sapat_adr_workflow.svg)
+
+## When This Workflow Fits
+
+Use this workflow when a meeting produces a decision that will matter after the
+call ends. Good candidates include architecture reviews, API contract debates,
+platform migration choices, incident remediation plans, and security design
+reviews. The recording should contain enough context to explain the decision,
+but the final artifact should still be the ADR, not the full transcript.
+
+Skip this workflow for informal standups, private performance conversations,
+or meetings where the group has not agreed to transcription. If the decision is
+already obvious from a pull request discussion or a design document, write the
+ADR directly and link that source instead. Transcription helps most when the
+important reasoning exists only in spoken form.
+
+## Materials Checklist
+
+Before starting, prepare the following:
+
+- A Daytona installation and an IDE connected to your Daytona workspace.
+- A GitHub account with access to the repository where you keep ADRs.
+- A design-review recording that your team is allowed to process.
+- `ffmpeg`, because Sapat uses it to convert media before transcription.
+- One supported Sapat provider configured with environment variables, such as
+  `GROQ_API_KEY`, `MISTRAL_API_KEY`, or the Azure OpenAI variables required by
+  the provider you choose.
+- A local `.env` file that is ignored by Git.
+
+Do not use production customer recordings while validating the workflow. Start
+with an internal demo call, a self-recorded explanation, or a meeting where all
+participants agreed to transcription.
+
+## Step 1: Create the Daytona Workspace
+
+Start from the Sapat repository so the workspace reflects the same codebase that
+defines the CLI, providers, and tests:
+
+```bash
+daytona create https://github.com/nibzard/sapat --code
+```
+
+When the workspace opens, create a Python virtual environment and install the
+package in editable mode:
+
+```bash
+python -m venv .venv
+. .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -e .
+```
+
+Confirm that `ffmpeg` is available:
+
+```bash
+ffmpeg -version
+```
+
+If the command is missing, add it through your workspace image, package manager,
+or dev container configuration. Sapat converts the input file to the preferred
+audio format for the selected provider before it sends the transcription
+request.
+
+## Step 2: Configure One Provider
+
+Sapat discovers providers dynamically. A provider is available only when its
+required environment variables are present and its optional Python packages are
+installed. Pick one provider for the first run instead of configuring every
+service at once.
+
+For example, a Groq-based smoke run only needs a local key:
+
+```bash
+cat > .env <<'EOF'
+GROQ_API_KEY=replace-with-your-local-key
+EOF
+```
+
+A Mistral run can use:
+
+```bash
+cat > .env <<'EOF'
+MISTRAL_API_KEY=replace-with-your-local-key
+MISTRAL_CHAT_MODEL=mistral-small-latest
+EOF
+```
+
+Keep `.env` out of Git. Use repository or workspace secrets for shared team
+workflows, and rotate any key that accidentally appears in logs, screenshots,
+or a pull request.
+
+## Step 3: Prepare the Recording
+
+Create a small folder for recordings and transcript outputs:
+
+```bash
+mkdir -p recordings transcripts adr
+```
+
+Copy the design-review file into `recordings/`. Use a name that describes the
+decision instead of the meeting invite:
+
+```text
+recordings/cache-key-design-review.mp4
+```
+
+Before transcription, write down a short glossary for the meeting. This is not a
+secret prompt; it is a small accuracy aid for product names, service names, and
+acronyms:
+
+```text
+Terms: Edge cache, KV namespace, cache stampede, invalidation window.
+People: Alice leads API design. Marco owns observability.
+Goal: Decide how cache keys should be normalized for public API requests.
+```
+
+That glossary becomes the transcription prompt. It reduces cleanup time because
+the provider has more context about domain-specific language.
+
+## Step 4: Run Sapat with Decision Context
+
+Run Sapat against a single file with an explicit provider. This example uses
+Groq, but the same pattern applies to other configured providers:
+
+```bash
+sapat recordings/cache-key-design-review.mp4 \
+  --provider groq \
+  --model whisper-large-v3 \
+  --quality M \
+  --language en \
+  --temperature 0 \
+  --transcription-prompt "Terms: Edge cache, KV namespace, cache stampede, invalidation window. Goal: decide cache key normalization for public API requests."
+```
+
+Sapat writes a `.txt` file next to the original recording:
+
+```text
+recordings/cache-key-design-review.txt
+```
+
+Move the transcript into the `transcripts/` folder and keep the original
+recording outside your pull request unless your team explicitly wants media
+artifacts committed:
+
+```bash
+mv recordings/cache-key-design-review.txt transcripts/cache-key-design-review.txt
+```
+
+For a folder of review calls, pass the directory instead of one file. Sapat
+processes `.mp4` files in that directory and writes sidecar transcript files.
+
+Use `--correct` only with providers that support correction. If a provider does
+not implement correction, Sapat warns and skips the correction pass. Treat
+correction as a spelling and punctuation helper, not as a substitute for human
+review.
+
+## Step 5: Extract the Decision Shape
+
+Read the transcript once before turning it into an ADR. Highlight lines that
+answer six questions:
+
+- What problem forced the decision?
+- Which options were considered?
+- Which option did the group choose?
+- What tradeoffs or risks were accepted?
+- Who owns follow-up work?
+- What evidence should future readers see?
+
+You can keep a lightweight notes file while reviewing:
+
+```markdown
+# Cache Key Design Review Notes
+
+## Context
+- Public API responses are cached at the edge.
+- Different query parameter ordering currently produces duplicate cache entries.
+
+## Options
+- Normalize query strings before cache lookup.
+- Cache only selected endpoints.
+- Leave current behavior and add observability first.
+
+## Decision
+- Normalize query strings before cache lookup.
+
+## Evidence
+- Alice: normalization removes duplicate entries without changing route owners.
+- Marco: observability still needs a dashboard before rollout.
+```
+
+Do not paste long transcript blocks into the ADR. Quote only short snippets that
+prove the decision and summarize the rest in your own words.
+
+## Step 6: Write the ADR Package
+
+Create one ADR file per decision:
+
+```bash
+cat > adr/0001-normalize-cache-keys.md <<'EOF'
+# ADR 0001: Normalize API Cache Keys
+
+## Status
+
+Proposed
+
+## Context
+
+Public API responses are cached at the edge. Today, equivalent requests can miss
+the same cache entry when query parameters arrive in a different order.
+
+## Options Considered
+
+- Normalize query strings before cache lookup.
+- Cache only selected endpoints.
+- Keep current behavior and add observability first.
+
+## Decision
+
+Normalize query strings before cache lookup.
+
+## Consequences
+
+- Cache hit rate should improve for equivalent requests.
+- Rollout needs a dashboard for duplicate-key rate and cache-hit changes.
+- Route owners must document any endpoint that depends on raw query ordering.
+
+## Evidence
+
+- Transcript: `transcripts/cache-key-design-review.txt`
+- Recording source: internal design-review call, not committed
+- Owner: API platform team
+EOF
+```
+
+The ADR should be short enough to review in a pull request. The transcript is a
+supporting artifact, not the primary deliverable.
+
+## Step 7: Review Before Sharing
+
+Before opening a pull request, run a privacy and quality pass:
+
+```bash
+grep -R "API_KEY\\|SECRET\\|TOKEN\\|PASSWORD" adr transcripts || true
+python -m compileall sapat tests
+git diff --check
+```
+
+Then review the ADR manually:
+
+- Remove customer names unless they are needed and approved.
+- Replace private meeting links with a description such as "internal design
+  review call."
+- Confirm that the status is accurate: `Proposed`, `Accepted`, `Superseded`,
+  or `Deprecated`.
+- Confirm that every owner named in the ADR has agreed to own the follow-up.
+- Keep the transcript file only if your team wants transcript artifacts in the
+  repository.
+
+## Common Issues and Troubleshooting
+
+**Problem:** Sapat reports that no providers are available.
+
+**Solution:** Confirm that your `.env` file is loaded in the terminal session
+and that the selected provider has every required environment variable. Some
+providers also require optional Python packages.
+
+**Problem:** `ffmpeg` is missing.
+
+**Solution:** Install it in the Daytona workspace image or add it to the
+workspace setup script. Sapat uses `ffmpeg` for conversion and large-file
+handling.
+
+**Problem:** The transcript confuses project names.
+
+**Solution:** Add a short `--transcription-prompt` with product names, service
+names, and acronyms. Keep the prompt factual and avoid including secrets.
+
+**Problem:** The ADR reads like meeting minutes.
+
+**Solution:** Move chronology into the transcript notes and keep the ADR focused
+on the decision. Future readers need the reason, the selected path, the rejected
+options, and the consequences.
+
+## Conclusion
+
+Sapat turns the design-review recording into text. Daytona gives the team a
+clean, reproducible workspace to run that workflow without polluting a laptop or
+hard-coding provider credentials. The ADR step is where the transcript becomes
+useful engineering memory: a small, reviewable record of the decision and its
+tradeoffs.
+
+Once this workflow is in place, teams can repeat it for database choices,
+security reviews, incident remediation plans, and API design discussions. The
+important habit is to keep raw transcription separate from the final decision
+record so the repository contains the durable conclusion, not the full meeting.
+
+## References
+
+- [Sapat repository](https://github.com/nibzard/sapat)
+- [Daytona documentation](https://www.daytona.io/docs/)
+- [Architecture Decision Records](https://adr.github.io/)