Skip to main content

Module recommendations

shadow_core::diff

Module recommendations 

Source
Expand description

Prescriptive fix recommendations derived from a DiffReport.

Once Shadow has detected divergences and ranked them (see crate::diff::alignment), this module turns that raw signal into a list of actionable next-steps a reviewer can act on in under 30 seconds — the “what do I do about this?” layer. It replaces the generic “investigate turn 9” instinct with specific moves like “Restore send_confirmation_email” or “Revert refund amount 9.99 → 99.99”.

§Design decisions

  • Deterministic, rule-based. No LLM dependency in the core crate. The recommendation engine maps each divergence shape to one or more specific recommendations via pure pattern matching. An LLM- assisted “enriched” suggestion layer can live in the Python optional-extras path later, but the rule-based core must always work offline.
  • Actionable phrasing. Every recommendation starts with a verb (Restore / Remove / Revert / Review / Verify). No “consider investigating” or “you might want to”. If the rule can’t decide whether action is safe, it uses Review + rationale; it doesn’t recommend a specific action it can’t justify.
  • Hedged for non-obvious cases. Style drift → Info severity. Low-confidence signals are tagged with Verify action rather than directive Restore / Revert. The rule engine errs on the side of under-prescribing: false positives waste reviewer time more than false negatives waste engineer attention.
  • Rationale included. Every recommendation has both a short action and a one-line rationale explaining the signal that triggered it. Reviewers should never have to re-read the raw trace to understand why a recommendation appeared.

§Severity scheme (mirrors ESLint / SonarQube / Rustc)

  • Error — structural regression with high confidence (dropped or reordered tool, refusal flip). Block-merge signal.
  • Warning — decision drift (arg value change, semantic shift). Needs review before merge; may be intended.
  • Info — style drift, below-noise variance, low-confidence signals. FYI, not action-required.

Structs§

Recommendation
One prescriptive recommendation for a reviewer.

Enums§

ActionKind
The action category. Informs rendering (icon/color) and tells the reviewer what KIND of move is being suggested.
RecommendationSeverity
Severity of a recommendation. Uses the same three-tier scheme as mainstream linters / static analyzers (ESLint, SonarQube, Rustc).

Functions§

generate
Generate recommendations from a complete DiffReport.