docs: adopt upstream improvements.md log + voice-providers cheat-sheet#14
Merged
dhruva-reddy merged 1 commit intomainfrom May 2, 2026
Merged
Conversation
Contributor
Author
This was referenced May 1, 2026
## ELI5
**Problem.** Two of our customer-fork repos (`gitops-mudflap`,
`gitops-amazon3p`) kept their own running notes about engine quirks
("man, this is annoying when X happens"). Those notes never made it
back upstream, so every new customer hit the same friction. There was
also no convention for *anyone* — human or AI — to leave behind a
"this should be better" trail.
**What this fix does.** Adopts the customer-log format upstream
(severity-ranked, evidence-tagged) and seeds it with 20 entries
catalogued from both customer logs. Adds a voice-provider cheat-sheet
under `docs/learnings/` so the most common 400-rejection class
(`voice.speed` on Cartesia) becomes a one-page lookup. Updates
`.gitignore` to stop sweeping AI agent handoff scratch (`.agent/`,
`.claude/handoffs/`) into commits via `git add -A`. Adds a CLAUDE.md
section telling future contributors how to log new entries.
**Outcome you'll notice.** Every fresh customer clone of this template
inherits the running log on day one. When you hit something annoying,
you append an entry in the same change instead of carrying it as
folklore. As later stacks land, rows in the triage table flip from
`Open` to `RESOLVED` so the file becomes a living changelog.
---
Land all the zero-engine-change cleanups in one small PR so the rest
of the stack starts from a clean docs surface.
- improvements.md (NEW, repo root): adopt the severity-ranked, evidence-
tagged catalog format from the Amazon3p customer log. Seeds 20 entries
catalogued from gitops-mudflap and gitops-amazon3p. Triage table rows
flip from Open → RESOLVED as later stacks land.
- docs/learnings/voice-providers.md (NEW): per-provider voice block
cheat-sheet (Cartesia vs 11labs vs OpenAI/Azure/Rime/LMNT/Minimax/
Neuphonic/SmallestAI). Closes the manual-lookup half of #9.
- docs/learnings/README.md: route the new entry from the index.
- AGENTS.md: document multi-file push (closes #14) + voice-providers
routing row.
- CLAUDE.md: add Improvements log section instructing future contributors
(humans + AI agents) to append entries when they hit friction.
- .gitignore: cover .agent/, .agent/handoffs/, .claude/handoffs/ so
git add -A doesn't sweep PII handoff scratch (closes #13). Drop the
legacy "requested improvements.md" line since the local-only convention
is superseded by upstream's improvements.md.
Closes improvements.md #13, #14. Partial #9 (doc cheat-sheet half).
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---
## Update — 11labs pronunciation dictionary coverage
Generalized the docs+log from "Cartesia voice picker drops the
pronunciation dictionary" to "voice edits drop the dictionary across
both Cartesia and 11labs", since the Vapi platform documents 11labs
as the supported provider for pronunciation dictionaries
(https://docs.vapi.ai/assistants/pronunciation-dictionaries) and
exposes a different field shape:
- 11labs (documented): `voice.pronunciationDictionaryLocators[]`
(array of `{ pronunciationDictionaryId, versionId }`).
- Cartesia (passthrough): `voice.pronunciationDictId` (single string
id; not in Vapi docs but observed in real customer payloads).
Doc + improvements.md updates only — the engine-side drift detection
that uses these shapes lands in PR #20 (Stack G).
dhruva-reddy
force-pushed
the
dhruva-reddy/docs/improvements-log
branch
from
6cd7e2e to
28aa4c9
Compare
adhamvapi
approved these changes
May 1, 2026
Contributor
Author
Merge activity
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
ELI5
Problem. Two of our customer-fork repos (
gitops-mudflap,gitops-amazon3p) kept their own running notes about engine quirks("man, this is annoying when X happens"). Those notes never made it
back upstream, so every new customer hit the same friction. There was
also no convention for anyone — human or AI — to leave behind a
"this should be better" trail.
What this fix does. Adopts the customer-log format upstream
(severity-ranked, evidence-tagged) and seeds it with 20 entries
catalogued from both customer logs. Adds a voice-provider cheat-sheet
under
docs/learnings/so the most common 400-rejection class(
voice.speedon Cartesia) becomes a one-page lookup. Updates.gitignoreto stop sweeping AI agent handoff scratch (.agent/,.claude/handoffs/) into commits viagit add -A. Adds a CLAUDE.mdsection telling future contributors how to log new entries.
Outcome you'll notice. Every fresh customer clone of this template
inherits the running log on day one. When you hit something annoying,
you append an entry in the same change instead of carrying it as
folklore. As later stacks land, rows in the triage table flip from
OpentoRESOLVEDso the file becomes a living changelog.Land all the zero-engine-change cleanups in one small PR so the rest
of the stack starts from a clean docs surface.
tagged catalog format from the Amazon3p customer log. Seeds 20 entries
catalogued from gitops-mudflap and gitops-amazon3p. Triage table rows
flip from Open → RESOLVED as later stacks land.
cheat-sheet (Cartesia vs 11labs vs OpenAI/Azure/Rime/LMNT/Minimax/
Neuphonic/SmallestAI). Closes the manual-lookup half of Specifying handoff tools in a squad requires UUID to function correctly #9.
routing row.
(humans + AI agents) to append entries when they hit friction.
git add -A doesn't sweep PII handoff scratch (closes docs(learnings): add /eval/simulation/* API endpoint reference #13). Drop the
legacy "requested improvements.md" line since the local-only convention
is superseded by upstream's improvements.md.
Closes improvements.md #13, #14. Partial #9 (doc cheat-sheet half).
🤖 Generated with Claude Code