Reference

Review Signals

Version: N/A
Status: N/A
Lineage: N/A

Review signals are deterministic indicators computed from requirement text and trace links. Each signal is normalized to a 0.0–1.0 range and stored with metadata that lists the requirement IDs that triggered it (plus the specific match reasons). These signals are used to rank review units by attention score.

Signal vector

The signal vector contains seven normalized values plus a total_requirements count:

  • cross_cutting_refs
  • ambiguity_density
  • safety_keyword_score
  • mode_coverage
  • trace_orphan_ratio
  • requirement_density_score
  • negation_complexity
  • total_requirements

Normalization and rules

Cross-cutting references

  • Raw: count of trace links (upstream or downstream) that point outside the current review unit.
  • Normalized: raw_count / (5 * unit_size) capped at 1.0.
  • Matched items: requirement IDs with at least one external link.

Ambiguity density

  • Raw: number of requirements that match any ambiguity rule.
  • Normalized: raw_count / total_requirements.
  • Matched items: requirement IDs with ambiguity patterns or missing conditions.

Ambiguity patterns:

  • Vague quantifiers: some, various, appropriate, adequate, sufficient, reasonable, normal, typical
  • TBD markers: TBD, TBC, to be determined, to be confirmed, to be defined
  • Passive without actor: shall be provided|performed|implemented|executed|conducted
  • Missing conditions rule: a sentence contains shall or must but no when, if, unless, while, or during.

Safety keyword score

  • Raw: average of the highest-weight safety keyword matched per requirement.
  • Normalized: capped at 1.0.
  • Matched items: requirement IDs with any safety keyword.

Keyword weights:

  • Critical (1.0): hazard, hazardous, catastrophic, no single failure, common cause, fail-safe, safety requirement, DAL, level A/B.
  • High (0.7): major, minor, criticality, design assurance, failure/fault/loss, unavailable, out of range.
  • Medium (0.4): alert, warning, monitor, integrity, availability, reliability, redundancy, protection, shutdown, override.

Mode coverage

  • Raw: unique expected modes found in requirement text.
  • Normalized: raw / expected_modes_count.
  • Matched items: requirement IDs that introduce a new expected mode.

Expected modes: normal, degraded, emergency, startup, shutdown.

Trace orphan ratio

  • Raw: count of requirements with neither upstream nor downstream links.
  • Normalized: raw / total_requirements.
  • Matched items: orphan requirement IDs.

Requirement density score

  • Raw: total_requirements.
  • Normalized: ideal range 15–50; linear penalty outside the range. Values are clamped to 0–1.

Negation complexity

  • Raw: count of requirements with multiple simple negations or any complex negation pattern.
  • Normalized: raw / total_requirements.
  • Matched items: requirement IDs with complex or multiple negations.

Negation patterns:

  • Simple: not, no, never, none, neither, nor
  • Complex: shall not|must not|cannot|may not combined with unless|except|provided that.

Ranking behavior

The ranking logic applies signal weights and inverts two signals when computing attention score:

  • mode_coverage is inverted because low coverage needs attention.
  • requirement_density_score is inverted because poor density needs attention.

The default presets are defined in the ranking module and can be persisted per iteration.