From cf51e217b4155ef36c9e5ae667e2ddb014828997 Mon Sep 17 00:00:00 2001 From: tudorian95 Date: Thu, 4 Jun 2026 13:57:54 +0300 Subject: [PATCH] Add Sapat ADR workflow guide Signed-off-by: tudorian95 --- authors/tudorian95.md | 8 + ...definition_architecture_decision_record.md | 23 ++ ...urn_design_reviews_into_adrs_with_sapat.md | 335 ++++++++++++++++++ guides/assets/20260604_sapat_adr_workflow.svg | 38 ++ 4 files changed, 404 insertions(+) create mode 100644 authors/tudorian95.md create mode 100644 definitions/20260604_definition_architecture_decision_record.md create mode 100644 guides/20260604_turn_design_reviews_into_adrs_with_sapat.md create mode 100644 guides/assets/20260604_sapat_adr_workflow.svg diff --git a/authors/tudorian95.md b/authors/tudorian95.md new file mode 100644 index 00000000..1c09e6da --- /dev/null +++ b/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: diff --git a/definitions/20260604_definition_architecture_decision_record.md b/definitions/20260604_definition_architecture_decision_record.md new file mode 100644 index 00000000..e6f862fa --- /dev/null +++ b/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. diff --git a/guides/20260604_turn_design_reviews_into_adrs_with_sapat.md b/guides/20260604_turn_design_reviews_into_adrs_with_sapat.md new file mode 100644 index 00000000..7e6ce56f --- /dev/null +++ b/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/) diff --git a/guides/assets/20260604_sapat_adr_workflow.svg b/guides/assets/20260604_sapat_adr_workflow.svg new file mode 100644 index 00000000..03522524 --- /dev/null +++ b/guides/assets/20260604_sapat_adr_workflow.svg @@ -0,0 +1,38 @@ + + Sapat to ADR workflow + A five step workflow from design review recording to Sapat transcription to ADR review. + + + + + + + + + Recording + Design review + or demo call + + + Daytona + Run Sapat in a + clean workspace + + + Transcript + Sidecar text plus + review notes + + + ADR + Decision + record + + Review for secrets, private names, evidence, owners, and status before sharing. +