Learning the theory by building the tool
Wholestep: a beginner-first music learning engine, built while working through a guitar course without any theory behind it.
Runs in a browser, best on a phone. Sound begins on first touch.
I could play. What I had never had was any theory behind it — which turned out to be the useful position to design from.
Sec. 01
Context and operating scale
I was working through Scotty West's Absolutely Understand Guitar course. I could play — what I had never had was any theory behind it, which is a common and frustrating place to be stuck.
The course comes with a physical slide rule: a printed card you turn to find scales, chords and relationships. It works, and it is the kind of thing that stays on a desk. I wanted a version I could carry, so I built one and sent it to Scotty. Four rounds of his feedback later, he offered to integrate it into his programme.
That should have been the end of it. Instead, building the reference tool made the actual problem visible — and the actual problem was not reference.
Sec. 02
The real problem
A reference system shows you what music contains. It does not teach you to hear it. I had built a good map for someone who could not yet read maps, and since I was that someone, it took a while to notice.
The conventional beginner path makes the same error at scale. Terminology and diagrams arrive before you have any reason to care about them. All correct, all useless on day one, because none of it is attached to a sound you have made yourself.
So the question changed. Not 'how do I display theory well' but: how might someone learn by hearing, copying and noticing first, with the vocabulary arriving only once it becomes useful?
Sec. 03
My role
- Product strategy and the decision to abandon the reference framing
- Learning-system design: the sequence, the constraints, the rules
- Interaction design across two instruments
- Architecture direction — shared music model, instrument adapters, lesson engine
- Prototyping and real-device testing
Sec. 04
What I designed
The core sequence reverses the usual order. Hear it, copy it, compare it, notice it, name it, use it, recall it later. Vocabulary arrives sixth, after the learner has already experienced the thing it names.
Everything else follows from that. The rules I ended up with:
- One obvious action at a time
- No scrolling to find the thing you are meant to do
- Demonstrations and the playable instrument share one sound source, so what you hear is what you make
- Guidance persists after the demonstration ends, because a beginner cannot hold it
- Mistakes produce supportive correction, never punishment
- Ascending musical movement must remain spatially ascending
- Reference tools are withheld until they solve a problem the learner actually has
Musical Slide Rule
Can I make Scotty West's relationships easier to see on a phone?
The first build was a compact offline reference: scales, modes, chords, fretboard and Circle of Fifths in one place. Useful to me, but it assumed the learner already understood the language.
- What it proved
- The underlying relationships could be represented consistently across keys and views.
- What was still limited
- It was a reference tool, not a teaching system.
- What it made me ask next
- Make the interval logic and explanations clearer before adding learning behaviour.
Scotty feedback iteration
Can the reference explain spacing rather than only display it?
Interval spacing, enharmonic naming and audio were tightened through repeated feedback. Whole and half steps became visible between the notes instead of being something the user had to infer.
- What it proved
- The reference could carry more of the theory without becoming a wall of text.
- What was still limited
- Understanding still depended on the learner deciding what to study and in what order.
- What it made me ask next
- Add sequence, practice and feedback rather than more reference material.
Music Boy
What changes when the tool starts teaching?
Learn and Practice appeared: short lessons, scale-building exercises, ear training, scoring, streaks and local progress. That exposed a more important problem — bolting lessons onto a reference library still made the reference the centre of the product.
- What it proved
- Progress, practice and persistence could live in the same small offline application.
- What was still limited
- The learner still arrived at a library and had to understand too much before acting.
- What it made me ask next
- Invert the product: one action at a time, sound first, vocabulary only after experience.
Wholestep
What if the product begins with the learner's next action instead of the theory catalogue?
The reference-tool premise was abandoned. Wholestep became a guided beginner loop built around hear, copy, compare, notice, name and use — with the keyboard as the explanatory surface and guitar as the destination.
- What it proved
- The architecture and interface could be organised around beginner behaviour rather than topic navigation.
- What was still limited
- The pedagogy is still unproven beyond me and the domain expert.
- What it made me ask next
- Stabilise the engine, then test the sequence with people who are genuinely new to the concepts.
Sec. 05
How it was used
At V0.5 I stopped adding lessons. The curriculum was outgrowing its foundations, and adding more content would have meant rebuilding it all later.
Instead: shared music model, answer constraints, audio lifecycle, progression and instrument adapters separated into their own layers, plus an engine lab to stress-test the architecture before scaling the curriculum on top of it.
That is the same decision as removing capability from The Spicy Noodle after v3.3.1. Pausing to fix the foundation is unglamorous and it is almost always right.
Sec. 05b
Two instruments, one musical truth
The keyboard became the explanatory surface because semitone distance is visually unambiguous — one key to the next, no exceptions. The guitar remained the destination, because that is the instrument the learner wants to play.
That forced the architecture. One shared music model, rendered through instrument adapters: music model, then lesson engine, then answer constraints, then living instruments, then audio, then progression. Piano and guitar are not two curricula. They are two physical views of the same information.
It is the same structural move as the regeneration classification. Find the underlying model, then render it for whoever is looking at it — which is also what the three house styles for one standard were doing. I did not set out to repeat myself. It turns out the pattern is the point.
Sec. 05c
What the phone taught that mockups could not
Real-device testing changed the architecture repeatedly, and every discovery was a category of problem rather than a bug.
Audio: a synthetic, uneven piano sound destroyed trust immediately, so sound quality became a product requirement rather than a detail. Then browser lifecycle testing exposed suspended audio contexts after switching apps — the screenshot of a failure state is included above deliberately. The resulting principle is simple: navigation must never depend on audio being ready, and recovery is owned by one engine rather than scattered through the interface.
Timing: success cues could overlap the learner's final note and sound doubled. Comparison examples gave away their own answers. Target highlights arrived late. Small individually, and collectively they proved that music-learning interfaces need choreography rather than screens.
State: transient empty copy, skipped guitar moments and a splash-screen deadlock all traced back to booleans scattered across components. Guided learning needs a deterministic state machine, not a collection of flags.
Progression: repeating a completed lesson farmed points. That produced stable completion identifiers and a separation between participation, durable mastery and review.
Geometry: the guitar could not stay a decorative bridge. Six strings, high E at the top, open strings as fret zero before the nut, fretted notes centred inside the fret space. Get any of that wrong and a guitarist stops trusting the whole thing.
Sec. 05d
Credit where it belongs
The musical framework is Scotty West's. His Absolutely Understand Guitar course and its slide rule established the relationships this is built on, and the tool exists because I was working through his material and wanted it in my pocket.
Four rounds of his feedback shaped the reference tool before any of the learning system existed. He has offered to integrate it into his programme with credit.
What is mine is the teaching architecture: the hear–copy–compare–notice sequence, the shared music model, the instrument adapters and the lesson engine. Those are design decisions, not musical ones, and it is worth being precise about which is which.
Sec. 06
Current Wholestep prototype
The lineage above shows how the premise changed. These are current prototype screens from real phone testing, including one failure state.
Sec. 07
Relevance by outcome
What it demonstrates
- Product reframing — abandoning the original premise when it proved wrong
- Learning-system design from first principles
- Shared-model architecture rendered through multiple adapters
- Real-device testing driving architecture rather than polish
Why the domain matters
- I was the target user, learning theory while designing the thing that teaches it
- The musical authority is Scotty's, not mine — his slide rule and his course
- What I contributed was structure: sequence, constraints, architecture
- If the method only worked in kitchens it would be experience rather than method
The recurring pattern
- Find the underlying model, render it for the reader in front of you
- Stop and fix the foundation before scaling the content on top
- Withhold detail until it solves a problem the user actually has
- Test in the real conditions, not in the mockup
Honest limits
- No users beyond me and the domain expert
- V0.5 — the engine is being stabilised, the curriculum is paused
- Pedagogical claims are untested; nobody has learned guitar from it yet
Sec. 08
Evidence ledger
Each statement on this page sits at one of five levels. Measured means recorded and quantified at the time. Documented means a retained artefact or record exists. First-person account means it rests on Ciarán's own testimony with no external corroboration. Inferred means it is reasoned from the design rather than shown by data. Not claimed means the page is explicitly not asserting it, and says why. Nothing is published above the level its evidence supports.
A working prototype exists, is live and can be tested.
Six development phases, the reframing from reference to teaching, and the V0.5 architecture pause.
The failure modes found in real-device testing — audio lifecycle, feedback timing, state management, progression exploits, guitar geometry.
Built on the reference conventions of Scotty West's Absolutely Understand Guitar slide rule, refined through four rounds of his feedback, and offered a place in his programme.
The musical framework is his. The learning system, lesson engine and instrument architecture are mine.
That it teaches music effectively.
Nobody has learned from it yet. Design intent only.
Any commercial outcome.
None. Independent work.
Sec. 09
Reflection and next iteration
The reason this one is on the site is not that it is a music product. It is that Wholestep is the clearest test on this site of whether the method survives outside a domain where I already have deep experience, and a method that only works where you are already expert is not a method.
Here the musical authority came from Scotty's course and his slide rule. What I brought was the structure: find the model underneath, sequence it around what the learner can actually do, and hold the vocabulary back until it earns its place. Designing it while learning it myself is the reason the sequence is what it is.
The next step is the same as everywhere else on this site — put it in front of people who are not me and find out what breaks.
Sec. 10