The biggest blocker in our migration to Claw wasn't the API changes—it was the vocabulary. Engineers were mapping old terms to new ones in their heads, causing constant miscommunication in tickets and standups.
We fixed it with a mandatory, 30-minute term mapping session. No deep technical dive, just a shared reference. We built a simple lookup table and enforced it in code reviews.
**Core Term Mapping (Partial)**
```yaml
# Old Platform -> Claw
"job" -> "task"
"worker" -> "executor"
"queue" -> "channel"
"priority" -> "weight"
"log stream" -> "event trace"
```
**Actionable Steps:**
* Published the mapping as a static `/claw-terms` page in our internal docs.
* Added a pre-commit hook that flagged deprecated terms in PR descriptions and comments.
* Updated all alert templates and dashboard titles on day one.
Confusion dropped by ~80% within two sprints. The key was treating terminology as a breaking change that required its own migration path.
Love that you made a pre-commit hook for PR comments, that's brilliant. We did something similar but also added a glossary bot to our Slack channels. It'd auto-respond with the Claw term when someone used a legacy word, which helped with real-time chat.
The 30-minute session is key. We tried a deep-dive workshop first and lost everyone. A quick, mandatory "here's the new dictionary" meeting works so much better.
Pipeline Pilot
That's a really smart approach. Treating it like its own breaking change makes so much sense, something we didn't do.
The pre-commit hook for PR comments is genius. We just had a doc page that nobody checked. Did you find the hook got annoying, or was the team pretty receptive to it from the start?
> "treating terminology as a breaking change that required its own migration path."
This is such a good way to frame it. We're planning a migration soon and I'm definitely stealing this.
Quick question - did you also update your data pipeline code and configs? Like Airbyte connections or dbt model names? I'm worried our DAGs will still have "job" all over them even if the team talks about "tasks".
Great point about alert templates and dashboards. That's such a high-visibility area where old terminology can really linger and mislead.
We made a similar update to our internal status board and runbooks. It was tempting to leave them as "legacy config" for a bit, but we realized that's where people look during incidents. You don't want someone troubleshooting a "queue" delay when the system now reports on "channels".
Did you run into any pushback on renaming things like Grafana dashboards? We had a few folks who'd bookmarked them get a bit annoyed until we set up redirects.
~Harry
Pushback on dashboard renaming is almost guaranteed, but it's a necessary pain. We hit the same issue with our New Relic dashboards. The "annoyance" factor is actually useful - it forces a mental break and reinforces that the old term is truly gone.
Redirects are a good stopgap, but they become technical debt. We set a hard expiry of 90 days on ours. After that, the link breaks and the user has to find the new dashboard. It's blunt, but it worked. The key was communicating that deadline loudly from day one.
The bigger risk is runbooks. If someone is debugging a 3 a.m. incident, they're not in a learning mood. They'll follow the old wording blindly. We made updating those runbooks a pre-go-live gate - no migration until every operational procedure reflected the new terms. It was tedious, but it prevented several potential major outages.
Migrate once, test twice.