---
schema_version: 1
id: RAC-KTR5QS8SHD78
type: roadmap
---
# RAC v0.8.3 — Explorer Recommendations

## Status

Planned

## Context

v0.8.2 makes repository health visible. Findings alone are not enough: the
Explorer requirement states that Explorer shall not merely identify issues —
it shall help users move from findings to action.

RAC Core already produces improvement guidance through the improve and review
services. Explorer's responsibility is to present that guidance so users
understand what a finding means, why it matters, and what to do about it
(DESIGN-recommendations).

## Outcomes

- Repository findings are presented with explanation, impact, and a suggested
  action.
- Users can prioritize attention using severity supplied by Core.
- Recommendations remain advisory; Explorer never applies changes.

## Initiatives

### Initiative 1 — Recommendation Categories

Present recommendations across the categories defined by
DESIGN-recommendations:

- Validation: missing sections, invalid metadata
- Relationships: broken references, missing links
- Repository health: orphaned artifacts, low traceability
- Quality: missing success measures, weak acceptance criteria

### Initiative 2 — Recommendation Presentation

Each recommendation presents:

- the finding
- why it matters (impact)
- a suggested action
- navigation to the affected artifacts

Explain before suggesting: users should understand a finding before being
asked to act on it.

### Initiative 3 — Severity

Present severity levels supplied by RAC Core:

- Critical
- Warning
- Suggestion

Severity definitions are maintained by Core intelligence, not by Explorer.

### Initiative 4 — Recommendation Navigation

From any recommendation, users can open the affected artifact's context view
and its related artifacts. Acting on recommendations (editor launch, export)
is delivered by v0.8.4.

## Implementation Contract

The following decisions are pinned for v0.8.3.

### Core Source

- Recommendations are RAC Core's review findings (`rac.services.review`): each
  carries a priority, a Core-supplied severity, the finding message, a
  deterministic suggested action, and the affected artifact's path. Explorer
  presents them; it computes none.
- A `review_from_portfolio` seam lets Explorer build the review from the
  already-loaded portfolio (no second walk); `build_review` delegates to it,
  with byte-identical output (golden battery).

### Presentation (explain before suggesting)

- Each recommendation shows the finding, why it matters (impact), the
  suggested action, and navigation to the affected artifact. The impact line
  is fixed presentation copy keyed by the Core finding code — display text, not
  analysis (the same role as Explorer's existing status and phase labels).
- Recommendations are grouped by category — Validation, Relationships,
  Repository Health, Quality — in that fixed order; only categories with
  findings are shown. Within a category, Core's priority order is preserved.

### Severity

- Core severities map to the three presentation tiers: `error → ✗ Critical`,
  `warning → ! Warning`, `info → · Suggestion`. Definitions stay in Core.

### Navigation and Command

- `recommendations` joins the command registry (`/recommendations`); the
  health screen gains an `r` binding to open it. Selecting a recommendation
  opens the affected artifact's context view (its related artifacts are
  reachable from there). Acting on a recommendation — editor launch, export —
  is v0.8.4.

### Scope

- Presentation plus the additive review seam: no JSON contract movement,
  existing CLI output byte-identical, no AI dependency (ADR-002). Adapter gains
  `recommendations_state`; `state.py` gains `RecommendationRow` and
  `RecommendationsState`. The explorer and review batteries absorb the tests.

## Non-Goals

- Automatic changes or artifact rewriting
- Replacement of human review
- Recommendation logic in Explorer (ADR-015)
- AI-dependent behaviour: recommendations remain available without AI
  (ADR-002)

## Success Measures

- A user can review repository recommendations, understand their impact, and
  locate every affected artifact without leaving Explorer.
- Every recommendation shown in Explorer is obtainable through existing `rac`
  commands and JSON output.

## Related Decisions

- ADR-015
- ADR-002
- ADR-003

## Related Designs

- explorer-recommendations
- explorer-health-model
- explorer-action-workflows

## Related Requirements

- rac-product-knowledge-navigator-explorer

## Dependencies

- v0.8.2 health presentation and attention items
- Existing improve and review services
