---
schema_version: 1
id: RAC-KV2E58EPZ7N5
type: roadmap
---
# RAC v0.13.3 — Cadence Nudge

## Status

Planned

## Context

Retention dies when writing stops. A team adopts RAC, captures a burst
of decisions, then drifts — and nothing in the tool notices or nudges.
With git-derived recency available (v0.13.2), `rac review` can surface a
gentle, advisory cadence signal: the corpus, or a part of it, has not
been written to in a while.

This is deliberately a nudge, not a gate. ADR-017 is explicit that RAC
manages knowledge, not work — it does not track status, assignees, or
deadlines. A staleness finding risks reading as work tracking, so this
milestone keeps it firmly advisory: off by default, informational
severity, never failing a review on its own. ADR-045 frames recency as a
capture-cadence signal precisely so this finding stays on the right side
of ADR-017. It tells a user "you have not recorded a decision in two
weeks", which is about the writing habit, not about whether any unit of
work is done.

## Outcomes

- `rac review --stale-after DAYS` surfaces an advisory finding when the
  corpus has had no new or updated artifact within the window, nudging
  the user back to the keyboard.
- The nudge is off by default and never changes a review's exit code:
  enabling it adds an informational finding, it never turns a green
  review red.
- The threshold is the user's to set, defaulting to fourteen days ("two
  weeks") when the flag is given without a value, so the common cadence
  is one keystroke.
- The signal respects ADR-017: it is about capture cadence, phrased as a
  writing-habit prompt, not a work-status or deadline check.

## Initiatives

### Initiative 1 — Cadence Finding in Review

`build_review` gains an optional `stale_after_days` parameter. When set,
it consults the recency service (v0.13.2) and, if the most recent
artifact (overall, and optionally per decision type) is older than the
window, emits an informational finding at the lowest priority with a
deterministic next step (`rac quickstart` or `rac new decision`). When
unset, review behaves exactly as today.

### Initiative 2 — `--stale-after` Flag

`rac review --stale-after [DAYS]` enables the nudge; the value defaults
to 14 when the flag is present without a number. Without the flag the
nudge is absent. The finding is rendered by the existing review human and
JSON paths, carrying the standard finding shape (priority, severity,
code, message, action, impact).

### Initiative 3 — Habit-Framed Messaging

The finding's message and impact are written as a writing-habit prompt
("No new product knowledge recorded in the last N days"), not as a
work-status warning, keeping the feature inside ADR-017's boundary.

## Constraints

- Off by default: review with no `--stale-after` is byte-identical to
  today's output and exit code.
- Informational only: the cadence finding never satisfies the priority
  1–2 condition that fails a review, so it cannot break CI.
- Built entirely on the v0.13.2 recency service; review gains no git
  import of its own (ADR-043's boundary).
- When recency is unknown (no git, untracked files), the nudge is
  suppressed rather than firing on missing data.

## Non-Goals

- Per-artifact staleness findings for every file (the headline signal is
  corpus-level cadence; per-type may follow but is not promised here).
- A failing exit code for staleness, now or via a flag.
- A frontmatter "last reviewed" field or any stored date (ADR-045).
- Scheduling, reminders outside the CLI, or notifications (the
  commit-time nudge in v0.13.4 is the only ambient prompt).

## Implementation Contract

The following decisions are pinned for v0.13.3.

### Flag

- `rac review --stale-after [DAYS]`: `DAYS` is an optional non-negative
  integer defaulting to 14. Absent flag → nudge disabled.
- Invalid `DAYS` (negative, non-integer) is a usage error (exit 2),
  matching the CLI's argument-validation convention.

### Finding

- Code `stale-corpus`, severity `info`, priority below all existing
  findings, with action `Run: rac quickstart` (empty corpus) or
  `Run: rac new decision <path>` (non-empty but stale).
- Message frames cadence: "No product knowledge recorded in the last N
  days." Impact: writing-habit framing, not work status.
- Emitted only when recency is known and the newest artifact is older
  than the window; suppressed when recency is unknown.

### Exit code

- Review exit code is unchanged by the nudge: `ok` stays governed by
  priority 1–2 findings only.

## Success Measures

- `rac review` without the flag produces identical output and exit code
  to the prior release on the same corpus.
- `rac review --stale-after 14` on a corpus whose newest artifact is 20
  days old emits the `stale-corpus` info finding and still exits 0.
- The same command on a corpus written to yesterday emits no cadence
  finding.
- In a non-git directory, `--stale-after` produces no cadence finding and
  no error.

## Risks

- A staleness finding could be read as work tracking, against ADR-017.
  Mitigated: off by default, informational, habit-framed, and recorded
  against ADR-045's capture-cadence framing.
- A noisy nudge could annoy and reduce trust. Mitigated: it fires once at
  corpus level, only when explicitly enabled, and never blocks.

## Assumptions

- The recency service (v0.13.2) is available and returns timezone-aware
  timestamps.
- Fourteen days is a reasonable default cadence for "recording a
  decision"; users who disagree set their own window.

## Related Decisions

- adr-007
- adr-015
- adr-017
- adr-045

## Related Requirements

- rac-growth-adoption

## Related Roadmaps

- v0.13.2-git-recency
- v0.13.4-commit-nudge
