---
schema_version: 1
id: RAC-KTYZNGTPER8K
type: roadmap
---
# RAC v0.12.1 — Intent Analysis

## Status

Planned

## Context

Repository comparison (v0.12.0) answers what changed. Reviewers of
product knowledge care about a different question: what changed, and
why might it matter? Raw artifact diffs do not surface a requirement
becoming vague, a constraint quietly weakening, or acceptance criteria
disappearing.

This milestone adds deterministic intent analysis on top of the
comparison model. Every check is a pure, explainable function of the
two repository states — no scoring, no semantics, no model calls —
consistent with RAC's structural-validation posture. Findings describe
product impact; they do not judge correctness.

## Outcomes

- Modified, added, and removed artifacts are screened for clarity
  regressions: measurable requirements becoming vague, mandatory
  language weakening, ambiguous wording arriving, acceptance criteria
  or success measures disappearing.
- Relationship impact of a change is surfaced: which artifacts
  reference the thing that changed, and which new scope arrives with no
  supporting context.
- Findings carry stable codes, severities, evidence, and artifact
  locations so downstream consumers (Watchkeeper recommendations, CI,
  agents) can act on them without parsing prose.

## Initiatives

### Initiative 1 — Intent Analysis Service

`analyze_intent(comparison)` in the services layer consumes the
v0.12.0 comparison model and produces a deterministic, stably ordered
list of findings. All text checks are token-boundary and casefolded;
section checks read the parsed artifact sections, not raw Markdown.

### Initiative 2 — Finding Vocabulary

Finding codes reuse the policy vocabulary of the Product Intent CI
requirement so future policy configuration needs no translation layer:
`specificity_regression`, `ambiguity_introduced`, `constraint_weakened`,
`constraint_removed`, `acceptance_criteria_removed`,
`success_measures_removed`, `relationship_impact`, `unlinked_scope`.

### Initiative 3 — Watchkeeper Surface

The watchkeeper report and command gain an additive `findings` array
(JSON) and a Findings block (human output). No new flags; the same
comparison drives everything.

### Initiative 4 — Contract Battery

An intent battery covers each check positively and negatively (the
boundary cases that must not fire), and the extended fixtures plus
refreshed goldens pin the finding contract end to end.

## Constraints

- Every check is deterministic and explainable from artifact text and
  the existing comparison model; no semantic scoring (ADR-015 and the
  structural-validation principle).
- The `findings` JSON array is additive to the v0.12.0 contract
  (ADR-007).
- Findings never change the exit code in this milestone; policy arrives
  with v0.12.2.

## Non-Goals

- Review recommendations or exit-code policy (v0.12.2)
- Generated review comments or GitHub integration (v0.12.3)
- Semantic similarity, embeddings, or model-assisted judgement
- Configurable term lists or policies — the vocabulary is pinned here
  and revisited only by a recorded decision

## Implementation Contract

The following decisions are pinned for v0.12.1.

### Module Location and Model

- `src/rac/services/intent.py` — `IntentFinding` (code, severity
  `warning` | `info`, path, identifier, detail, evidence) and
  `analyze_intent(comparison) -> list[IntentFinding]`.
- Ordering: warnings before info, then code, then path.

### Checks

- `specificity_regression` (warning): a modified requirement line whose
  old text contains a digit and whose new text contains none.
- `ambiguity_introduced` (warning): an ambiguity term newly present in
  an added or modified requirement line. The term list is a module
  constant: easy, intuitive, simple, seamless, user-friendly, scalable,
  fast, quickly, robust, flexible.
- `constraint_weakened` (warning): a modified requirement line where a
  mandatory token (must, shall) disappears and a hedge token (should,
  may, could) appears.
- `constraint_removed` (warning): a removed requirement whose text
  carried a mandatory token.
- `acceptance_criteria_removed` / `success_measures_removed` (warning):
  the corresponding parsed section is non-empty in base and absent or
  empty in head for a modified artifact.
- `relationship_impact` (info): a modified or removed artifact that
  other artifacts reference; evidence lists the referencing artifacts.
- `unlinked_scope` (warning): an added artifact of a known type with no
  relationships in the head state — neither outgoing declared nor
  incoming resolved.

## Success Measures

- Each check fires on its planted fixture case and stays silent on the
  adjacent negative case, pinned by the intent battery.
- The requirement's worked examples (upload time regression,
  must-to-should weakening, seamless-checkout ambiguity) reproduce as
  findings with the documented codes.
- Refreshed goldens show findings rendered identically across runs.

## Risks

- Lexical checks produce false positives (a digit lost in a wording
  cleanup is not always a regression). Accepted: findings are
  informational flags for human attention, never verdicts, and the
  detail sentence says exactly what triggered.
- Term lists invite endless tuning. Mitigated: the list is pinned in
  this contract; changes require a corpus edit, not a code tweak.

## Assumptions

- Part of the watchkeeper series originally drafted as v0.9.x and
  renumbered to v0.12.x (see v0.12.0 for the renumbering record).
- The v0.12.0 comparison model carries enough context (products, raw
  text, repositories for both sides) that intent analysis needs no
  additional corpus walk.

## Related Decisions

- ADR-007
- ADR-015
- ADR-027

## Related Requirements

- rac-product-intent-ci-watchkeeper

## Related Roadmaps

- v0.12.0-repository-review
