Tasks
Back to task
Task report

Task Report — Add Lydian Chromatic Concept Study Tab

Project: music-study
Task: Add Lydian Chromatic Concept study tab
Assignee: Cadu
Type: Frontend / Music Theory Engine
Estimate: 8 hours
Recommended status: Ready for implementation
Priority: Medium–High

1. Summary

This task adds a new Lídio Cromático / Lydian Chromatic study area to the Music Study app.

The current app is centered on four parent scales, their modes, harmonic fields, and comparisons. That structure is useful, but it does not yet support the class workflow used by the teacher:

chord quality → target/alvo → parent scale/escala-mãe → ordered scale options → improvisation exercise

The new feature should be implemented as a separate study mode, not as another item inside the existing scale selector. The goal is to create a first vertical slice that can be expanded later with more teacher-specific harmony content.

2. Main architecture decision

The Lydian Chromatic Concept material should have its own typed theory module and a small pure computation engine.

The implementation should avoid putting theory mappings directly inside JSX. It should also avoid mixing this feature into the existing four-scale engine unless there is a clear reusable helper.

Recommended structure:

src/
├── theory/
│   └── lydianChromatic/
│       ├── types.ts
│       ├── data.ts
│       ├── engine.ts
│       └── index.ts
│
├── features/
│   └── lydianChromatic/
│       ├── LydianChromaticSection.tsx
│       ├── ChordTargetSelector.tsx
│       ├── TargetPanel.tsx
│       ├── ParentScalePanel.tsx
│       ├── LydianScaleOrderPanel.tsx
│       └── index.ts

Optional, depending on the current repo structure:

src/components/controls/EnharmonicNoteSelector.tsx

Only extract a shared enharmonic selector if it can be done safely without breaking the existing TonicSelector.

3. Important implementation principles

  1. Keep theory pure.
    src/theory/lydianChromatic/engine.ts should have no React imports.

  2. Keep teacher-specific mappings editable.
    Chord → target → parent scale → scale order data should live in a data file, not inside components.

  3. Do not assume the mappings are final.
    The first version can use seed data, but the code should make it easy to adjust the mappings based on the professor's explanation.

  4. Do not break the existing app.
    Preserve current behavior for scale cards, harmonic field, modes, comparison, audio playback, localStorage, and i18n.

  5. Inspect the real repo before editing.
    Do not guess where TabId, tabs, i18n, localStorage, or CSS tokens live.

  6. Match the existing i18n format exactly.
    If the current t() helper does not support nested objects, use flat locale keys instead of nested objects.

  7. Reuse UI patterns carefully.
    The new tab should visually match the current app, especially the enharmonic note button pattern.

4. Suggested agent workflow

Option A — Quality-first workflow

Use a strong model, such as Sonnet or an equivalent coding model, for the full implementation.

Best when:

  • You want fewer back-and-forth corrections.
  • The repo structure is not fully known.
  • You want the model to inspect, implement, build, and self-review in one pass.

Recommended sequence:

1. Strong model: inspect repo + implement vertical slice.
2. Strong model or small model: run build/lint and summarize changed files.
3. Strong model: fix any build/lint issues.

Option B — Cost-saving workflow

Use small models for safe, narrow tasks and a strong model for the main implementation.

Recommended split:

Small model 1 — Repo inspection only
- Find TabId definition.
- Find tab rendering.
- Find i18n locale structure.
- Find TonicSelector and note-button/enharmonic logic.
- Find current CSS token patterns.
- Produce a file map only. Do not edit files.

Strong model — Main implementation
- Use the file map.
- Implement the new theory module.
- Implement the new feature components.
- Add the new tab.
- Add i18n labels.
- Preserve existing behavior.
- Run build/lint.

Small model 2 — QA review
- Review the diff.
- Check if the feature is isolated.
- Check if theory is pure.
- Check if i18n matches the current helper.
- Check if any unrelated files were changed.

Recommended practical choice

For this task, it is acceptable to use only Sonnet or another strong coding model. The feature touches architecture, React, TypeScript, i18n, styling, and music-theory data. A small model can help with inspection, but the implementation should be done by a stronger model if quality matters more than saving tokens.

Canonical implementation prompt

Use this prompt with the coding agent.

You are working in the `music-study` repository.

Task:
Add a first vertical slice of a new `Lídio Cromático / Lydian Chromatic` study tab.

Context:
The app currently studies four parent scales, their modes, harmonic fields, arpeggios, and comparisons. This is useful, but it does not yet support the class workflow for the Lydian Chromatic Concept.

The desired workflow is:

chord quality → target/alvo → parent scale/escala-mãe → ordered scale options → improvisation exercise

This feature must be treated as a separate study mode, not as another option inside the existing four-scale selector.

Important:
The Lydian Chromatic material is teacher-specific study content. Do not present the seed mappings as final universal truth. Keep the data editable and centralized so the teacher's mappings can be adjusted later without touching component code.

Before implementing:
1. Inspect the actual repository structure.
2. Locate the real files that define or control:
   - `TabId`
   - tab rendering
   - active tab state
   - localStorage tab/state behavior, if any
   - i18n locale structure
   - `TonicSelector` usage
   - existing note/enharmonic UI pattern
   - existing CSS/token patterns
3. Do not guess file paths.
4. Do not create duplicate UI helpers if an existing component can be reused safely.
5. If `TonicSelector` is coupled to `useScaleEngine`, either:
   - extract only the reusable enharmonic note-button UI into a shared component, if low risk; or
   - create a local selector for the new feature, but keep it clearly scoped and visually consistent.
6. Do not assume nested i18n keys work. Match the current i18n format exactly.
7. Keep imports relative, consistent with the existing project style.

Expected implementation:

1. Add the new tab:
   - Update the `TabId` type to include `lydianChromatic`.
   - Add localized tab labels:
     - pt-BR: `Lídio Cromático`
     - en: `Lydian Chromatic`
   - Render the new tab alongside the existing tabs.
   - Add the new tab content branch without changing existing tab behavior.

2. Create a dedicated theory module:
   Add:
   - `src/theory/lydianChromatic/types.ts`
   - `src/theory/lydianChromatic/data.ts`
   - `src/theory/lydianChromatic/engine.ts`
   - `src/theory/lydianChromatic/index.ts`

   Define types similar to:

   - `LydianChromaticChordId`
   - `LydianChromaticScaleId`
   - `LydianChromaticChordMapping`
   - `LydianChromaticScaleDef`
   - `LydianChromaticResult`
   - `LydianChromaticScaleOption`

   The data file should contain editable seed mappings for chord qualities such as:

   - `Xmaj7`
   - `Xmaj7#11`
   - `X7`
   - `X7#11`
   - `X7alt`
   - `Xm7`
   - `Xm6`
   - `Xm7b5`
   - `Xdim`
   - `Xsus4`
   - `Xsus4(b9)`

   Each chord mapping should include:

   - display symbol
   - target/alvo degree
   - target interval in semitones
   - parent scale id
   - ordered scale options from lower tension to higher tension

3. Create a pure computation function:

   Implement:

   `computeLydianChromaticSelection({ root, chordId })`

   It should return:

   - `root`
   - `chordId`
   - `chordSymbol`
   - `chordTarget` or equivalent target label
   - `targetDegree`
   - `targetNote`
   - `parentScale`
   - `parentScaleNotes`
   - `orderedScaleOptions`

   Requirements:

   - No React imports.
   - No browser APIs.
   - No localStorage.
   - Pure deterministic function.
   - Build notes from intervals.
   - Respect the selected root's accidental style where possible: flat roots should prefer flat spellings, sharp/natural roots should prefer sharp spellings.

4. Add feature components:

   Add a feature folder such as:

   `src/features/lydianChromatic/`

   Include components equivalent to:

   - `LydianChromaticSection.tsx`
   - `ChordTargetSelector.tsx`
   - `TargetPanel.tsx`
   - `ParentScalePanel.tsx`
   - `LydianScaleOrderPanel.tsx`
   - `index.ts`

   The UI should include:

   - Root selector
   - Chord target buttons using generic `X` symbols, for example `Xmaj7`, `X7`, `Xm7b5`
   - Concrete chord display, for example `C7`, `Dbmaj7`, etc.
   - Target/alvo display
   - Parent scale/escala-mãe panel
   - Ordered scale options panel
   - Short improvisation exercise prompt

5. Keep theory copy centralized:

   Add stable i18n keys or centralized data-driven labels.

   Required labels:

   pt-BR:
   - `Lídio Cromático`
   - `Tônica`
   - `Tipo de acorde`
   - `Alvo de improvisação`
   - `Escala-mãe`
   - `Opções de escala`
   - `Tensão`
   - `Exercício`

   en:
   - `Lydian Chromatic`
   - `Tonic`
   - `Chord type`
   - `Improvisation target`
   - `Parent scale`
   - `Scale options`
   - `Tension`
   - `Exercise`

   Match the existing locale file style exactly.

6. Styling:

   - Reuse current UI patterns and CSS tokens.
   - Do not introduce a new design system.
   - Do not redesign the full app.
   - Keep the new feature visually aligned with existing controls and cards.
   - Avoid global CSS side effects.

7. Preserve existing behavior:

   Do not break:

   - scale cards
   - harmonic field
   - modes
   - comparison view
   - audio playback
   - localStorage
   - existing tonic/scale selection behavior
   - existing i18n behavior

Validation:

Run:

- `npm run build`
- `npm run lint`

If either fails, fix the errors unless they are pre-existing and unrelated. If errors are pre-existing, report them clearly.

Manual smoke tests:

1. Open the app.
2. Confirm existing tabs still work.
3. Open the new `Lídio Cromático` tab.
4. Select `C` as root and `X7` as chord type.
5. Confirm the UI shows a concrete chord like `C7`.
6. Confirm it shows an alvo/target note.
7. Confirm it shows a parent scale.
8. Confirm it shows ordered scale options.
9. Select a flat root such as `Db` and confirm note spelling prefers flats.
10. Reload the app and confirm no localStorage or tab behavior is broken.

Final response format:

Report:

1. Files changed
2. What was implemented
3. Any seed theory mappings added
4. Any assumptions made
5. Build result
6. Lint result
7. Anything intentionally left for later

Do not include unrelated refactors.
Do not change package dependencies unless absolutely necessary.
Do not modify contract, API, audio engine, or existing scale-engine logic except for safe integration points needed to add the tab.

Small model prompt — repo inspection only

Use this if you want to save tokens before sending the main implementation to a stronger model.

You are working in the `music-study` repository.

Your task is inspection only. Do not edit files.

Find the exact files and code locations related to adding a new tab called `lydianChromatic`.

Inspect and report:

1. Where `TabId` is defined.
2. Where tabs are rendered.
3. Where active tab state is stored.
4. Whether tab state is persisted in localStorage.
5. Where i18n locale strings live.
6. Whether the i18n helper supports nested keys or only flat keys.
7. Where `TonicSelector` is defined.
8. Whether `TonicSelector` can be reused outside the current scale engine.
9. Existing CSS/token patterns used by cards, controls, buttons, and note pills.
10. Recommended exact files to change for the Lydian Chromatic tab.

Output format:

- File map
- Relevant snippets or line references
- Reuse recommendation for the note/enharmonic selector
- Risks
- Suggested implementation order

Do not implement anything.

Strong model prompt — implementation using inspection report

Use this after the small model has produced the file map.

You are working in the `music-study` repository.

Use the inspection report from the previous agent as the source of truth for file locations.

Implement the first vertical slice of the `Lídio Cromático / Lydian Chromatic` tab.

Requirements:

1. Add `lydianChromatic` to the real tab type/state system.
2. Add localized labels using the repo's existing i18n format.
3. Add a pure theory module under `src/theory/lydianChromatic/`.
4. Add a feature UI folder under `src/features/lydianChromatic/` or the closest existing feature convention.
5. Implement `computeLydianChromaticSelection({ root, chordId })` as a pure function.
6. Include editable seed mappings for:
   - Xmaj7
   - Xmaj7#11
   - X7
   - X7#11
   - X7alt
   - Xm7
   - Xm6
   - Xm7b5
   - Xdim
   - Xsus4
   - Xsus4(b9)
7. Reuse or safely mirror the existing enharmonic note selector pattern.
8. Add root selector, chord selector, target panel, parent scale panel, ordered scale panel, and exercise prompt.
9. Preserve all existing behavior.
10. Run `npm run build` and `npm run lint`.

Do not do unrelated refactors.
Do not add dependencies.
Do not redesign the app.
Do not alter existing music-theory behavior except for safe integration needed to add the new tab.

At the end, report files changed, build result, lint result, and any assumptions.

Small model prompt — QA review

Use this after implementation.

You are reviewing a completed implementation in the `music-study` repository.

Task being reviewed:
Add a first vertical slice of a new `Lídio Cromático / Lydian Chromatic` tab.

Review only. Do not edit files unless explicitly asked later.

Check:

1. Did the implementation add a new tab without breaking existing tabs?
2. Is `lydianChromatic` added to the real `TabId` system?
3. Is the theory layer pure, with no React/browser/localStorage imports?
4. Are chord mappings centralized in a data file?
5. Is the UI separated into feature components?
6. Does i18n match the repo's existing format?
7. Was the existing enharmonic note selector reused or mirrored safely?
8. Are existing scale cards, harmonic field, modes, comparison, audio playback, and localStorage untouched?
9. Did the implementation avoid unrelated refactors?
10. Do `npm run build` and `npm run lint` pass?

Also manually inspect the behavior for:

- C + X7
- Db + Xmaj7
- G + Xsus4(b9)
- Xm7b5 with a flat root

Output:

- Pass/fail checklist
- Bugs found
- Risky assumptions
- Suggested minimal fixes

5. Acceptance criteria

The task is complete when:

  • A new Lídio Cromático / Lydian Chromatic tab exists.
  • The new tab does not interfere with existing study modes.
  • Selecting a root and chord type produces a concrete chord symbol.
  • The UI shows the target/alvo degree and note.
  • The UI shows the parent scale/escala-mãe.
  • The UI shows ordered scale options from lower to higher tension.
  • The seed mappings are centralized and easy to edit.
  • Theory computation is pure and testable.
  • i18n labels are centralized.
  • Existing audio and scale features still work.
  • npm run build passes.
  • npm run lint passes or only reports clearly identified pre-existing unrelated issues.

6. Suggested first musical seed data

These mappings are only a starting point. They should be reviewed against the professor's explanation.

Xmaj7      → alvo: 7ª      → parent: Lydian
Xmaj7#11   → alvo: #11     → parent: Lydian
X7         → alvo: 4ªJ     → parent: Lydian Dominant
X7#11      → alvo: #11     → parent: Lydian Dominant
X7alt      → alvo: b5/#11  → parent: Auxiliary Diminished or Altered seed
Xm7        → alvo: b3      → parent: Dorian seed
Xm6        → alvo: 6       → parent: minor-related seed
Xm7b5      → alvo: b5      → parent: locrian/minor-related seed
Xdim       → alvo: b3/b5   → parent: diminished seed
Xsus4      → alvo: 4ªJ     → parent: mixolydian/sus seed
Xsus4(b9)  → alvo: 4ªJ/b9  → parent: phrygian/sus seed

Important: because this app is meant to follow the professor's explanation, these should stay clearly editable and should not be hard-coded into JSX.

7. Risks

Risk 1 — Generic implementation that does not fit the repo

The previous version of the prompt was good, but it allowed phrases like “wherever TabId is defined.” That can make weaker models generate plausible but non-integrated code.

Mitigation:

  • Force repo inspection first.
  • Require exact files changed.
  • Require build/lint.

Risk 2 — Duplicating note selector logic

The current app already has an enharmonic UI solution in TonicSelector. Copying that logic can create drift.

Mitigation:

  • Reuse if safe.
  • Extract a small shared note selector if low risk.
  • Only duplicate locally if the current component is too coupled.

Risk 3 — Incorrect i18n shape

If the app's t() helper only supports flat keys, nested locale objects will break.

Mitigation:

  • Inspect the existing i18n implementation first.
  • Match the current format exactly.

Risk 4 — Treating seed music theory as final

The Lydian Chromatic Concept has multiple interpretations and the app should follow the professor's explanation.

Mitigation:

  • Mark mappings as editable seed data.
  • Keep data centralized.
  • Avoid definitive language in UI copy.

8. Final recommendation

This is a good task for testing a new coding model because it checks several important abilities:

  • understanding an existing repo;
  • adding a new feature without breaking old behavior;
  • separating theory/data/engine from React UI;
  • respecting i18n and styling patterns;
  • handling music-theory data carefully;
  • validating with build and lint.

For best quality, use a strong model for the main implementation. Smaller models can help with repo inspection and QA review, but the actual implementation should probably be handled by Sonnet or another strong coding model.