rosetta

rosetta

Two Claude Code skills that teach you any codebase from what you already know.

Why "Rosetta"?

The Rosetta Stone was a decree written in three scripts — and for 2,000 years, scholars couldn't read ancient Egyptian. Then someone realised the same text was written in a language they already knew, and everything unlocked.

That's this skill. You already speak TypeScript. You already know what a middleware is, what dependency injection does, what an async boundary looks like. When you drop into a Java Spring backend or an Elixir Phoenix app, the concepts are mostly the same — they just wear different clothes.

Rosetta shows you the familiar face inside the unfamiliar syntax. And unlike a Rosetta Stone lesson, it also tells you exactly where the translation breaks down — because that's where the real learning happens.

Two skills, one knowledge map

/rosetta — for when the language is unfamiliar. Explains patterns by anchoring to your known stack, then calls out exactly where the analogy breaks down.

/cartographer — for when the codebase is unfamiliar. Maps design decisions, tradeoffs, and gotchas — even in languages you already know.

Both skills write to the same knowledge map per repo. Every session opens with your current familiarity score and what's left to explore:

Knowledge map: acme-backend
Familiarity: 41% — building fluency ████████░░░░░░░░░░░░ (10 / 24 pts)
Covered: goroutines, error wrapping, auth middleware, repository pattern
Not yet: context propagation, rate limiting, config management, …

Installation

npx skills@latest add github:mark-quinn/rosetta/skills/rosetta
npx skills@latest add github:mark-quinn/rosetta/skills/cartographer

The skills CLI copies both skills into your ~/.claude/skills/ directory. Install one or both — they share the same knowledge map.

Usage

Open any Claude Code session in a directory with unfamiliar code:

/rosetta

Or go straight to a concept:

/rosetta goroutines
/rosetta dependency injection

/cartographer auth
/cartographer error handling
/cartographer

First run asks a few questions to set up your profile. Every session after that opens with your current score.

How it works

Every language pattern is explained in five parts:

1. The Hook — one sentence naming the exact equivalent in your stack
2. The Bridge — how the new concept works, using real code from the repo
3. Where the analogy breaks down — 1–3 concrete differences (mandatory, never skipped)
4. Why it's designed this way — the motivation, so it sticks
5. One thing to try — a quick hands-on experiment in the current codebase

Every codebase pattern is explained in five parts:

1. What it does in this codebase — specific implementation, not generic concept
2. Why it was chosen — the problem solved and alternatives not taken
3. Tradeoffs — honest costs of the approach
4. Gotcha — the thing most likely to bite someone new
5. How it connects — threads to other patterns already in the map

Everything stored locally in plain markdown — human-readable and editable:

Example

/rosetta goroutines

In Node, you'd use async/await over a Promise for concurrent work. In Go, goroutines are the equivalent — lightweight functions you launch with go func() that run concurrently without you managing a thread pool.

Where the analogy breaks down

Node's event loop is single-threaded — your async code takes turns. Go's goroutines run in true parallel across OS threads. That means race conditions you'd never hit in Node can surface in Go, and you need channels or mutexes to coordinate shared state.

Why Go does it this way: the runtime scheduler is designed for thousands of concurrent goroutines cheaply. Node's model works great for I/O; Go's model works great for CPU-bound parallelism too.

Contributing

PRs are very welcome. This project gets better the more language pairs and codebase patterns it covers — and that knowledge comes from the community.

Good places to start:

• New codebase pattern categories — add detection signals and questions to skills/cartographer/CODEBASE-PATTERNS.md
• Analogy quality — if an explanation for a specific language pair could be sharper, improve skills/rosetta/EXPLANATION-GUIDE.md
• Edge cases — spotted a gap in the skill behaviour? The core logic is in skills/rosetta/SKILL.md and skills/cartographer/SKILL.md
• Language coverage — better slug detection for less common stacks, framework-specific pattern detection

If you're unsure whether something is worth a PR, open an issue first. No contribution is too small.

Built as Claude Code skills · MIT License