Surfaced by a pilot test (Claude Code Opus 4.7 against examples/after/, 2026-05-24). Full feedback: dialect-feed.md.
Problem
Today the meaning of each namespace lives only in @key.description ad-hoc. An agent classifying a new key has to read every existing key in that namespace to understand the namespace's purpose.
Fix
Add a namespaces: block in dialect.yaml where each entry can include a one-liner:
namespaces:
checkout: "Booking confirmation flow — payment + agreement screen."
settings: "User account preferences."
home: "Trip list, top-level navigation."
common: "Shared UI strings (cancel, save, loading)."
The agent reads these blurbs at extract time to decide where a new key belongs ("does this go in common or settings?") without having to scan every existing key.
Acceptance
dialect.yaml supports a namespaces: block with per-namespace descriptions.
- Init plan / describe plan templates teach the agent to read these blurbs when deciding namespace placement.
dialect check flags namespaces that lack a blurb (warning, not error).
Surfaced by a pilot test (Claude Code Opus 4.7 against
examples/after/, 2026-05-24). Full feedback:dialect-feed.md.Problem
Today the meaning of each namespace lives only in
@key.descriptionad-hoc. An agent classifying a new key has to read every existing key in that namespace to understand the namespace's purpose.Fix
Add a
namespaces:block indialect.yamlwhere each entry can include a one-liner:The agent reads these blurbs at extract time to decide where a new key belongs ("does this go in
commonorsettings?") without having to scan every existing key.Acceptance
dialect.yamlsupports anamespaces:block with per-namespace descriptions.dialect checkflags namespaces that lack a blurb (warning, not error).