ga-domain-context

name	GA Domain Context
description	Primes every session with the guitarist's perspective, GA architecture, and how to use the MCP tools during feature development. Load this before working on any Guitar Alchemist feature.
triggers	["guitarist problem","guitar alchemist feature","GA backlog","music theory feature","chord substitution","improvisation feature"]

GA Domain Context

Guitar Alchemist is a music platform for guitarists, not a generic dev project. Every feature decision should start with a real guitarist's pain, verified with the GA MCP tools, then implemented in the GA domain model.

---

Who We're Building For

A guitarist who:

• Knows songs but not always why they work harmonically
• Learns by ear first, theory second
• Hits a wall: "why does this sound wrong?" / "what can I play here?"
• Wants answers in guitarist vocabulary: chord names, fret positions, tab — not abstract intervals

North Star question for every feature: What does a guitarist do with this?

---

GA MCP Tools — Use During Development, Not Just Runtime

The ga-dsl MCP server (registered as mcp__ga-dsl__*) gives you live music theory during brainstorming and planning. Call these tools when designing features to verify your theory is correct before writing code.

Verification workflow for a guitarist problem

1. Identify the musical concept — what chord, scale, or key is involved?
2. Verify with MCP tools — call GaAnalyzeProgression, GaChordIntervals, GaCommonTones to ground the feature in real theory
3. Design the output — what does the guitarist see? (tab, chord symbol, fretboard, explanation)
4. Implement in the right layer — see architecture below

Key tools and when to use them

Tool	When to call it
GaAnalyzeProgression("Am F C G")	Whenever a feature involves key detection or Roman numeral labelling
GaDiatonicChords("G", "major")	When suggesting chords that "fit" a key
GaChordIntervals("Cmaj7")	When explaining why a chord sounds the way it does
GaCommonTones("G7", "Cmaj7")	When implementing voice-leading or pivot-chord features
GaTransposeChord("Am7", 7)	When implementing transposition or capo features
GaRelativeKey("A", "minor")	When implementing relative key or parallel key features
GaSearchTabs("metallica nothing else matters")	When a feature needs real-world tab examples
GaInvokeClosure("domain.queryChords", '{"key":"G","scale":"major","quality":"minor"}')	For advanced diatonic filtering

---

Architecture Quick Reference

Five-layer rule (strict — no exceptions)

Layer 1 — GA.Core / GA.Domain.Core      Pure primitives: Note, Interval, PitchClass, Fretboard
Layer 2 — GA.Business.Core              Business logic, chord analysis, scale queries
Layer 3 — GA.Business.Core.Harmony      Voice leading, chord progression analysis
Layer 4 — GA.Business.ML                Embeddings (OPTIC-K), semantic search, agents
Layer 5 — GA.Business.Core.Orchestration High-level workflows, IntelligentBSPGenerator

Rule: new code goes in the lowest layer that has everything it needs. AI code → Layer 4. Workflows → Layer 5. Pure music math → Layer 1 or 2.

Where guitarist features typically land

Problem type	Layer	Example
"What intervals are in this chord?"	1–2	Chord.Intervals, ChordDslService
"Which chords fit this key?"	2–3	DiatonicChordService
"Suggest a substitution"	3	HarmonicTransformationService
"Find similar-sounding songs"	4	OPTIC-K embedding + vector search
"Generate a practice routine"	5	Orchestration + agent composition

F# DSL — the closure registry

The GA Language closures (domain.*, tab.*, agent.*) live in GA.Business.DSL. They are:

• Registered at module load via do register()
• Accessible in-process via GaClosureRegistry.Global
• Exposed to Claude Code via the ga-dsl MCP server

When adding a new music-theory closure, add it to DomainClosures.fs and register it in register().

OPTIC-K embeddings (216 dimensions)

Used for semantic similarity between chord voicings/BSP rooms. Never change dimension count without a full re-index. Structure:

• dims 6–29: STRUCTURE (pitch-class invariants) — weight 0.45
• dims 30–53: MORPHOLOGY (fretboard geometry) — weight 0.25
• dims 54–65: CONTEXT (harmonic function) — weight 0.20
• dims 66–77: SYMBOLIC (manual tags) — weight 0.10

---

The Compound Engineering Loop for GA

Guitarist problem (BACKLOG.md)
    ↓
Brainstorm: call GA MCP tools to verify the music theory
    ↓  GaAnalyzeProgression, GaChordIntervals, GaCommonTones…
Plan: docs/plans/ — what does the guitarist see + how does it map to layers?
    ↓
Implement: lowest layer first, ROP error handling, unit tests
    ↓
Document: update BACKLOG.md (remove idea), link plan to PR
    ↓
Compound: solution is now a closure / endpoint / UI feature
         that makes the NEXT problem easier to solve

Each solved problem expands the closure registry, which makes future features faster: GaCommonTones built for voice-leading also powers pivot-chord detection and substitution suggestions.

---

Guitarist Vocabulary → GA Concepts

What a guitarist says	GA concept	Tool / layer
"What key am I in?"	Key inference from chord set	GaAnalyzeProgression
"What scale fits here?"	Diatonic scale from key	GaDiatonicChords
"Why does this note sound outside?"	Chromatic pitch class vs. diatonic set	GaChordIntervals + set math
"What can I play instead?"	Chord substitution	GaCommonTones + GaRelativeKey
"How do I finger this?"	Fretboard geometry	GA.Business.Core.Fretboard layer
"Show me a lick"	Tab generation	tab.generateChord, VexTabGenerator
"Find me a tab"	Internet tab search	GaSearchTabs (Archive.org + GitHub)
"This sounds jazzy/bluesy"	Stylistic tag	OPTIC-K SYMBOLIC dims

---

Before Implementing Any Feature

1. Call at least one MCP tool to verify the music theory is correct
2. Ask: what does a guitarist do with this output? (tab, chord name, fretboard, text)
3. Place in the right layer — never put orchestration in Layer 1-2
4. ROP all the way — service methods return Result<T, TError>, never throw
5. Write a test that uses a real chord symbol or progression, not mocked values