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:

| Section | Consumed by |
|---------|------------|
| **Error Handling** | `clean-code` atom (§8), `secure-coding` atom (§1 trust boundary 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.

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

| # | Section | What It Captures |
|---|---------|-----------------|
| 1 | **Error Handling** | Language error philosophy (exceptions, error returns, Result types), error propagation patterns, error creation idioms |
| 2 | **Type System & Object