/language-idioms-refiner

name: language-idioms-refiner
description: "Facilitate a structured conversation to define language-specific idioms and patterns for a repository. Produces a language-idioms.md document consumed by multiple atoms to adapt pseudocode defaults to the project's language. Use when setting up a new project, switching languages, or when the user says 'setup language', 'define language idioms', 'configure language', 'language patterns', or 'adapt for Go/Rust/Python'."

Language Idioms Refiner

What This Produces

• **Output**: `.lattice/standards/language-idioms.md` (or custom path from `.lattice/config.yaml` -> `paths.language_idioms`)
• **Mode**: Always standalone -- no embedded language defaults exist in atoms to overlay on. For revisions, load existing document and update sections in place.
• **Config keys**:
• `language` (top-level) -- language identifier (e.g., `go`, `rust`, `python`, `java`, `typescript`)
• `paths.language_idioms` -- path to the produced document
• **Template**: Read `./assets/template.md` for the full document structure, pre-populated examples, and interview guidance comments
• **Consumed by**: Multiple atoms reference specific sections by heading name:

| Section | Consumed by | |---------|------------| | **Error Handling** | `clean-code` atom (§8), `secure-coding` atom (§2 validation error messages) | | **Type System & Object Model** | `clean-code` atom (§1 SRP/cohesion), `domain-driven-design` atom (entities, VOs, aggregates) | | **Naming Conventions** | `clean-code` atom (§4) | | **Testing Patterns** | `test-quality` atom (§5 naming, §4 isolation, §6 builders) | | **Parameter & Function Design** | `clean-code` atom (§2 function size, §5 parameters) | | **Dependency Management** | `clean-code` atom (§9 testability/DI), `architecture` atom (dependency direction) |

These six section headings are the **stable contract**. Atoms reference them by name. Additional sections can be added by consumers but these six must be present.

Scope Clarification

This document captures **how the project's language expresses engineering patterns** -- the language-level idioms that atoms need to adapt their pseudocode defaults. Clear boundaries:

| Concern | Where It Belongs | Not Here | |---------|-----------------|----------| | Project identity, tech stack, directory layout | `knowledge-priming` atom | No project structure or framework docs | | Code craftsmanship rules (thresholds, heuristics) | `clean-code` atom / overlay | No function size limits or DRY rules | | Architecture layers, dependency direction | `architecture` atom / overlay | No layer definitions | | Domain modeling guardrails | `domain-driven-design` atom / overlay | No aggregate rules | | Team-specific preferences within language | Atom-specific overlays | No team decisions (see below) |

**Key distinction from atom overlays**: This document describes *how the language works*. Atom overlays describe *how the team works within the language*.

• **Language idioms doc**: "Go uses explicit error returns (`if err != nil`), not exceptions"
• **Clean-code overlay**: "We use `fmt.Errorf('context: %w', err)` for wrapping, custom error types for domain errors"

Language idioms are facts about the language. Atom overlays are team choices.

Before You Begin

Check for existing documents

1. Read `.lattice/config.yaml` -- does `paths.language_idioms` point to a file? 2. If yes, read that file. Ask the user:

• "You already have a language idioms document for **[language]**. Would you like to **revise** it (update specific sections), **start fresh** (new interview), or **switch language**?"
• Revise: Load the existing document, walk through only the sections the user wants to change.
• Start fresh: Proceed with the full interview flow below.
• Switch language: Proceed with full interview for the new language; existing document will be replaced.

3. If no config or no existing document, proceed with the full interview flow.

Detect the language

Determine the project language before starting the interview:

1. **From config**: Check `.lattice/config.yaml` for `language` key. 2. **From project files** (if no config key):

• `package.json` → TypeScript / JavaScript
• `tsconfig.json` → TypeScript (confirm over JavaScript)
• `go.mod` → Go
• `pom.xml` or `build.gradle` or `build.gradle.kts` → Java or Kotlin
• `Cargo.toml` → Rust
• `requirements.txt` or `pyproject.toml` or `setup.py` → Python
• `Gemfile` → Ruby
• `*.csproj` or `*.sln` → C# / .NET
• `Package.swift` → Swift

3. **Multiple languages detected**: Ask the user which is the primary language. One language-idioms document per project (covers the primary language). 4. **No detection**: Ask the user directly.

<!-- synced with lattice-init "Language/framework detection" -- edit both -->

Present the detected language: "I detected this is a **Go** project (found `go.mod`). I'll propose Go-idiomatic patterns for each section. You can confirm or adjust."

Interview Flow

This refiner works differently from other refiners. Instead of showing defaults and asking "change or keep?", it **proposes language-specific content** and asks "does this match your team's usage?"

Step 1: Confirm language and version

"I detected **[Language] [version]**. Is this correct?"

Record language and version. These go in the document frontmatter.

Step 2: Walk through sections with proposals

For each of the 6 sections:

1. **Propose** pre-populated content based on the detected language (see Language-Specific Proposals below). 2. **Present** the proposal: "Here's what I'd recommend for [Language]. Does this match how your team uses [Language]?" 3. **User confirms** → record as-is. 4. **User adjusts** → discuss specifics, record their version.

Step 3: Additional sections

After the 6 core sections, ask: "Any language-specific patterns I should add? For example: concurrency patterns, memory management, async/await idioms, or fra