Skip to content

F6: Add per-namespace blurbs to dialect.yaml so agents can disambiguate borderline keys #7

@ChauCM

Description

@ChauCM

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).

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions