---
schema_version: 1
id: RAC-KTR5QS8Q575E
type: roadmap
---
# RAC v0.8.2 — Explorer Health

## Status

Planned

## Context

The Explorer requirement's Assess capability requires users to evaluate
repository quality, completeness, and health without running individual
commands.

RAC Core already produces the underlying intelligence through validation,
relationship analysis, repository review, statistics, and portfolio
services. Explorer's responsibility is to make that intelligence visible and
navigable — not to recalculate it (DESIGN-health-model).

## Outcomes

- Users can assess repository health at a glance and identify what requires
  attention.
- Every health signal links to the artifacts it concerns.
- Health presentation is rendered entirely from Core results; Explorer owns
  no scoring.

## Initiatives

### Initiative 1 — Health Overview

Render a repository health summary on the repository home:

```text
Health 92%

Attention

2 broken relationships
1 incomplete requirement
```

Final scoring is owned by RAC Core. Explorer shall not calculate scores,
invent findings, or override Core diagnostics.

### Initiative 2 — Health Areas

Present health across the areas defined by DESIGN-health-model:

- Completeness
- Relationships
- Validation
- Coverage

### Initiative 3 — Attention Items

Attention items shall be:

- actionable
- linked to the affected artifacts
- prioritized

Example:

```text
REQ-004  Missing Success Metrics
```

Selecting an attention item navigates to the affected artifact's context
view.

### Initiative 4 — `/health` Command

Expose health through the command surface:

```text
/health
```

using the same command registry introduced in v0.8.1.

### Initiative 5 — Accessible Status Presentation

Health states carry text labels alongside any colour or symbol:

```text
✓ Healthy
! Needs Attention
✗ Error
```

Meaning never depends on colour alone.

## Implementation Contract

The following decisions are pinned for v0.8.2.

### Health Screen

- A `HealthScreen` renders Core's health score, an overall status label, the
  four health areas (Completeness, Relationships, Validation, Coverage), and a
  prioritized, selectable attention list. Reachable from the home screen via
  `h` and from anywhere via `/health`; Esc pops back to home.
- Every value is read from the already-loaded repository model and its
  `PortfolioSummary` — no second walk, no Explorer-side scoring.

### Area Status (no invented thresholds)

- Each area's ✓ / ! / ✗ status derives from Core facts, not Explorer
  thresholds: Validation is ✗ Error when invalid artifacts exist; Completeness
  is ! Needs Attention when recommended sections are unfilled; Relationships is
  ! Needs Attention when references are broken; Coverage is ! Needs Attention
  when artifacts are orphaned. An area with no findings is ✓ Healthy.
- The overall score band label (`health_label`) is shared with the home
  summary so the two screens never disagree.

### Attention Items

- The attention list is the portfolio's `attention` items in their existing
  deterministic priority order (errors before warnings, then path, then code).
- Each item carries its severity label and the affected artifact's path;
  selecting one opens that artifact's context view (closing v0.8.1's
  display-only limitation).

### Command Surface

- `health` joins the v0.8.1 registry; `/health` opens the health screen. The
  registry contract test flips from pinning `/health` absent to pinning it
  present.

### Accessibility

- Status everywhere carries a text label beside its symbol
  (`✓ Healthy` / `! Needs Attention` / `✗ Error`); meaning never depends on
  colour (ADR-028, DESIGN-visual-system).

### Scope

- Presentation only: no Core or service changes, no JSON contract movement,
  existing CLI output byte-identical. Adapter gains `health_state`; `state.py`
  gains `HealthState`, `HealthAreaState`, `AttentionRow`. No new test files or
  CI battery changes — the explorer battery absorbs the coverage.

## Non-Goals

- New health intelligence or scoring algorithms in Explorer (ADR-015)
- Recommendations presentation (v0.8.3)
- Automatic remediation

## Success Measures

- A user can answer "what is the overall health of this repository?" and
  "what requires attention?" without leaving Explorer.
- Every health value shown in Explorer is obtainable through existing `rac`
  commands and JSON output.
- Health rendering involves no Explorer-side calculation beyond formatting.

## Related Decisions

- ADR-015
- ADR-003

## Related Designs

- explorer-health-model
- explorer-visual-system

## Related Requirements

- rac-product-knowledge-navigator-explorer
- rac-repository-review-mode

## Dependencies

- v0.8.0 repository model and diagnostics objects
- v0.8.1 repository home and command surface
- Existing validation, relationships, review, stats, and portfolio services
