Skip to content

Improve first-run onboarding: close the loop + git-aware project card#633

Open
bborn wants to merge 1 commit into
mainfrom
task/4659-review-taskyou-first-time-experience-and
Open

Improve first-run onboarding: close the loop + git-aware project card#633
bborn wants to merge 1 commit into
mainfrom
task/4659-review-taskyou-first-time-experience-and

Conversation

@bborn

@bborn bborn commented Jul 8, 2026

Copy link
Copy Markdown
Owner

What & why

Reviewed the first-time TUI experience by driving scripts/qa/ty-qa-firstrun.sh across all three launch scenarios (git repo / non-git marker folder / plain folder). Three papercuts stood out against the JTBD — "get an agent working on my code with as little setup as possible" — and this PR fixes them.

1. Momentum dead-end → carry into the first task

Accepting Create Project (from the detection card or the Welcome fork's folder picker) used to drop you onto an empty board that just said "press n". Setting up the project is only step one — the point is to run a task in it. Now creation flows straight into the New Task form, pre-selected to the project you just created (via the existing SetLastUsedProject). esc returns to the board.

Verified end-to-end: pressing y on the git card now opens New Task with Project: acme-rocket already selected.

2. Wrong noun for non-git folders

The card said "Create a TaskYou project for this repo?" and "This directory looks like a project" even for a non-git marker folder. And it exposed raw Worktrees: true/false jargon.

Now git-aware:

  • git repo: "…for this repo?" · "This git repo looks like a project." · "Isolation: each task runs in its own git worktree"
  • non-git folder: "…for this folder?" · "This folder looks like a project." · "Isolation: off — not a git repo, so tasks run in the folder directly"

3. Unlabeled Welcome fork

The two buttons ("Set up a project" / "Just start a task") never said what they do. Added a one-line hint under the highlighted choice.

Implementation notes

  • Card copy extracted into pure, unit-tested helpers projectDetectTitle / projectDetectDescription (no huh/AppModel deps).
  • No behavior change to detection/candidate logic — copy + post-create flow only.

Testing

  • go test ./internal/ui/ — green
  • golangci-lint run with the CI-pinned v2.8.0 — 0 issues
  • New tests: TestProjectDetectTitle, TestProjectDetectDescription, TestWelcomeChoiceHint, TestWelcomeViewShowsChoiceHint, and momentum assertions added to TestCreateDetectedProjectPersists
  • Manual QA via ty-qa-firstrun.sh (all 3 scenarios) + drove the card→form jump on the isolated harness

🤖 Generated with Claude Code

Review of the first-time TUI experience via the ty-qa-firstrun harness
surfaced three papercuts against the "get an agent working on my code with
minimal setup" job-to-be-done:

1. Momentum dead-end: accepting "Create Project" from the detection card
   (or the Welcome fork's folder picker) dropped the user onto an empty
   board that just said "press n". Setting up the project is only step one
   — the job is to run a task in it. Now creation carries straight into the
   first-task form, pre-selected to the new project (via SetLastUsedProject).
   esc returns to the board.

2. Wrong noun: the detection card said "Create a TaskYou project for this
   repo?" and "This directory looks like a project" even for a non-git
   marker folder (Worktrees: false). Now git-aware: "repo" vs "folder", and
   the "Worktrees: true/false" jargon is spelled out as what it means —
   "Isolation: each task runs in its own git worktree" vs "Isolation: off".

3. Unlabeled fork: the Welcome fork's two buttons ("Set up a project" /
   "Just start a task") didn't say what they do. Added a one-line hint under
   the highlighted choice.

Card copy is extracted into pure, unit-tested helpers (projectDetectTitle /
projectDetectDescription). Verified all three scenarios + the momentum jump
end-to-end with scripts/qa/ty-qa-firstrun.sh.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant