When Users Can’t Discover

When Users Can’t Discover

December 20–23, 2025

Saturday evening, testing on the alpha laptop. Fresh install complete, setup wizard working (FK bugs from last week now fixed). Time to try actual PM workflows.

First test: “What services do you offer?”

The response came back generic. Helpful, polite, but not what I’d asked for. No menu of capabilities, no feature overview, just a conversational “I can help with various tasks” non-answer.

Second test: “Help me setup my projects.”

Piper diverted immediately to GitHub issue creation. Wrong handler entirely. I’d asked for setup guidance, got issue tracking instead.

Two simple questions. Both should have worked. Neither did.

The investigation

The pattern was clear: Piper assumed I knew what to ask for. Ask about “GitHub issues” specifically, you’d get GitHub help. Ask about “projects” generically, the system would guess — often wrong.

We’d built a command-oriented interface. Users needed to know the right commands, the right phrasing, the specific features available. Discovery wasn’t supported. Exploration wasn’t encouraged.

This is a classic expert user trap. When you know the system intimately, you forget that new users need to find features before they can use them.

Lead Developer ran Five Whys analysis overnight:

Why did “menu of services” fail?
No pattern matched IDENTITY queries about capabilities.

Why no pattern for capability discovery?
Pre-classifier focused on execution (GitHub, Slack, Calendar) not exploration.

Why focus on execution?
System design assumed users know what they want.

Why that assumption?
Built from developer perspective — we knew every feature.

Why didn’t alpha testing catch this earlier?
We were the alpha testers. We knew what to ask.

Root cause: architectural gap. The system had no concept of “discovery intent.” No way to handle “show me what you can do.” No bridge between plugin capabilities and user exploration.

None of this surprised me. I knew we hadn’t really addresses this gap. The awareness had been nagging at me for some time but only alpha testing brought it to the surface.

The overnight implementation added 17 new patterns — “what services,” “what can you help with,” “show me capabilities,” “help setup,” “getting started.” All the discovery phrases users would naturally try.

But patterns alone weren’t the solution. They were symptoms treatment. The real issue ran deeper.

The architectural shift

Sunday morning, Lead Developer created Epic #488: “Discovery-Oriented Intent Architecture.”

The epic framed it clearly: We’d built a system where users need to know what to ask for. We needed a system where users could explore what’s available.

The difference:

• Command-oriented: “Create a GitHub issue about X” (requires knowing GitHub integration exists)
• Discovery-oriented: “What can you do?” → “I can help with GitHub, Slack, Calendar…” → “Tell me about GitHub” → capabilities explained

This wasn’t just adding patterns. It was reframing how Piper handles uncertainty and exploration.

The proposed architecture:

1. Add DISCOVERY as an intent category (alongside QUERY, EXECUTION, STATUS)
2. Route discovery requests to dedicated handler
3. Handler bridges to PluginRegistry metadata
4. Return structured capability menu
5. Support progressive disclosure (overview → details → usage)

Phase 1 could ship with pattern matching. Long-term would integrate with the UX 2.0 modeled consciousness work — but that’s post-alpha. For now: make discovery possible.

Meanwhile, canonical query work ramped up. Query #7 (historical retrospective), Query #14 (project-specific status) — the queries that power morning standups and daily check-ins. Implementation work that would feed into discovery.

Discovery becomes real

When we were finally ready, Lead Developer coordinated twelve Code agents in parallel. Each agent got a precise prompt: specific query, specific patterns, specific formatters, specific tests.

The queries that got implemented weren’t just features getting checked off. They were validation that the discovery architecture worked:

Identity queries: “What can you do?” now returns dynamic capabilities from PluginRegistry. “Are you working properly?” runs actual health checks. “How do I get help?” provides real onboarding guidance.

Temporal queries: “What did we accomplish yesterday?” “When did we last work on this?” “How long have we been working on this?” All the time-based questions PMs naturally ask.

Spatial queries: “What projects are we working on?” “Which project should I focus on?” “Show me the project landscape.” The workspace navigation questions.

Capability queries: “Can you create a GitHub issue?” “What integrations do you have?” The meta-questions about what’s possible.

By end of day: users could ask exploration questions and get real answers. Not generic responses, not “I can help with various tasks” — actual enumeration of capabilities, actual context about what’s available.

The interesting discovery: we’d already implemented many of these queries. Query #2 (dynamic capabilities) — code existed, just untracked. Query #16 (GitHub issue creation) — working, just undocumented. Query #18 (list projects) — functional, just missing from test matrix.

The 75% completion pattern striking again. Code written, functionality working, tracking abandoned. The systematic audit revealed what was actually there versus what we thought was missing.

Parallel momentum

While canonical queries were getting documented and tested, a different blocker resolved.

The mobile PoC had been stuck since December 7th. Expo Go’s SDK 54 bundled incompatible native module versions — Worklets 0.5.1 native vs. 0.7.1 JavaScript. No App Store update available to fix it.

Solution deferred that week: install Xcode, build native instead of relying on Expo Go’s pre-bundled modules.

Two weeks of infrastructure work later — FK bugs, intent classification, canonical queries — development circles back to mobile. Xcode installed. Native build path available.

npx expo run:ios

All native modules compiled. Fresh native code matching JavaScript expectations exactly. iPhone simulator launched. Entity-based gesture mapping fully functional — swipe right to complete tasks, swipe left to defer, haptic feedback, intent toasts, all working.

Seven-day blocker bypassed by building native instead of debugging Expo Go’s bundled limitations.

This is a skunkworks project. It doesn’t block anything. But it will be a crucial input into UX research and understanding what the the holistic UX model should feel like for a mobile user.

The parallel progress validated something important: sustainable work doesn’t mean single-threaded work. It means systematic work that can pause, resume, and move between contexts without losing thread.

What discovery enables

Four days. One architectural gap identified, one epic created, one implementation sprint, one mobile breakthrough.

But the real change was conceptual, not technical.

Before: Piper waited for users to know what to ask. “Create a GitHub issue” worked. “What can you do” didn’t.

After: Piper supports exploration. New users can ask “what services do you offer” and get an answer. They can ask “help me get started” and get guidance. They can ask “what makes you different” and get Piper’s differentiation story.

The technical implementation — 17 patterns, 31 tests, 12 queries, proper capability enumeration — proved the architecture shift worked. But the real validation would come from actual alpha testers trying to explore what Piper could do.

Discovery isn’t just a feature category. It’s a philosophical shift from assuming user knowledge to supporting user learning. From command-oriented to exploration-friendly.

We’d built a system that expected expertise. We needed a system that enabled learning. The gap between those two models was the difference between “powerful for experts” and “accessible for humans.”

Now when users ask “what can you do?” — they get a real answer.