I was searching Am7 to take a screenshot.
Near the top of the results, something looked off.
The top-ranked voicing had three notes: A, C, G. No 5th. Which isn't wrong, exactly. Am7 is A, C, E, G - and jazz players drop the 5th all the time. It's a real voicing. A perfectly valid one.
But it's not the one a guitarist expects to see first.
I was looking for Am7. I wanted the shape. The chunky, four-string, all-the-notes, "oh yes that's Am7" shape. Fretscape was handing me a chamber arrangement when I wanted the singalong.
It wasn't a bug. Fretscape was returning correct voicings, ranked by the difficulty system I'd spent months tuning. The theory was sound. The maths was right.
The problem was upstream. The ranking itself wasn't thinking like a guitarist.
TL;DR A screenshot of Am7 showed me Fretscape was ranking a three-note voicing (A, C, G - no 5th) above the standard four-tone shape. Technically fine; that voicing is real. But not what a guitarist scanning results expects to see first. Same with another result where the chord was correct but the diagram read as something it wasn't. The fix wasn't to remove these voicings - they're still valid, just not "first" material. It was to add a second ranking layer: one for musical correctness, one for what a guitarist's brain expects.
The expectation gap
Fretscape is built on the idea that chord tools should understand how guitarists think, not just how chords are spelled.
That sounds straightforward. It isn't.
Generating every valid voicing is the easy half. The hard half is showing them in the order a guitarist already expects them.
A guitarist searching Am7 isn't asking "what are the mathematically valid voicings of A, C, E, G?" They're asking "which one of these looks like Am7?" The first question is a theory problem. The second is a pattern-recognition problem - and the answer lives in a guitarist's hands after thousands of hours of chord charts, not in a music theory textbook.
A guitarist searching Am7 isn't asking "what are the mathematically valid voicings?" They're asking "which one of these looks like Am7?"
Problem one: the missing 5th
Here's what I saw as I scrolled down the voicing results a little bit.
Three notes. A, C, G. Root, minor third, minor seventh. No 5th.
That's a real voicing. Jazz players leave out 5ths routinely, because the 5th carries the least harmonic weight - the root, the third and the seventh tell you everything you need to know about the chord. In a dense arrangement, dropping the 5th clears space for someone else's notes.
But a guitarist typing Am7 into a lookup tool isn't writing a chart for their jazz quartet. They're trying to play a chord. The chord they want is the one with all four chord tones present. Root, third, fifth, seventh - all there, all accounted for.
The fix was quiet. Voicings that leave out non-optional chord tones now get tagged as incomplete. Tagged voicings still appear in results, because they're not wrong. They're just demoted below voicings with all the notes present.
Guitarists who want the slimmer voicing can still find it. Guitarists who just want Am7 get Am7.
Problem two: the shape that read wrong
Another result came up with the fingering 8 0 7 0 x x.
Reading low string to high: fret 8 on the low E (which is a C), open A, fret 7 on the D string (an A, an octave above the open A below it), open G, mute the top two.
It looks like C is the bass when you read the diagram from left to right. The dot on fret 8 of the low E sits at the bottom-left. But it isn't. The C on the low E is at C3; the open A is A2 - lower in actual pitch. The bass is A. The root, in root position.
So the maths is fine. This is a valid Am7 with the 5th omitted, root in the bass.
But it's still a strange one to lead with. The notes stack oddly - root, then C right above it with no breathing room, then a leap up to G, then back to A on the D string. A doubled root with the third tight against the bass. Cluster-y, awkward, not what a guitarist's eye or ear is reaching for.
A guitarist scanning the result has to look twice. The diagram puts the C at the bottom-left, which reads as "the chord starts on C" - even when their ear would tell them otherwise.
Same fix in spirit. Voicings whose layout reads wrong - doubled roots, tight clusters at the bottom, the lowest-fretted string sitting visually below the lowest-pitched string - get tagged. They're demoted below voicings that match the shape a guitarist expects to see.
Still there. Just not first.
The pattern I saw
Neither of these was really a bug.
The voicing generator was returning correct voicings. The difficulty scoring was accurate. The theory was sound. The problem was the ordering - because the ranking was judging by musical validity and nothing else.
That's one layer. It wasn't enough.
The engine finds what's technically correct. The ranking layer decides what a guitarist expects to see first. Those are different jobs.
Two different scoring layers, doing two different things. The first asks "is this a legitimate voicing of the requested chord?" The second asks "out of the legitimate voicings, which one matches the mental picture a guitarist has when they type this chord name?" Both answers matter. Neither replaces the other.
Why this is harder than it sounds
Most chord tools never face this problem.
They don't generate enough voicings to have to rank them properly. A tool with sixteen voicings for C major just shows you all sixteen. Sixteen results fit on a screen. You scroll once, you see everything, you pick.
A tool with a hundred-plus voicings doesn't have that luxury. The top of the list is the answer, because nobody's scrolling past the fold to find out what's there. Whatever sits first is effectively what the tool said when the user asked the question.
Curation becomes a first-class product problem. The deeper your generator goes, the harder your ranking has to work to think the way the user does - because the list you return is the list they'll act on.
The depth of your generator creates a ranking problem shallower tools never have to solve.
This isn't a complaint. It's a consequence of the design I picked. If you're generating every voicing a guitarist could play, you're taking on the responsibility of ordering them well.
Building intuition into software
Guitarists learn these expectations implicitly.
Nobody sits you down and explains this rule out loud. You absorb it the way guitarists absorb most things - through chord charts, songbooks, tab sites, lessons, and years of seeing the same kinds of shapes presented the same way. Eventually your brain builds a picture of what a chord is supposed to look like, even if you'd struggle to explain the rule in words. Most guitarists have never written any of this down.
But when a ranking violates it, something feels off. That mild sense of wait, that's not right is the rule firing. The guitarist couldn't necessarily tell you what the rule is. They just know when it's broken.
Building software for experienced players means turning those implicit rules into explicit ones. Which is harder than it sounds, because the rules only surface when they're broken. You don't catch them from the spec - the spec has no idea they exist. You catch them when a ranking feels wrong and you have to go dig out why.
What I took from it
Generating every valid option is the beginning. Not the end.
How you rank them is where the product actually lives. A generator that knows every voicing and a ranker that understands what a guitarist reaches for first is a different product from a generator that knows the voicings and lists them by difficulty. Same data. Different outcome.
When your system knows more about music than most of its users, the hard part stops being correctness and starts being presentation. The system is already right. It has to learn to be useful to someone who doesn't need an encyclopedia.
The only way to find these cases is to look at your own product the way a user would. Which in my case meant sitting down to take a screenshot and noticing, quietly, that something felt off.
The fix wasn't to make the system smarter. It was to make it more considerate.
Knowing is the easy part. Knowing what to show first is the whole game.
This is the third of five How Fretscape Thinks posts. The Am → F transition story - the system understood physical movement better than my intuition did. The progression optimiser bugs - the system wasn't respecting user intent. This one - the system wasn't respecting user expectation. And the final two - the system performing knowledge instead of giving it, and the system knowing when it didn't know. Different angles on the same destination.
A few questions this raises
Why not just remove voicings that don't match expectation?
Because they're not wrong. The 5th-less Am7 is a real voicing - jazz players reach for it all the time. And awkwardly-stacked voicings are real too - they show up inside progressions where a specific bass move or texture calls for them. Removing them would make the tool less useful for the guitarists who want exactly those shapes. Demoting them below the expected voicings solves the problem without losing the options.
How do you know when a ranking feels wrong?
You usually don't, until you use the product in a context you don't normally use it in. I was searching Am7 for marketing material, which isn't part of my normal building loop. The moment I looked at the results the way a user would, the problem jumped out. Implicit rules always do that - invisible until someone catches you on them.
Is this really a product problem and not an algorithm problem?
It's both, and the boundary is the interesting bit. The algorithm decides what's generatable; the product decides what's prioritisable. Treating those as the same problem is the mistake most tools make - they sort by musical correctness and call it done. Separating them is where the work is.
