# How the no-mistakes TUI Reviews Findings: Navigation, Selection, and Actions Explained

> Discover how the no-mistakes TUI simplifies reviewing findings. Navigate, select, and take action on JSON results efficiently with this interactive terminal UI.

- Repository: [Kun Chen/no-mistakes](https://github.com/kunchenguid/no-mistakes)
- Tags: deep-dive
- Published: 2026-06-27

---

**The no-mistakes terminal UI parses JSON findings per pipeline step, renders them as an interactive list with severity icons and checkboxes, and allows users to navigate with *j/k*, toggle selections, jump to diffs, and submit chosen items to a fix agent or approve the step.**

The `kunchenguid/no-mistakes` project implements a terminal user interface (TUI) that transforms static linting results into an interactive review session. When a pipeline step generates findings—whether from an automated agent or manually added by a user—the TUI loads these from raw JSON and presents them as a selectable list where developers can curate exactly which issues to address.

## Core Data Model for Findings Review

The interactive review system centers on a `Model` struct defined in [`internal/tui/findings.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/tui/findings.go) that maintains state across steps:

```go
type Model struct {
    stepFindings          map[types.StepName]string   // raw JSON per step
    findingItems          []finding                   // merged agent + user items
    findingSelections    map[types.StepName]map[string]bool // selected IDs
    findingCursor        map[types.StepName]int      // cursor per step
    // … other UI state
}

```

*(Source: [`internal/tui/findings.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/tui/findings.go) lines 10‑30.)*

This structure separates the raw JSON storage (`stepFindings`) from the parsed, navigable items (`findingItems`), while tracking **cursor position** and **selection state** independently for each pipeline step. The `findingSelections` map uses boolean flags to track which finding IDs are checked, enabling persistent selections even when users navigate between steps.

## Rendering the Findings List

The visual representation is generated by the `renderFindingsWithSelection` pipeline in [`internal/tui/review.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/tui/review.go), which delegates to `renderFindingsRange` for the actual string construction.

Each finding line combines several visual elements:

- **Severity icons** — `severityIcon` (lines 30‑39) maps `error`, `warning`, and `info` levels to `E`, `W`, and `I` respectively, with color coding (red for errors, yellow for warnings, blue for info).
- **Selection checkboxes** — Selected items display a green `[x]`, while unselected items show a dim `[ ]` (lines 81‑84).
- **Cursor indicator** — The current line is marked with a blue `>` symbol, driven by the `findingCursor` index.
- **User attribution** — Findings where `item.Source == FindingSourceUser` append a blue `[user]` tag (lines 98‑103).
- **Location truncation** — Long file:line references are shortened using `cutText` to prevent line overflow (lines 111‑115).

The footer beneath the list provides viewport context and selection summaries, such as `↑ 2 above ↓ 3 more below (j/k) • E 2 W 1 selected`, indicating scroll position and the count of selected errors and warnings (lines 52‑68).

## Navigation and Interaction Actions

The TUI supports both vim-style and arrow-key navigation through functions defined in [`internal/tui/findings.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/tui/findings.go):

### Cursor Movement

**`moveFindingCursor(step, delta)`** updates the `findingCursor` map, moving the blue `>` indicator up or down in response to *j/k* or arrow keys.

### Selection Toggling

**`toggleCurrentFinding(step)`** flips the boolean value in `findingSelections[step]` for the item under the cursor, immediately updating the checkbox display from `[ ]` to `[x]`.

### Bulk Selection

**`selectAllFindings(step)`** (lines 110‑118) pre-checks every finding ID for the current step, while **`clearAllFindings(step)`** empties the selection map entirely. These correspond to the `a` (select all) and `c` (clear) keybindings.

### Diff Inspection

**`diffOffsetForCurrentFinding(step)`** translates the file:line reference of the highlighted finding into a scroll offset for the diff view, allowing users to press `d` to jump directly to the relevant code location.

## From Review to Resolution

Once the user has curated the findings list, the TUI determines the available exit actions based on `awaitingActionState`:

- **Fix** — When `allowFix == true` (indicating actionable findings are selected), the UI builds a payload using **`selectedFindingIDs(step)`** for agent-produced issues and **`selectedUserAddedFindings(step)`** for user-added items. These IDs are bundled into `RespondParams` and sent to a fix agent that generates patches for only the selected items.
- **Approve** — If the step has no actionable findings (`allowFix == false`), the UI presents only an “Approve” button, marking the step as passed without invoking a fix agent.

The selection state clears automatically upon step completion, ensuring the next review starts with a clean slate.

## Summary

- The **Model struct** in [`internal/tui/findings.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/tui/findings.go) stores raw JSON findings, parsed items, cursor positions, and selection states per step.
- **Rendering** occurs via `renderFindingsWithSelection` in [`internal/tui/review.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/tui/review.go), which produces severity-coded lines with checkboxes, user tags, and cursor indicators.
- **Navigation** uses *j/k* or arrow keys mapped to `moveFindingCursor`, while **Space/Enter** toggles individual selections via `toggleCurrentFinding`.
- **Bulk actions** `selectAllFindings` and `clearAllFindings` provide quick selection management.
- **Diff inspection** uses `diffOffsetForCurrentFinding` to synchronize the findings list with the code diff view.
- **Resolution** paths include submitting selected findings to a fix agent or approving steps with no actionable items.

## Frequently Asked Questions

### How does the no-mistakes TUI distinguish between agent-generated and user-added findings?

The parser checks the `Source` field of each finding. When `item.Source == FindingSourceUser`, the renderer appends a blue `[user]` tag to the line (lines 98‑103 in [`internal/tui/review.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/tui/review.go)). User-added findings are tracked separately in `selectedUserAddedFindings` when building the fix payload, ensuring they are handled appropriately by the fix agent.

### What keyboard shortcuts are available for reviewing findings in the no-mistakes TUI?

Users navigate with **j/k** or arrow keys (mapped to `moveFindingCursor`), toggle selections with **Space** or **Enter** (`toggleCurrentFinding`), select all with **a** (`selectAllFindings`), clear all with **c** (`clearAllFindings`), and jump to the diff with **d** (`diffOffsetForCurrentFinding`).

### How does the TUI handle findings from multiple pipeline steps simultaneously?

The `Model` maintains separate `findingCursor` and `findingSelections` maps keyed by `types.StepName`, allowing each step to retain its own cursor position and selection state. When a user switches steps, the UI loads the appropriate entries from these maps without losing context from other steps.

### What happens if I select a finding but then navigate away from the step?

Selections persist in the `findingSelections` map until explicitly cleared or until the step completes. The TUI checks `awaitingActionState` to determine if the current selection set contains actionable items, enabling the "Fix" button only when appropriate, regardless of previous navigation history.