feat(ux): improve first-time user experience by subsy · Pull Request #155 · subsy/ralph-tui

subsy · 2026-01-19T18:27:02Z

Summary

Improves the developer experience for first-time users by addressing friction points when getting started with ralph-tui.

JSON tracker startup: When using the JSON tracker without specifying --prd, the TUI now opens with the load dialog instead of erroring at the terminal
Default labels filter: Removed 'ralph' as the default label filter during setup, so users see all their epics by default (can still add labels manually)
Empty state guidance: When no epics are found in beads mode, shows helpful checklist:
- Check if epic beads are defined
- Shows configured labels (if any) that epics need
- Mentions children and dependencies for awareness
Dashboard auto-commit: Added auto-commit status indicator (✓/✗) to the dashboard (d key)

Test plan

Run ralph-tui run with tracker: json in config but without --prd flag - should open TUI with file prompt
Run setup wizard with beads tracker - labels should default to empty
Test epic selection with no epics - should show helpful guidance checklist
Test epic selection with labels configured but no matching epics - should mention the labels
Press 'd' to open dashboard - should show auto-commit status

Summary by CodeRabbit

New Features
- Control epic loader visibility on startup (enabled for JSON tracker without PRD).
- Epic selection shows configured labels and contextual guidance when no epics are found.
- Auto-commit status indicator added to the progress dashboard.
Improvements
- JSON tracker validation now warns and prompts for file selection instead of blocking configuration.
- Default labels prompt changed to empty with guidance to leave blank to show all epics.
Tests
- Updated beads tracker tests to expect an empty default for labels.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

- JSON tracker without --prd now opens TUI with load dialog instead of erroring at the terminal - Remove 'ralph' from default labels filter so users see all epics by default (can still add labels manually in config) - Show helpful guidance in beads empty state with checklist: - Check for epic beads defined - Show configured labels if any - Mention children and dependencies - Add auto-commit status (✓/✗) to dashboard (d key)

vercel · 2026-01-19T18:27:07Z

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Review	Updated (UTC)
ralph-tui	Ignored		Jan 19, 2026 7:30pm

coderabbitai · 2026-01-19T18:27:12Z

Walkthrough

Adds runtime control to show the epic loader on startup for JSON trackers without a PRD, converts missing PRD validation into a warning/prompt, exposes tracker-configured labels to the epic selection UI, and surfaces auto-commit in the progress dashboard via prop threading.

Changes

Cohort / File(s)	Summary
Run flow & startup flag `src/commands/run.tsx`	Adds `initialShowEpicLoader?: boolean` to `RunAppWrapperProps`; computes `initialShowEpicLoader = config.tracker.plugin === 'json' && !config.prdPath` and passes it into the wrapper.
RunApp & dashboard wiring `src/tui/components/RunApp.tsx`, `src/tui/components/ProgressDashboard.tsx`	`RunApp` accepts `initialShowEpicLoader` and initializes `showEpicLoader` from it; `ProgressDashboard` gained `autoCommit?: boolean` and receives `storedConfig?.autoCommit`.
Config validation change `src/config/index.ts`	For JSON tracker without `prdPath`, validation now emits a warning and a note that the TUI will prompt for file selection instead of failing validation.
Beads tracker API & defaults `src/plugins/trackers/builtin/beads/index.ts`, `tests/plugins/beads-tracker.test.ts`	Adds `getConfiguredLabels(): string[]` to `BeadsTrackerPlugin`; changes default `labels` setup prompt from `'ralph'` to `''`; updates tests to expect empty default.
Epic selection UI labels `src/tui/components/EpicSelectionApp.tsx`, `src/tui/components/EpicSelectionView.tsx`	Threads `configuredLabels` (string[]) from tracker into `EpicSelectionView`; enhances empty-state messaging to show configured labels and guidance.
Config tests `src/config/index.test.ts`	Test updated to expect a valid config with a PRD warning for JSON tracker without `prdPath` instead of an error.

Sequence Diagram(s)

sequenceDiagram
  participant CLI as "CLI (run.tsx)"
  participant Config as "Config validator"
  participant RunWrapper as "RunAppWrapper"
  participant RunApp as "RunApp (TUI)"
  participant Tracker as "Tracker plugin (beads/json)"
  participant User as "User (TUI)"

  CLI->>Config: load config
  Config-->>CLI: return config + PRD warning (if json && no prdPath)
  CLI->>RunWrapper: create with initialShowEpicLoader=(tracker==='json' && !prdPath)
  RunWrapper->>RunApp: mount with initialShowEpicLoader
  RunApp->>Tracker: request configuredLabels and tracker data
  Tracker-->>RunApp: return configuredLabels, epics
  RunApp->>RunApp: init showEpicLoader from initialShowEpicLoader
  RunApp->>User: render EpicSelectionView (configuredLabels) and ProgressDashboard (autoCommit)

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

fix: beads tracker closes tasks more consistently and in the correct database based on config. #108: Modifies RunApp component behaviour and props; overlaps with epic loader and dashboard prop changes.
feat: prompt engine v2 - templates, preview panel, and UX improvements #128: Related changes to JSON-tracker PRD handling and tracker APIs used by the TUI.

Poem

🐰 The JSON field is bare, I peep and hop,

I show the loader quick — no need to stop.
Labels whisper where the epics hide,
Auto-commit ticks by my side.
A rabbit nods: prompts keep progress top.

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Title check	❓ Inconclusive	The title 'feat(ux): improve first-time user experience' is related to the changeset but is overly broad and vague for the specific changes implemented.	Consider using a more specific title that reflects the key technical changes, such as 'feat: add json tracker file selection and improve empty-state guidance' or breaking into multiple commits with more targeted titles.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage	✅ Passed	Docstring coverage is 85.71% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

📝 Generate docstrings

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

The default labels filter was changed from 'ralph' to '' so users see all epics by default. Update the test to match.

The JSON tracker without prdPath now produces a warning instead of an error since the TUI will prompt for file selection. Update the test to match the new behavior.

codecov · 2026-01-19T19:32:14Z

Codecov Report

❌ Patch coverage is 54.54545% with 5 lines in your changes missing coverage. Please review.
✅ Project coverage is 45.96%. Comparing base (ec485ff) to head (ec39320).
⚠️ Report is 4 commits behind head on main.

Files with missing lines	Patch %	Lines
src/commands/run.tsx	0.00%	3 Missing ⚠️
src/config/index.ts	75.00%	1 Missing ⚠️
src/plugins/trackers/builtin/beads/index.ts	75.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #155      +/-   ##
==========================================
- Coverage   45.97%   45.96%   -0.01%     
==========================================
  Files          63       63              
  Lines       16101    16109       +8     
==========================================
+ Hits         7402     7405       +3     
- Misses       8699     8704       +5

Files with missing lines	Coverage Δ
src/config/index.ts	`52.28% <75.00%> (+0.06%)`	⬆️
src/plugins/trackers/builtin/beads/index.ts	`49.29% <75.00%> (+<0.01%)`	⬆️
src/commands/run.tsx	`9.67% <0.00%> (-0.03%)`	⬇️

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

…devex feat(ux): improve first-time user experience

AI Agent added 2 commits January 19, 2026 19:21

test: update labels default expectation to empty string

948f647

The default labels filter was changed from 'ralph' to '' so users see all epics by default. Update the test to match.

test: update json tracker validation test to expect warning

ec39320

The JSON tracker without prdPath now produces a warning instead of an error since the TUI will prompt for file selection. Update the test to match the new behavior.

subsy merged commit 4382552 into main Jan 19, 2026
9 checks passed

subsy deleted the feat/improve-first-time-user-devex branch January 19, 2026 19:33

sakaman pushed a commit to sakaman/ralph-tui that referenced this pull request Feb 15, 2026

Merge pull request subsy#155 from subsy/feat/improve-first-time-user-…

4d7bd66

…devex feat(ux): improve first-time user experience

coderabbitai bot mentioned this pull request Feb 18, 2026

Fix Beads sync to use --flush-only flag to prevent data loss #316

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(ux): improve first-time user experience#155

feat(ux): improve first-time user experience#155
subsy merged 3 commits intomainfrom
feat/improve-first-time-user-devex

subsy commented Jan 19, 2026 •

edited by coderabbitai bot

Loading

Uh oh!

vercel bot commented Jan 19, 2026 •

edited

Loading

Uh oh!

coderabbitai bot commented Jan 19, 2026 •

edited

Loading

Uh oh!

codecov bot commented Jan 19, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Comments

Conversation

subsy commented Jan 19, 2026 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Summary by CodeRabbit

Uh oh!

vercel bot commented Jan 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai bot commented Jan 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Sequence Diagram(s)

Estimated code review effort

Possibly related PRs

Poem

Uh oh!

codecov bot commented Jan 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Comments

subsy commented Jan 19, 2026 •

edited by coderabbitai bot

Loading

vercel bot commented Jan 19, 2026 •

edited

Loading

coderabbitai bot commented Jan 19, 2026 •

edited

Loading

codecov bot commented Jan 19, 2026 •

edited

Loading