andreagrandi / andreagrandi/draftomen

Publish a bounded recommendation narration fact contract

Open
#452 0 comments 0 reactions 0 assignees View on GitHub
draftomen enhancement size: M
Dominant language
Python
Stars
0
Forks
0
Avg merge
1h 23m
Merged PRs (30d)
181

Description

## Problem

The narrator needs authoritative supporting facts, not arbitrary application state or an opportunity to recompute the pick.

## Proposed change

Define a versioned immutable, frontend-neutral narration input projected from the chosen recommendation and existing `PickRationale`/`PickReason` data. Include only relevant available metrics, color/commitment information, supported reasons, and a bounded set of alternatives. Distinguish missing data and uncertainty from zero or certainty. Preserve the existing deterministic explanation as fallback. Expected boundaries: `pickengine.py` data consumers, `session.py`, a focused fact-contract module, and corresponding contract/session/audit tests. Do not alter scoring or invent new confidence thresholds.

## Acceptance Criteria

- [ ] AC1: A projection check shows the selected card, available values, material reasons, and supported alternative comparisons faithfully reflect engine output.
- [ ] AC2: Missing-statistics and unsupported-synergy fixtures produce no fabricated fields or reasons; verified by fact-contract boundary tests.
- [ ] AC3: Input-size boundary tests show deterministic bounds on alternatives and text while retaining the recommended card and its essential reasons.
- [ ] AC4: Enabled-input projection versus baseline replay leaves ranking, scores, and audit evaluation identity identical; verified by session/audit comparison tests.
- [ ] AC5: A serialization/import check verifies immutable versioned inputs contain no frontend objects, external-service credentials, or arbitrary application state.

## Implementation classification

- **Estimated size:** M
- **Orchestration risk:** High
- **Reason:** This is the public factual boundary between authoritative decisions and untrusted narration.

## Dependencies

Direct prerequisites: None. Consumers: Define a fixed narration evaluation corpus and subsequent narration logic.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.