Build the constraint explanation UI #20

New issue

Open

opened 2026-07-28 04:55:05 +00:00 by claude-bot · 1 comment

claude-bot commented

2026-07-28 04:55:05 +00:00

Context

The Phase 2 acceptance criterion is explicit: "Derived constraints explain themselves in
the UI." A derived date a reviewer cannot interrogate is a date they cannot trust, and an
untrustworthy suggestion is worse than none.

Scope

Present derived evidence in the review workspace with its full reasoning chain.

Implementation notes

Derived evidence needs visual distinction from observed evidence in the evidence panel.
A reviewer must never mistake an inference for a fact.
Show the derivation in plain language: "Between photo 12 (June 1987, approved) and
photo 20 (September 1987, approved) in album Summer 1987."
Make the chain navigable â€” clicking a referenced photo opens it, so a reviewer can
verify the anchor the inference rests on.
Show the anchors' own reliability. An inference resting on low-confidence OCR is not
the same as one resting on an approved decision, and the UI should make that obvious.
Render contradiction states clearly when the engine surfaces conflicting constraints,
with a path to resolve them.
Accepting a derived date should be a deliberate act that creates a normal decision â€”
not an implicit side effect of viewing the photo.

Done when

Derived evidence is visually distinct from observed evidence
Each derived date explains its reasoning in plain language
Referenced anchor photos are navigable from the explanation
Anchor reliability is visible
Contradictions render as an actionable state
Accepting a derived date requires explicit reviewer action

References

frontend/src/pages/ReviewWorkspace
docs/circa-ui-spec.md, docs/circa-wireframes.md
docs/circa-spec.md Phase 2 acceptance criteria

Depends on: the constraint propagation engine.

## Context The Phase 2 acceptance criterion is explicit: "Derived constraints explain themselves in the UI." A derived date a reviewer cannot interrogate is a date they cannot trust, and an untrustworthy suggestion is worse than none. ## Scope Present derived evidence in the review workspace with its full reasoning chain. ## Implementation notes - Derived evidence needs visual distinction from observed evidence in the evidence panel. A reviewer must never mistake an inference for a fact. - Show the derivation in plain language: "Between photo 12 (June 1987, approved) and photo 20 (September 1987, approved) in album Summer 1987." - Make the chain navigable â€” clicking a referenced photo opens it, so a reviewer can verify the anchor the inference rests on. - Show the anchors' own reliability. An inference resting on low-confidence OCR is not the same as one resting on an approved decision, and the UI should make that obvious. - Render contradiction states clearly when the engine surfaces conflicting constraints, with a path to resolve them. - Accepting a derived date should be a deliberate act that creates a normal decision â€” not an implicit side effect of viewing the photo. ## Done when - [ ] Derived evidence is visually distinct from observed evidence - [ ] Each derived date explains its reasoning in plain language - [ ] Referenced anchor photos are navigable from the explanation - [ ] Anchor reliability is visible - [ ] Contradictions render as an actionable state - [ ] Accepting a derived date requires explicit reviewer action ## References - `frontend/src/pages/ReviewWorkspace` - `docs/circa-ui-spec.md`, `docs/circa-wireframes.md` - `docs/circa-spec.md` Phase 2 acceptance criteria Depends on: the constraint propagation engine.

claude-bot added this to the v0.4.0 milestone

2026-07-28 04:55:05 +00:00

claude-bot added the

frontend

enhancement

labels

2026-07-28 04:55:05 +00:00

claude-bot referenced this issue

2026-07-28 06:00:27 +00:00

supersede_evidence never sets superseded_by #80

claude-bot referenced this issue

2026-07-28 06:03:05 +00:00

Let a reviewer adopt an evidence date into the decision form in one click #96

claude-bot referenced this issue

2026-07-28 06:06:02 +00:00

Evidence schema cannot represent multi-parent provenance #108

claude-bot referenced this issue

2026-07-28 06:06:04 +00:00

Combined confidence scoring across evidence signals #111

claude-bot referenced this issue

2026-07-28 06:06:10 +00:00

Guided simple-review mode for non-technical reviewers #123

claude-bot referenced this issue

2026-07-28 06:07:52 +00:00

Implement the group constraint propagation engine #19

claude-bot commented

2026-07-28 06:07:52 +00:00

Author

Amended by the audit of 2026-07-28.

This UI depends on a provenance chain the schema cannot currently represent. derived_from is a
single FK; a derived range has two parents ("between photo 12 and photo 20"), which is exactly
what this UI must explain. See #108.

Related to the same explanatory goal: #111 (combined confidence scoring) provides the "single best
suggestion" this UI presents, and #96 (adopt an evidence date in one click) is the action a
reviewer takes once they accept the explanation.

**Amended by the audit of 2026-07-28.** This UI depends on a provenance chain the schema cannot currently represent. `derived_from` is a single FK; a derived range has **two** parents ("between photo 12 and photo 20"), which is exactly what this UI must explain. See #108. Related to the same explanatory goal: #111 (combined confidence scoring) provides the "single best suggestion" this UI presents, and #96 (adopt an evidence date in one click) is the action a reviewer takes once they accept the explanation.