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

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 that maintains state across steps:

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 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, 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:

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 stores raw JSON findings, parsed items, cursor positions, and selection states per step.
• Rendering occurs via renderFindingsWithSelection in 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). 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}