language-idioms-refiner

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:

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:

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.

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 framework-specific conventions."

Record any additional sections the user wants.

Step 4: Produce document

Assemble and write the document.

Section-by-Section Interview Guide

Read ./assets/template.md and follow the <!-- INTERVIEW GUIDANCE: --> comments for each section.

The 6 core sections

Cross-section awareness

Language-Specific Proposals

For well-known languages, pre-populate each section with idiomatic defaults. The interview confirms or adjusts these. For unrecognized languages, ask open-ended questions.

Go

Rust

Python

Java / Kotlin

TypeScript

C# / .NET

Other Languages

For languages not listed above, use open-ended questions for each section:

1. "How does [Language] handle errors? Exceptions, error returns, algebraic types, or something else?"
2. "What's the object model? Classes, structs, traits, protocols? Inheritance or composition?"
3. "What are the naming conventions? Case style, visibility markers, module naming?"
4. "What's the testing ecosystem? Framework, organization, assertion style?"
5. "How do you pass configuration and options to functions? Named params, objects, builders?"
6. "How is dependency injection handled? Containers, manual wiring, interface parameters?"

Output Assembly

1. YAML frontmatter: language and version
2. Title line: # Language Idioms: {Language}
3. All 6 core sections with confirmed/adjusted content
4. Any additional sections the user added
5. Strip all <!-- INTERVIEW GUIDANCE: --> comments

Target size: 40-60 lines of focused content. Each section should be 4-8 lines: a brief philosophy statement plus the key idiomatic patterns as a concise list. No code examples -- atoms have their own examples in pseudocode that they adapt using this document's guidance.

Determine output path:

1. If .lattice/config.yaml exists and has paths.language_idioms, use that path.
2. Otherwise, default to .lattice/standards/language-idioms.md.

Update config:

1. Set language: {language} at top level (create or update).
2. Set paths.language_idioms pointing to the output file.
3. If .lattice/config.yaml does not exist, create it. Preserve all existing content.

Confirm to user: "Your language idioms document has been written to [PATH] for [Language] [version]. The following atoms will now adapt their patterns: clean-code, test-quality, secure-coding, domain-driven-design, and architecture."

Document Quality Checks

Before writing the final document, verify:

• All 6 core section headings are present and match exactly: Error Handling, Type System & Object Model, Naming Conventions, Testing Patterns, Parameter & Function Design, Dependency Management
• Content is specific to the language, not generic advice ("use error returns" not "handle errors properly")
• No code craftsmanship rules (thresholds, complexity limits) -- those belong in atom overlays
• No project identity information (tech stack, directory layout) -- that belongs in knowledge-priming
• Content is concise -- each section 4-8 lines, total document under 60 lines
• Frontmatter has correct language and version values
• Config file is correctly updated with both language key and paths.language_idioms
• No <!-- INTERVIEW GUIDANCE: --> comments remain in output