Document rule engine API and default rule templates

epic-scenario-based-follow-up-prompts-core-logic-task-014 — Write developer documentation for the ScenarioRuleEngine public API including: evaluate() parameter contracts and return type, EvaluationResult reason code enum with descriptions, ScenarioRule JSON schema with annotated examples for the five most common HLF follow-up scenarios (post-initial-contact, post-long-session, wellbeing-flag-raised, no-contact-after-10-days, post-group-activity), and configuration manager seeding behaviour. Store as inline Dart doc comments and a markdown reference in the docs/ folder.

medium priority low complexity documentation pending documentor Tier 6

Acceptance Criteria

ScenarioRuleEngine class has a Dart doc comment block (///) on the class declaration describing its purpose

evaluate() method has a Dart doc comment documenting: all parameters with @param equivalents, return type with @returns, and possible thrown exceptions

EvaluationResult enum has a Dart doc comment on the enum declaration and on each individual value explaining when it is returned

docs/scenario-rule-engine.md exists and is written in English

The markdown document includes the full ScenarioRule JSON schema in a fenced code block

The markdown document includes 5 annotated JSON examples — one for each HLF scenario: post-initial-contact, post-long-session, wellbeing-flag-raised, no-contact-after-10-days, post-group-activity

Each JSON example has prose annotations (above or inline comments) explaining the trigger_conditions and prompt_content choices

The markdown document describes ScenarioConfigurationManager seeding behaviour: when seeding occurs, what default templates are seeded, and how to override defaults

All documentation is in English regardless of source material language

Technical Requirements

frameworks

Dart

Flutter

data models

ScenarioRuleEngine

EvaluationResult

ScenarioRule

ScenarioConfigurationManager

security requirements

JSON examples must use synthetic/fictional data — no real contact IDs, user IDs, or PII from HLF

Document must not expose internal Supabase table structure beyond what is needed for integration

Execution Context

Execution Tier

Tier 6

Tier 6 - 158 tasks

Can start after Tier 5 completes

View Full Execution Plan

Implementation Notes

Write Dart doc comments using the /// triple-slash style, not /** */ blocks, to align with Dart conventions. For the markdown file, use a structure with sections: Overview, evaluate() API Reference, EvaluationResult Codes, ScenarioRule JSON Schema, Default Rule Templates (5 examples), and Seeding Behaviour. The five HLF scenarios map to the real use cases described in the workshop summary: post-initial-contact (first contact completed, prompt to follow up within 3 days), post-long-session (session > 60 min, check-in prompt), wellbeing-flag-raised (coordinator flagged concern during activity), no-contact-after-10-days (Blindeforbundet 10-day reminder — adapt for HLF context), post-group-activity (group session completed, individual follow-up prompt). Keep examples realistic but use placeholder IDs like 'chapter-hlf-demo'.

Testing Requirements

No automated tests required for documentation. However, verify that: (1) dart doc generates without warnings for the documented classes (run dart doc --dry-run); (2) all 5 JSON examples in the markdown are valid JSON (validate with a JSON linter); (3) cross-references in the markdown to EvaluationResult enum values match the actual enum value names in code.

Component

Scenario Rule Engine

service high

Dependencies (2)

Wire all three services into the Riverpod provider graph: scenarioRuleEngineProvider (depends on scenarioRuleRepositoryProvider and promptHistoryRepositoryProvider), scenarioConfigurationManagerProvider (depends on scenarioRuleRepositoryProvider), and scenarioDeepLinkHandlerProvider (depends on promptHistoryRepositoryProvider and go_router). Ensure providers are scoped correctly for multi-chapter support using family providers keyed by chapterId where appropriate. epic-scenario-based-follow-up-prompts-core-logic-task-013 Write integration tests that exercise the full evaluation path against a real Supabase test instance: seed scenario_rules and scenario_prompt_history records, call ScenarioRuleEngine.evaluate() via ScenarioRuleRepository and PromptHistoryRepository, assert correct rule selection including cooldown enforcement, assert EvaluationResult reason codes for non-match cases. Use flutter_test with Supabase test project credentials from CI environment. epic-scenario-based-follow-up-prompts-core-logic-task-012

Epic Risks (2)

high impact medium prob scope

The Rule Engine must support a flexible JSON rule schema that can express compound conditions (e.g., contact_type AND wellbeing_flag AND delay_days). Underestimating schema expressiveness may require breaking changes to the rule format after coordinators have already configured rules.

Mitigation & Contingency

Mitigation: Define and freeze the rule JSON schema (trigger_type enum, metadata_conditions structure, delay logic) before any implementation begins; validate schema against all known HLF scenarios documented in the feature spec.

Contingency: If schema changes are needed after deployment, implement a schema version field and a migration utility that upgrades stored rules to the new format without coordinator intervention.

medium impact medium prob technical

Deep-link navigation to the activity wizard with pre-filled arguments may fail if the user's session has expired or if the wizard route is not yet mounted in the navigator stack, causing unhandled navigation exceptions.

Mitigation & Contingency

Mitigation: Implement session state check before navigation; if session is expired, redirect to biometric/login screen and store the pending deep-link URI for post-auth redirect using go_router's redirect mechanism.

Contingency: If post-auth redirect proves unreliable, fall back to navigating to the home screen with a visible action banner that re-triggers the wizard with pre-filled arguments.

Quick Links

All Tasks Execution Plan