---
schema_version: 1
id: RAC-KTW06NWH56R9
type: roadmap
---
# RAC v0.8.11 — Explorer Follow-ups: Core-Owned Impact and First-Run Editor

## Status

Planned

## Context

Two deliberate deferrals from the v0.8.x series are recorded in
`rac/roadmaps/future/explorer-followups.md`; with the workspace, command
surface, live reload, and creation flows complete (v0.8.7–v0.8.10), this
item retires both.

First, every recommendation's *impact* sentence ("why it matters") is
Explorer-authored presentation copy in `rac.explorer.adapter`, keyed by
Core's finding codes. That kept v0.8.3 presentation-only, but it leaves
`rac review` JSON consumers without impact text and the copy outside the
validated corpus. The fix follows ADR-015's own ordering — service, then
CLI, then JSON, then Explorer: Core owns the impact text on `ReviewIssue`,
and the Explorer renders it instead of its own.

Second, the editor preference and terminal-editor support landed in v0.8.8,
but a fresh user is never offered an editor: onboarding is a welcome screen
only, and the preference hides in `/settings`. The first-run prompt the
deferral note called for closes the loop.

## Outcomes

- Impact text becomes repository intelligence: every `rac review` consumer
  — JSON, CLI, CI, the Explorer — reads the same Core-owned "why it
  matters" sentence for a finding.
- The Explorer carries no finding copy of its own; the adapter renders
  Core's fields verbatim (ADR-015 fully honored for recommendations).
- A first-run user leaves onboarding with a working editor: prompted once,
  prefilled from the environment, skippable, persisted — and never asked
  again.

## Initiatives

### Initiative 1 — Core-Owned Impact Text

`ReviewIssue` gains an additive `impact` field with Core-owned per-code
text, carried through `to_dict` as an additive JSON-contract change
(ADR-007; `schema_version` stays 1 — fields are additive and gated). The
review service's human rendering may surface it where useful; the Explorer
adapter deletes its `_IMPACT` table and renders Core's sentence. Unknown
codes carry a generic impact in Core, so the field is always present.

### Initiative 2 — First-Run Editor Prompt

Onboarding gains one optional step after the welcome: an editor prompt
prefilled from `$VISUAL` / `$EDITOR`, where Enter accepts (an empty value
keeps the environment fallback), editing the line sets the preference, and
Esc skips. The choice persists through the existing `save_preferences`
path; returning users — anyone past first run — never see the step.
`/settings` remains the place to change it later.

## Implementation Contract

The following decisions are pinned for v0.8.11.

### Impact

- `rac.services.review.ReviewIssue` gains `impact: str`; the per-code text
  moves from `rac.explorer.adapter._IMPACT` to the review service, with a
  generic sentence for unrecognized codes. `to_dict` adds the key —
  additive only; no existing field changes, no schema_version bump.
- The Explorer adapter's `_recommendation` reads `issue.impact`; the
  `_IMPACT` table is deleted (clean break, ADR-023). Golden files and JSON
  contract tests absorb the new key.

### First-run prompt

- The prompt is one onboarding state owned by the home view (no new
  screens); it appears only when `firstrun.is_first_run()` and writes only
  `explorer.json` (ADR-024). Resolution display reuses
  `editor.resolve_editor`; an accepted empty value stores `""` (the
  environment fallback), matching `/settings` semantics.

### Scope

- No new dependencies. The review JSON change is the only Core movement;
  it is additive and documented in the CLI reference. Explorer battery and
  review/golden batteries absorb all tests.

## Non-Goals

- Changing impact severities, priorities, codes, or actions — only the
  impact sentence moves.
- A schema_version bump — the field is additive (ADR-007).
- Editor validation or detection beyond what v0.8.8 shipped — the prompt
  stores a command, it does not verify one.
- Re-prompting existing users — the first-run marker already gates it.

## Success Measures

- `rac review --json` carries an `impact` for every issue, and the
  Explorer shows byte-identical impact text to the JSON output.
- `grep _IMPACT src/rac/explorer/` finds nothing.
- A fresh user who accepts the prompt has `editor` persisted in
  `explorer.json` and `e` works immediately; a user who skips sees the
  same behavior as today.

## Assumptions

- The review service remains the single producer of findings; no other
  consumer holds finding copy that would also need moving.
- The first-run marker (`explorer-first-run`) remains the onboarding gate.

## Risks

- Golden-file churn: adding a JSON key touches review goldens; the change
  is mechanical but must be reviewed as contract movement, not noise.
- Impact copy becomes API: once in JSON, wording changes are observable to
  consumers; text edits should be deliberate.
- An onboarding step risks friction; one prefilled, skippable line bounds
  it, and Esc preserves today's behavior exactly.

## Related Decisions

- ADR-007
- ADR-015
- ADR-023
- ADR-024

## Related Designs

- explorer-recommendations
- explorer-editor-integrations
- explorer-first-run-experience

## Related Requirements

- rac-product-knowledge-navigator-explorer

## Dependencies

- v0.8.10 explorer creation, stats, and directory view
