Published as prior art by Collin Wade · April 22, 2026

The Adaptive Chord Training Method: Design, Algorithms, and Pedagogical Decisions Behind Adaptive Harmony

Author: Collin Wade, Founder, Adaptive Harmony Published: April 22, 2026 Location: adaptiveharmony.com (official publication) Purpose: This document publicly discloses the design decisions, algorithms, learning-science methods, and user-experience inventions behind Adaptive Harmony. It is published as a technical reference for music educators, piano students, and developers interested in adaptive music pedagogy. By publishing this material publicly with a verifiable date, it becomes prior art — freely usable by anyone building on these ideas, and not patentable by any third party.

Why I am publishing this

Adaptive Harmony is a chord-training application for piano students. It uses spaced repetition, mastery-gated progression, and MIDI-verified chord input to help learners build harmonic fluency across 111 levels spanning Western classical and popular chord vocabulary.

Many of the specific design decisions, algorithms, and user-experience patterns built into the app are, to my knowledge, not published elsewhere in integrated form. Some are straightforward applications of well-known cognitive-science principles (Leitner spaced repetition, working-memory chunking). Others are novel combinations I have developed through iteration and teacher feedback during the build process.

I am publishing the full design in detail — including algorithms, tuning parameters, UX flows, and pedagogical rationale — for three reasons:

To share useful ideas with music educators and app developers. Adaptive chord pedagogy is underdeveloped. The more people experimenting with it, the better for piano learners as a whole.
To make the specific methods prior art. Once published here with a verifiable date, no one can later patent these methods in a way that would block others from using them. This includes me — I am not claiming patent rights over what follows. I am making a choice to keep this open.
To document my own invention timeline. This post, timestamped on my blog and archived in the Internet Archive’s Wayback Machine, establishes the date on which these specific combinations of ideas were documented publicly.

What follows is the full technical detail. It is long and specific on purpose. Vague descriptions do not establish prior art; precise ones do.

Part 1: The Core Learning Architecture

1.1 The Hierarchy

Adaptive Harmony’s curriculum is organized into 111 levels across 5 phases:

Phase 1 (Triads): Major, minor, diminished, augmented triads with inversions
Phase 2 (Sevenths): Major 7, dominant 7, minor 7, half-diminished, fully diminished, minor-major 7
Phase 3 (Sus and 6th chords): Sus2, sus4, 6, m6, 6/9
Phase 4 (Extensions): 9ths, 11ths, 13ths, with omission rules
Phase 5 (Altered): Dominant 7 with b5, #5, b9, #9, #11, b13

Each level teaches one new concept. Levels are grouped into milestones (groups of related levels that together complete a pedagogical unit, e.g. “all major triad inversions across keys 1a”). Milestones are exposed to users in the Guided+ mode for starting-level selection.

1.2 Key Groupings (Circle of Fifths, Option B)

Keys are introduced in this order, chosen to follow the circle of fifths while pairing each major key with its relative minor:

Group 1a: C major / A minor, G major / E minor
Group 1b: D major / B minor, A major / F# minor
Group 2: F major / D minor, Bb major / G minor, Eb major / C minor
Group 3: E major / C# minor, B major / G# minor, F# major / C# minor
Group 4: Ab major / F minor, Db major / Bb minor

This grouping keeps related keys together (sharing enharmonic equivalents, parallel fingering patterns) and progressively expands the accidentals the learner must read. Many existing piano methods introduce keys by sharp count alone; this grouping additionally respects relative-minor pairing, which matches how piano repertoire is actually composed.

1.3 Three-Item Chunks for Beginners

New concepts are introduced three at a time, never more. This is a direct application of working-memory research (Cowan 2001: the effective capacity of working memory is approximately 3-4 chunks, not the older 7±2 estimate). For the absolute beginner, three new chord identities is the maximum that can be encoded without loss during a single study session.

After three chunks are introduced and each shows initial mastery (not final mastery — just “correct at least twice”), a new batch of three is added.

1.4 One New Dimension at a Time

A “dimension” in this system means any of: chord quality (major/minor/etc.), inversion, key, voicing depth (triad vs 7th vs 9th), or hand (LH/RH/both). When introducing a new chord type, the learner holds every other dimension constant.

For example, when introducing the minor 7 chord, the user first practices only C minor 7 in root position with both hands. Once that is stable, the user practices C minor 7 in first inversion — same chord, new inversion. Only after all inversions of C minor 7 are stable does the learner move to a new key’s minor 7 chord (A minor 7 in root position).

This “isolation-before-combination” principle is what drives the 111-level count. Most existing piano methods combine dimensions much earlier, which is faster to ship but demonstrably harder for learners.

Part 2: The Leitner Variant

2.1 Seven-Box Leitner with Specific Intervals

Adaptive Harmony uses a Leitner spaced-repetition system with seven boxes and the following review intervals (in days):

Box 0: 0 days (due immediately next session)
Box 1: 1 day
Box 2: 3 days
Box 3: 7 days
Box 4: 16 days
Box 5: 35 days
Box 6: 75 days

These intervals approximate the SuperMemo-derived forgetting curve compressed for musical skills (motor-plus-recognition) rather than declarative knowledge (vocabulary flashcards). The gap ratio between consecutive boxes is roughly 2.0-2.5x, with a slight expansion at higher boxes. Chords in Box 6 are considered mastered long-term; they still rotate in but rarely.

Box transition rules:

First-attempt correct: chord advances one box.
First-attempt incorrect: chord drops to Box 0 regardless of current box (the punishment is severe on purpose — reflects that error during performance is expensive).
Partial credit (correct on second or later attempt): chord stays in current box.

2.2 Minimum Pool Size of Six

Leitner systems with small pools are unstable: if you have three cards in Box 0, you practice the same three cards every session. That produces rote memorization, not recognition. To prevent this, Adaptive Harmony enforces a minimum practice pool of six chords per session. If fewer than six chords are “due” according to Leitner scheduling, the system pulls forward chords from higher boxes (those closest to their due dates) to reach six.

This prevents the degenerate case and forces variety even in early levels.

2.3 Maximum Rotation of Fifteen

Conversely, large pools are overwhelming. If a learner has 40 chords due in one session, practice becomes exhausting and accuracy collapses. Adaptive Harmony enforces a maximum practice rotation of fifteen chords per session. If more than fifteen are due, the system presents the fifteen most-overdue first and marks the remainder as due next session.

The 15-chord ceiling was chosen based on the observation (from beta testing) that practice sessions above ~15 chords degrade in accuracy and subjective engagement.

2.4 Cumulative Review (No Practice Scope Toggle)

Unlike some spaced-repetition apps, Adaptive Harmony does not offer a “practice only this level” toggle. Once a level is unlocked, its chords enter the global Leitner pool. During any practice session, the user may see chords from any unlocked level that are due for review. This prevents the common anti-pattern where learners “finish” Level 1 then forget it entirely while working on Level 5.

This design decision comes with a cost: users sometimes complain that “I’m on Level 10 but I keep seeing Level 2 chords.” The design treats this as a feature, not a bug. Practice scope toggles exist in many competitor apps; Adaptive Harmony intentionally omits one.

2.5 Weighting Toward Recent Mistakes

Within the pool of “due” chords, selection is not uniform random. Chords are selected by weighted random draw where weight is a function of:

How recently the chord was missed (recent misses weighted higher)
How many times the chord has been missed cumulatively (chronic misses weighted higher)
How long since the chord was last practiced (older misses weighted higher)

Formal weight calculation:

weight = (1 + recent_miss_count) × (1 + cumulative_miss_rate × 3) × min(5, days_since_last_practice)

This favors chords the user struggles with while still providing variety.

Part 3: Chord-Specific Design Decisions

3.1 Shell Voicing Rules for Seventh Chords

A “shell voicing” of a seventh chord omits the fifth. For example, a C major 7 shell is C-E-B (root, third, seventh) — the G is omitted. This is standard jazz pedagogy for LH voicings in comping.

Adaptive Harmony’s rule: shell voicings are acceptable only for seventh chords in root position. All inversions of seventh chords require the full four-note voicing.

The rationale:

In root position, the shell makes intuitive sense: the bass establishes the root, the 3rd and 7th establish the quality, the 5th is the most expendable note.
In inversions, removing the 5th corrupts the inversion’s identity. A first-inversion C7 is E-G-Bb-C; removing the G produces E-Bb-C which is a half-diminished rather than a clear first inversion.

This is a pedagogical choice to enforce harmonic literacy in inversions rather than allowing learners to “get away with” shell voicings they couldn’t defend theoretically.

3.2 Extended Chord Omission Rules

Extended chords (9ths, 11ths, 13ths) are large — too large for most hands. Adaptive Harmony’s rules for which notes may be omitted:

Extension	Always omittable	Conditionally omittable	Never omittable
9th (1-3-5-7-9)	5	7 (if context clear)	1, 3, 9
11th (1-3-5-7-9-11)	5, 9	7 (if context clear)	1, 3, 11
13th (1-3-5-7-9-11-13)	5, 9, 11	7 (if context clear)	1, 3, 13
Dominant 13	5, 11	9	1, 3, 7, 13

The logic: the 3rd and the highest extension (the “identity note”) are never omittable because they establish the chord’s quality. The 7th is almost always present for tension. The 5th is the most expendable because it is usually implied by the rest of the chord or the bass.

Dominant 13th is the exception because the 7 (flat seventh) and 13 both carry dominant tension — both are required. The 11 is typically avoided on dominant chords because it clashes with the 3rd.

This validation logic runs client-side during chord checking. A user playing a voicing that omits an “always omittable” note is marked correct. A voicing that omits a “never omittable” note is marked incorrect with a specific hint explaining which note is missing.

3.3 Fully Diminished Chords Have No Inversions

The fully diminished seventh chord (e.g. C-Eb-Gb-Bbb) is a stack of three minor thirds. All of its “inversions” are enharmonically equivalent to other fully diminished chords (C dim7 first inversion = Eb dim7 root position).

Most piano methods treat all four rotations of dim7 as separate chord inversions. Adaptive Harmony treats fully diminished as a single chord with no distinct inversions. A user is marked correct for any of the four rotations.

This avoids busywork (teaching four “inversions” that sound identical) and reflects how fully diminished is used in practice (as a pivot chord with ambiguous root).

3.4 Inversion Notation: Color-Coded + Slash + Figured Bass

When a chord appears in an inversion, Adaptive Harmony displays it three ways simultaneously:

Color-coded chord symbol — the inversion bass note is highlighted in a distinct color
Slash notation — e.g. “C/E” for first inversion C major
Figured bass notation — e.g. “C⁶” for first inversion, “C⁶₄” for second inversion

Why all three: different learners have different notation fluency. Classical students are fluent in figured bass; jazz students in slash chords; beginners in color coding. By showing all three, we help each student learn the others from context.

3.5 Enharmonic Display Rules

Chord symbol display follows these rules:

Sharps are preferred for the keys C, G, D, A, E, B, F#
Flats are preferred for F, Bb, Eb, Ab, Db
Within a progression, stay in the home key’s accidental system (no mixing sharps and flats except when modulating)
For borrowed chords, use the accidental of the borrowed-from key (e.g. in C major, borrowed iv is notated F minor — not E# minor)

These rules are standard music-theory conventions but worth making explicit for automated display logic.

Part 4: The Guided+ Starting Level Selector

4.1 The Problem

Adaptive practice apps typically force new users through an assessment quiz before starting, or start everyone at Level 1. Both are hostile to intermediate users. A returning intermediate pianist does not want to drill C major triads for three sessions before reaching anything challenging.

4.2 The Solution: Milestone-Granularity Starting Point Selection

The Guided+ mode lets users choose their starting level at milestone granularity — not at any level, but at any milestone (a grouping of ~3-7 related levels that together complete a unit).

The flow:

User selects “Guided+” from the mode toggle
The milestone list is displayed: e.g. “M1: Major triads root position, all keys 1a” / “M2: Major triads all inversions, all keys 1a” / “M3: Minor triads…” / etc.
User taps a milestone to select their starting point
A confirmation screen appears: “Start at [Milestone Name]? You’ll skip [N] earlier milestones. You can still access those later from the progress screen.”
On confirming, the user’s level-progress record for skipped levels is created with a mastery-sessions count of 3 (equivalent to “tested out”) but first-attempt-accuracy set to null (distinguishing “skipped” from “actually mastered”).
Skipped levels appear differently in the progress screen, with a “review this level” action available.

Why milestone granularity and not free level choice:

Level granularity would overwhelm users with 111 options.
Phase granularity would be too coarse (a phase has 20+ levels).
Milestones are a natural middle ground — approximately 25-30 milestones across 111 levels.

Why the confirmation screen:

Prevents accidental skips.
Sets clear expectation that earlier content is still available.
Distinguishes skipping from hiding.

4.3 Beta Ref Tracking Through Password Screen

For beta testers enrolling via a referral link (for example, a URL containing ?ref=sarah-roeber), the ref parameter must persist through the password entry screen (since the app is password-protected during beta). Implementation:

On initial load, if the URL contains a ref parameter, write it to localStorage under the key beta_ref.
The password screen does not inspect or modify beta_ref.
After successful password entry, the main app reads beta_ref and applies the beta flag during signup.

This pattern (ref-persisted-through-gate) is useful wherever signup happens after an intermediate step.

Part 5: Forced Rest Breaks

5.1 The Break Trigger

Adaptive Harmony forces a rest break based on two conditions (whichever fires first):

Time trigger: 12 continuous minutes of practice
Struggle trigger: three consecutive incorrect chord answers

On trigger, the practice view locks; a “rest break” screen appears with a short encouraging message, a 90-second countdown, and an option to practice deep breathing exercises.

5.2 Why 12 Minutes

Research on motor-skill acquisition (e.g., Censor et al. 2012) shows that consolidation occurs in the minutes immediately following practice. Continuous practice beyond ~10-15 minutes without consolidation produces diminishing returns; errors compound. Twelve minutes is chosen as a mid-range value.

5.3 Why Three Consecutive Errors

Three in a row is a reliable signal of either fatigue or frustration. One error is random. Two is suspicious. Three means the user is no longer learning.

5.4 Break Timer Reset on Inactivity

If a user walks away from the app mid-session (tab backgrounded, no MIDI input for 60+ seconds), the 12-minute practice timer resets when they return. This prevents the irritation of “I just came back from my bathroom break and now the app is forcing a break?”

5.5 Critical Design: Break is Unskippable

The break cannot be dismissed. This is intentional. An optional break is ignored by users who need it most. The 90-second forced pause is the whole point.

Part 6: First-Attempt Accuracy as the Only Metric

Most music-practice apps show “accuracy” as a single number that includes retries. This inflates the metric and hides struggle. If a user plays a chord wrong three times before getting it right, their accuracy is recorded as 100% because they eventually got it.

Adaptive Harmony tracks and displays first-attempt accuracy only. A chord is either correct on the first try or not. Subsequent retries are available for learning but are not counted toward accuracy statistics.

This matters for three reasons:

Honest self-knowledge: users see their actual recognition speed, not a padded score.
Meaningful progression criteria: the 3x mastery gate (below) requires ≥85% first-attempt accuracy. This is an achievable bar for mastered content and an honest one for not-yet-mastered content.
Leitner integrity: box transitions require first-attempt success. A user who “gets there eventually” stays in the same box — correctly reflecting that recognition is not fluent yet.

Part 7: The Three-Session Mastery Gate

7.1 The Criterion

A learner unlocks a new level when they have completed three separate practice sessions on the current level, each meeting these requirements:

At least 20 chords attempted in the session
First-attempt accuracy ≥ 85%
Sessions span at least 48 hours total (from first qualifying session to third)

All three must be met. Speedrunning is prevented by requirement #3.

7.2 Why “Three Sessions Across 48 Hours”

Single-session mastery is illusory; anyone can perform well once. The combination of three sessions and two days enforces that learning has consolidated through sleep cycles. This is a well-documented finding in motor-skill literature (Walker 2005 on sleep-dependent motor learning).

7.3 Why 85% and Not 100%

Perfection is not the right bar for moving on. Learners who achieve 100% on a level are often overpracticing to avoid the anxiety of moving forward. 85% is high enough to indicate fluency and low enough to avoid perfectionist stalls.

7.4 Why 20 Chords Minimum

Fewer than 20 chords produces unreliable accuracy statistics (small-sample noise). Twenty is the minimum for a ~±5% confidence interval on accuracy at the 85% level.

7.5 Critical: Gate Runs Server-Side

For monetized tiers, the mastery gate runs on the server, not the client. The client can display estimated progress (“1 of 3 mastery sessions complete”), but unlocking the next level requires a server-side authorization function to return true. This prevents determined users from bypassing the paywall by modifying client JavaScript.

Part 8: Pro Mode Self-Selection

8.1 The Problem

Some experienced pianists rightly resent being forced through a guided curriculum. They already know major triads in root position; they want to jump straight to altered dominants.

8.2 The Solution: Three Modes

Adaptive Harmony offers three modes:

Guided: automatic progression through 111 levels, one at a time
Guided+: user selects starting milestone; otherwise guided from there
Pro: user picks any chord from any level at any time; no progression, no gate; practice what you want

Pro mode is NOT gated or paywalled — it’s available to all users. The rationale: Pro users are a distinct audience. Forcing them through the guided path loses them. Giving them Pro mode keeps them engaged with the app even though they’re getting less structured benefit.

The adaptive algorithm still runs in Pro mode (Leitner boxes are maintained for any chords the user practices), but no level unlocks happen and no mastery gates are enforced.

8.3 Guided+ vs Pro: When Each Fits

Guided+: intermediate learners who want structure but want to skip the easy material
Pro: advanced learners who already have a fluent harmonic vocabulary and want the app purely as a practice surface

Many apps force a single progression mode. Three modes was chosen specifically to respect the three distinct user archetypes this app serves.

Part 9: The Optional-Level System

9.1 What Optional Levels Are

Among the 111 levels, some are flagged as optional. An optional level is one that teaches useful content but is not required for progression to the next phase. Examples:

Advanced altered dominant voicings (Phase 5) — optional because most players won’t encounter them outside jazz contexts
Minor-major 7 chords — taught but marked optional because they’re rare in common-practice repertoire

9.2 Default Behavior

By default, optional levels are excluded from the normal progression path. A user in Guided mode moves from one required level to the next required level without encountering optional levels.

9.3 Opt-In for Optional Levels

Users can opt in to including optional levels at the phase level (e.g. “include all optional Phase 4 extensions”). Once opted in, optional levels appear in progression normally.

9.4 Why This Design

Surveys of piano teachers showed repeated frustration with methods that either (a) force every student through esoteric content or (b) hide it entirely so motivated students never find it. The default-excluded / opt-in-available pattern lets most users have a clean progression while giving motivated users the full depth.

Part 10: The Diagnostic Mode (Future)

Planned for post-Batch-D: a diagnostic assessment that lets a new user take a 15-minute quiz covering chord recognition across all five phases. Results place them at the appropriate milestone automatically, without requiring them to self-identify their level.

Key design decisions already locked in:

Diagnostic uses adaptive item selection (like the GRE) — early questions calibrate, later questions probe specific weaknesses
Results include confidence intervals, not just a placement level
Users always retain the option to override the diagnostic’s recommendation (and go higher or lower)
Diagnostic is optional, never required — forcing a test is hostile

Documenting this here establishes the design date for adaptive-item-selection diagnostics in chord recognition specifically. The general technique is well-known; the specific application to chord pedagogy with adaptive item selection for placement is being made prior art here.

Part 11: Gamification Scoring (In Progress)

Partially implemented at the time of this writing; key design decisions documented here.

11.1 Two-Scale Scoring Problem

A design challenge unique to this app: users who play via MIDI versus virtual keyboard have fundamentally different input bandwidth. A MIDI user can play a chord in 50ms; a virtual keyboard user takes several seconds to click four notes sequentially.

Scoring both on the same scale is unfair either direction:

Use a time-based score → virtual keyboard users always lose
Use an accuracy-only score → MIDI users are penalized for the speed advantage they have over a virtual-keyboard learner of the same skill

11.2 The Dual-Scale Solution

Score on two separate scales:

MIDI score: accuracy × speed factor (bonus for fast correct chords)
Virtual keyboard score: accuracy × completion factor (bonus for finishing sessions, no speed component)

Display both separately. A user playing via MIDI sees their MIDI leaderboard position; a virtual keyboard user sees a virtual keyboard leaderboard.

This avoids the common gamification failure where one input method dominates all leaderboards.

11.3 “Honest” Scoring Principle

No scoring component rewards anti-learning behavior. Specifically:

No “streak” bonus that penalizes taking necessary breaks
No XP for practicing already-mastered content (users can do so but get no score)
No daily-login bonus that coerces meaningless sessions

Gamification exists to make practice engaging, not to farm metrics.

Part 12: The “Hint Escalation” System

When a user plays a chord incorrectly, hints escalate rather than revealing the answer:

First miss: shown the chord symbol more prominently (maybe the user misread it)
Second miss: shown the scale-degree formula (e.g. “1-b3-5-b7” for minor 7)
Third miss: chord played audibly + keyboard visualization + text description

Importantly, the keyboard visualization + audio + text appears only on the third miss — not on the first or second. Too-eager hint display is a common failure mode in music practice apps; it trains users to fail-and-wait instead of think-and-try.

After three misses, the user moves on to the next chord (the failed chord is logged for Leitner purposes — dropped to Box 0 — but not repeated immediately to avoid compounding frustration).

Part 13: Regional Curriculum Packs (Future)

Documented here to establish design date. Post-Batch-D, Adaptive Harmony plans to ship region-specific chord progression packs. Specifically:

13.1 East Asian Pop Pack

A unified content pack covering:

Japanese Royal Road (IV-V-iii-vi / 4536) progressions and their extended 4536251 variants
Komuro 6451 (vi-IV-V-I) Japanese pop progression
K-pop 2010s loop (I-III-vi-IV), 2020s loop (II-V-I-VI), ballad loop (IV-II-III-vi)
K-pop voicing ladder — systematic progression from triad → add 7ths → add 9ths → add slash chords → add sus4, demonstrating how K-pop transforms simple diatonic progressions into emotional texture
C-pop I-V-vi-V loop (Mandopop variant of the Western Axis progression)
Chinese pentatonic melodic layer module — teaching learners to compose or improvise melodies on the gong-shang-jue-zhi-yu pentatonic while harmonizing with Western chord progressions, avoiding scale degrees 4 and 7

13.2 Why This Combination is Novel

No existing adaptive chord-training app offers region-specific pop curriculum integrated with spaced-repetition progression. Most music-theory apps treat Western classical/pop as the universal default. This design decision — that regional curricular content is a first-class feature of the app, not a localization afterthought — is documented here as of April 22, 2026.

Part 13.5: Common Chord Progression Training as a Standalone Module (Planned)

A planned future module will teach common chord progressions as a primary unit of practice rather than individual chords. Specifically, the same Leitner-variant spacing logic documented in Part 2 will be applied to progressions as the practice unit rather than to isolated chord identities.

13.5.1 Design Specifics

The practice item is a full progression (e.g., I–V–vi–IV, ii–V–I, I–IV–V–I, 12-bar blues, Canon in D, I–vi–IV–V 1950s progression, Royal Road 4536, etc.), not an individual chord.
Each progression carries its own Leitner box state per user, with the same seven-box intervals (0, 1, 3, 7, 16, 35, 75 days) and the same box-transition rules (first-attempt correct advances one box; first-attempt incorrect drops to Box 0 regardless of current box).
Minimum practice pool of 6 progressions per session; maximum rotation of 15 per session; same cumulative-review principle that prevents scope toggles.
Progressions tagged by genre (pop, jazz standards, classical cadences, gospel, blues, R&B, neo-soul, East Asian pop) and by key group (using the same Option B circle-of-fifths grouping documented in Part 1.2).
Same isolation-before-combination principle: one new progression introduced at a time, held stable across key transpositions before introducing a new progression.
Same 3x mastery gate (across distinct sessions, 85% first-attempt accuracy, 20-item minimum per session, 48-hour spacing).
Progressions practiced via MIDI input, with validation comparing the user’s played chord sequence to the expected progression sequence. Timing tolerance allows for natural rubato within chord transitions.
Voicing freedom: within a progression, user can play any valid voicing of each chord (shell or full). Shell voicing rules from Part 3.1 still apply.

13.5.2 Why Progression-Level Pedagogy Is Distinct

Most music theory apps either teach chords in isolation (where users can identify individual chords but cannot connect them fluently) or teach songs (where users memorize specific pieces without abstracting the underlying progression). The progression-as-practice-unit approach occupies a third position: general enough to transfer across songs in the same genre, specific enough to build the motor patterns that make real playing feel natural.

13.5.3 Prior Art Declaration

The specific combination — progressions as the Leitner practice unit, with genre tagging, key-group transposition, and the same tuning parameters documented throughout this publication — is documented here as of April 22, 2026. Published as prior art. Anyone may build it. No one may patent it.

Part 14: The Bug Flag Button (Planned)

Planned post-Batch-D UX element: a per-question bug flag button. While practicing, a user who believes a specific chord question is wrong (bad enharmonic display, unclear notation, incorrect expected voicing) can tap a small flag icon. The flag:

Captures the level, chord, user’s current answer, the expected answer, and the time
Creates a bug report in the bug_reports table with full context
Optionally, user can add one line of text

This is designed to surface the long-tail of content bugs that beta testers catch but don’t report because reporting is too friction-heavy.

The specific design — in-context flagging during practice, not a separate “report a bug” form — is what makes this effective. Published here as prior art for in-context music-app bug flagging.

Part 15: Accessibility Design

Features being built in to Adaptive Harmony:

15.1 Staff Notation as Lowest Priority

Staff notation displays the current chord on a grand staff when available. But: staff notation is the lowest-priority display. Users can disable it entirely (and should, if they find it distracting). When enabled, it appears alongside — never instead of — chord symbols and figured bass. This is a pedagogical decision: staff notation is useful to some learners but a barrier to others. It is never the canonical representation; chord symbols + figured bass are.

15.2 Virtual Keyboard Chord Playback

For users without MIDI, the virtual keyboard displays chord notes pressable by clicking. On successful completion, the chord plays audibly through the browser audio API. Audio playback is a requested accessibility feature from beta testers with limited piano experience who want to hear the chord as they play it.

15.3 Color-Coded Inversions

Inversions are color-coded (bass note highlighted distinctly). This serves two purposes: pedagogical (visual cue reinforces which note is the bass) and accessibility (users with less notation fluency get an immediate visual signal).

15.4 Future: Acoustic Input

Planned for Batch I. Uses microphone input to recognize chords played on an acoustic piano (no MIDI required). The architectural decision to prioritize this feature was driven by teacher beta feedback (classical teachers overwhelmingly own acoustic pianos, not MIDI controllers). This is a strategic accessibility feature for the teacher market, not a nice-to-have.

Part 16: User Experience Patterns

16.1 Three-Screen Onboarding Maximum

New users see no more than three onboarding screens before reaching practice. Common anti-pattern: apps that show ten screens of tutorials before letting the user do anything. Adaptive Harmony limits onboarding to:

Choose mode (Guided / Guided+ / Pro)
Connect MIDI or choose virtual keyboard
Start Level 1 (or selected milestone for Guided+)

Anything else can be learned in context.

16.2 Progress Screen is the Home Screen

After onboarding, the home screen shows the user’s progress across all levels, not a marketing page. Pattern logic: users open the app to practice, not to read copy. The progress screen doubles as navigation (tap any unlocked level to practice it) and motivation (visual showing how far they’ve come).

16.3 No Dark Patterns in Paywall

The free-to-paid conversion UX follows these self-imposed rules:

No countdown timers on trial
No fake scarcity (“Only 3 spots left!”)
No hiding the cancel button
No requiring card details without explicit consent
No emails after cancellation trying to win user back more than once
No comparative pricing showing crossed-out “original” prices that were never real

These are not legal requirements (most dark patterns are legal in the US); they are self-imposed constraints reflecting the founder’s values. Published here to make the intent part of the public record.

Part 16.5: Future Directions (Unspecific)

The design patterns documented in this publication are expected to extend over time to additional instruments, additional musical skills, and additional content domains beyond piano chord vocabulary. Specific adaptations will be documented in subsequent defensive publications at the time those designs are finalized.

This section lists the general directions currently under consideration. It does NOT contain specific design details sufficient to establish prior art for any particular feature — those details will appear in later publications when designs are complete. Listing these directions here serves only to indicate that the project has a broader arc and that future publications may follow.

16.5.1 Directions Under Consideration (Non-Specific)

Adaptation of the Leitner variant and mastery gate structure to instruments other than piano (guitar, bass, voice, drums, orchestral strings, brass, woodwinds)
Adaptation to musical skills adjacent to chord recognition, such as ear training, interval recognition, rhythmic dictation, sight-reading, improvisation, and transcription
Expansion of the regional curriculum concept (Part 13) to additional musical traditions beyond East Asian pop
Teacher-facing features such as multi-student dashboards, assignment creation, progress sharing with parents, and integration with music-school management systems
Integration with existing music notation software and DAWs for content ingestion
Real-time performance feedback beyond chord validation (rhythm accuracy, dynamics, articulation)
Practice analytics for individual users and for teacher-student relationships
AI-assisted features that respect the pedagogical principles documented in this publication (no gamification dark patterns; no training on user data without consent; no substitution of AI feedback for human teacher relationships)

16.5.2 Important Limitation of This Section

This section is deliberately unspecific. The paragraphs above are NOT sufficient to establish prior art for any particular design. They do not describe algorithms, tuning parameters, UX flows, data models, or any of the specific combinations that make a design patentable or defensibly prior-art-worthy. They are a statement of intent.

When any of these directions is fully designed, a separate defensive publication will document it with the specificity required to establish prior art. Until then, readers should not treat any direction listed in this section as either (a) a commitment to build it, or (b) prior art blocking others from patenting specific implementations.

Part 17: Technical Architecture Decisions

Documented here briefly for prior art on specific combinations:

17.1 Client-Side Chord Validation with Server-Side Gate Verification

Chord validation runs entirely in the browser (no network round-trip per chord — required for MIDI latency). Paywall and mastery gate verification run on the server. The hybrid pattern: client for UX-critical paths, server for security-critical paths. This pattern is the correct architecture for any adaptive learning app with paid tiers; documented here specifically for chord-training apps.

17.2 Leitner State Serialized as JSON Blob Per Level

Rather than normalizing Leitner state into a separate table per chord, the full Leitner state for a level is stored as a JSON blob in the level_progress row. This trade-off favors read performance (one query loads a level’s full state) over queryability (can’t SQL-query individual chord histories easily). Acceptable because Leitner state is read in aggregate much more often than individual chord histories are queried.

17.3 Append-Only Session Log

Practice sessions are recorded as append-only rows. Sessions are never updated or deleted. This simplifies analytics, audit, and debugging. The live Leitner state in level_progress is the “current snapshot”; sessions are the “event log.” This is a standard event-sourcing pattern, documented here specifically for music-practice applications.

Part 18: What This Document Does NOT Claim

To be clear about the limits of prior art:

I do not claim invention of spaced repetition. Leitner invented it in 1972.
I do not claim invention of MIDI chord recognition. MIDI input and chord parsing are both decades old.
I do not claim invention of adaptive difficulty in music education. General adaptive learning has been researched extensively; the 2010 US patent application (US20110247479A1) describes adaptive chord training with MIDI input and was abandoned, putting the core concept in the public domain.
I do not claim invention of gamification in education apps. This is ubiquitous.
I do not claim invention of any specific chord progression. Royal Road, Canon, axis, and others are all public domain music theory.

What I am specifically documenting here:

The combination of these elements in the specific configurations described above
The specific tuning parameters (7 boxes with these intervals; min pool 6; max rotation 15; 3x mastery / 48 hour / 85% / 20 chord gate; 12 minute break trigger; 3 consecutive error struggle trigger; 3 miss hint escalation)
The specific pedagogical decisions (shell-only-in-root-position; fully-diminished-has-no-inversions; extended-chord omission rules as tabled; inversion triple-notation; dual-scale gamification)
The specific UX patterns (milestone-granularity Guided+ selector; confirmation screen for skipping; beta ref through password screen; per-question bug flag; no-dark-patterns paywall)

By publishing these specific decisions with precise parameters on this date, I establish them as public prior art. Anyone may use them. No one may patent them (at least, no valid patent could be granted over published prior art). Including me.

Part 19: Invitation

If you are a music educator, piano teacher, or app developer working on adaptive music pedagogy, I welcome correspondence. The design decisions documented here were not arrived at in isolation — beta testers, piano teachers, and the broader music-education community shaped every one of them.

If you have research, beta feedback, or design ideas that would improve on what is described here, I would like to hear from you. Contact: collin@adaptiveharmony.com.

If you are building something in this space and want to discuss pedagogical questions (not business competition), I am genuinely open. Adaptive music education is a small field; more builders make all of our tools better for learners.

Verification

This document is published at:

adaptiveharmony.com (primary location)
Internet Archive Wayback Machine (archived on publication date for permanent timestamp)
Google Drive (distributed to third parties including professional contacts)

Hashes of the document text will be recorded in the project’s IP log as of the publication date for additional verification.

Document version: 1.0 Original publication date: April 22, 2026, 3:54 PM CDT Author and copyright holder of the expression (not the ideas): Collin Wade, Adaptive Harmony

The ideas described in this document are hereby contributed to the public domain as prior art. The expression (the specific words of this document) remains copyrighted by the author. You are free to use, implement, modify, and build on the ideas; you are not free to copy the text of this document without attribution.

End of publication.