# First-Run UX Triage Report

Analyzed screenshot from Brady (images/001.png) showing Squad CLI shell first-run experience.

---

## Issue #1: Node.js SQLite ExperimentalWarning Leaking to Terminal

**Severity:** P1 (Blocks first impression, makes CLI appear broken)

**What's Wrong:**
Node.js experimental feature warnings are printed below the prompt and interfere with the REPL experience:
```
[CLI subprocess] (node:13692) ExperimentalWarning: SQLite is an experimental feature and might change at any time
[CLI subprocess] (Use 'node --trace-warnings ...' to show where the warning was created)
```

**Root Cause:**
The warning suppression in `cli-entry.ts` (lines 3-9) intercepts `process.emitWarning()` calls, but warnings may be generated by child processes or during module loading before this code executes.

**Where to Look:**
- `packages/squad-cli/src/cli-entry.ts` (lines 3-9): Current suppression mechanism
- Module imports in the same file that trigger SQLite loading
- The test file `test/repl-ux-e2e.test.ts` uses `NODE_NO_WARNINGS: '1'` in `cleanEnv()` (line 37) — this is the right approach

**Suggested Fix Approach:**
1. **Option A (Recommended):** Add `NODE_NO_WARNINGS=1` to the process.env early in `cli-entry.ts`, before any imports that could trigger SQLite
2. **Option B:** Ensure warning suppression runs earlier — move lines 3-9 to execute before all imports
3. **Verify:** Test runs from the CLI should show no warnings in the terminal output

---

## Issue #2: Redundant "Init" Messaging

**Severity:** P2 (Minor UX polish — slightly confusing but not breaking)

**What's Wrong:**
First-run message appears twice in the welcome sequence:

1. **In banner box** (line 300 of `App.tsx`): 
   ```
   "Exit and run 'squad init', or type /init to set up your team"
   ```

2. **Below banner** (line 321 of `App.tsx`):
   ```
   "Run 'squad init' to set up your team."
   ```

The second message is redundant — it repeats the core action users need to take.

**Root Cause:**
Two separate rendering paths for first-run state:
- `headerElement` (lines 277-306): Shows "Exit and run 'squad init'..." when no agents
- `firstRunElement` (lines 308-325): Shows "Run 'squad init'..." when `isFirstRun` is true with no agents

Both render simultaneously on first run with an empty roster.

**Where to Look:**
- `packages/squad-cli/src/cli/shell/components/App.tsx` (lines 299-301 and lines 320-322)
- `packages/squad-cli/src/cli/shell/lifecycle.ts`: How `isFirstRun` is determined in `WelcomeData`

**Suggested Fix Approach:**
1. Consolidate the first-run messaging: Only show one clear CTA
2. Remove the redundant "Run 'squad init'..." message from `firstRunElement` when roster is empty (line 321)
3. Keep the banner's "Exit and run 'squad init'..." as the single source of truth
4. Alternative: Make `firstRunElement` show only when `rosterAgents.length > 0` and `isFirstRun === true`

---

## Issue #3: Message Clarity/Tone Issue

**Severity:** P2 (Polish — minor tone inconsistency)

**What's Wrong:**
The phrase "Exit and run 'squad init'" in the banner requires users to *leave* the tool to set it up. This is accurate but slightly awkward — the suggestion "/init to set up your team" (in the same line) is the better UX, but both options appear simultaneously.

**Root Cause:**
The banner tries to accommodate both workflow paths (exit CLI vs. type command), which creates cognitive load.

**Where to Look:**
- `packages/squad-cli/src/cli/shell/components/App.tsx` (line 300)

**Suggested Fix Approach:**
1. Reorder or emphasize the command-driven path: "Type /init to set up your team. (Or exit and run 'squad init' from the terminal.)"
2. Or simplify: "Type /init to set up your team in this shell" — defer the exit option to help text

---

## Summary of Actions

| Issue | Priority | Owner | File | Quick Fix |
|-------|----------|-------|------|-----------|
| SQLite warnings | P1 | CLI | `cli-entry.ts` | Add `NODE_NO_WARNINGS=1` early in env setup |
| Redundant init message | P2 | Shell UX | `App.tsx` (first-run path) | Remove duplicate message or refactor conditional rendering |
| Message tone | P2 | Shell UX | `App.tsx` | Reorder/emphasize /init command over exit path |

---

## Verification

Once fixed:
1. Run `squad` with no .squad/ directory
2. Verify no `ExperimentalWarning` appears below the prompt
3. Verify only ONE clear "set up" instruction appears (not two)
4. Verify the wording guides users to `/init` or similar, not just "exit and run"

Run `npm run test` to check `test/repl-ux-e2e.test.ts` for first-run assertions.
