citation-work/INTENT.md

INTENT

Purpose

This repository exists to provide the document review workspace for the citation-evidence ecosystem.

citation-work enables users to review collections of documents, mark relevant passages, add commentary, and create reusable evidence items that can later support form fields, claims, requirements, decisions, reports, or web publications.

It is the human-facing workbench for turning document reading into structured evidence.

---

Primary Utility

The repository provides the review and annotation user experience for citation-evidence.

It should make it easy to:

• open and navigate document collections,
• review documents efficiently,
• select relevant passages,
• create annotations,
• add commentary,
• convert annotations into evidence items,
• browse collected evidence,
• navigate from evidence items back to source context,
• prepare evidence for later binding, export, or citation rendering.

This repository turns the core model from citation-engine and the anchoring capabilities from evidence-anchor into a practical working environment.

---

Intended Users

Primary users are people who need to read documents and collect useful, source-backed evidence.

They include:

• researchers and analysts reviewing document sets,
• consultants and knowledge workers preparing reports,
• compliance, audit, procurement, and legal-adjacent workers collecting source support,
• product and requirements workers extracting evidence from source material,
• form workers preparing evidence before structured data entry,
• developers and coding agents building review workflows on top of citation-evidence.

End users should experience this repository as the place where document review happens.

---

Strategic Role

The strategic role of citation-work is to provide the first usable surface of the citation-evidence system.

It should prove that the system can support a complete evidence capture loop:

Document Collection
  → Document Viewer
  → Text Selection
  → Annotation
  → Commentary
  → Evidence Item
  → Evidence Sidebar
  → Reopen Source Context

The repository should focus on workflow quality: reducing friction between reading, noticing, marking, commenting, and later reusing evidence.

---

Core Concept

The central concept of citation-work is the review workspace.

A review workspace combines:

• a document collection,
• a document viewer,
• an annotation creation workflow,
• an evidence sidebar,
• review status,
• search and filtering,
• navigation back to source context.

The workspace should help users move from unstructured reading to structured evidence without interrupting concentration.

---

Scope

This repository should own:

• document collection review UI,
• document list and navigation UI,
• review queue behavior,
• document viewer shell composition,
• annotation toolbar and selection UX,
• evidence sidebar,
• evidence item browsing,
• review status interactions,
• evidence status interactions,
• tagging and filtering UI,
• navigation from evidence item to source context,
• review-oriented keyboard shortcuts,
• user workflows for collecting evidence before later binding or export.

It should consume domain services and types from citation-engine and anchoring/viewer contracts from evidence-anchor.

---

Out of Scope

This repository should not own the lower-level or broader system concerns.

Specifically, it should not own:

• the canonical domain model,
• persistence contracts,
• low-level selector resolution algorithms,
• PDF text extraction internals,
• Markdown or HTML ingestion pipelines,
• external source discovery,
• citation recovery logic,
• form-field binding semantics,
• visual guide overlay logic for evidence-backed forms,
• citation card rendering internals,
• product-level deployment and integration shell.

Those responsibilities belong to the appropriate subsystem repositories.

---

Architectural Position

citation-evidence
  integrated product shell and reference application

citation-work
  review workspace, annotation UX, evidence sidebar

citation-engine
  domain model, services, persistence contracts, citation rendering

evidence-anchor
  selector creation, selector resolution, highlighting contracts

evidence-source
  document ingestion, representations, source recovery

evidence-binder
  evidence-to-field / claim / requirement binding

citation-work should act as a user-facing application layer that composes capabilities from the core subsystems.

It should not redefine their domain concepts.

---

Primary Workflows

1. Open Review Collection

A user opens or creates a document collection and sees the available documents, review states, and collected evidence.

Open Collection
  → List Documents
  → Show Review Status
  → Select Document
  → Display Document in Viewer

2. Create Evidence from Selection

A user selects text in a document, creates an annotation, adds commentary, and stores it as an evidence item.

Select Text
  → Capture Selection
  → Create Selectors
  → Create Annotation
  → Add Commentary
  → Create Evidence Item
  → Show in Evidence Sidebar

3. Review Evidence

A user browses collected evidence, filters it, changes status, and jumps back to source context.

Browse Evidence
  → Filter by Document / Tag / Status
  → Select Evidence Item
  → Resolve Annotation
  → Scroll Document to Source Context
  → Highlight Passage

4. Prepare Evidence for Later Use

A user organizes evidence so that it can later be bound to fields, claims, requirements, or exported as citations.

Evidence Item
  → Add Tags
  → Set Status
  → Refine Commentary
  → Mark as Candidate / Confirmed / Needs Check

---

Initial Review States

Documents should initially support review states such as:

unreviewed
in-review
marked
relevant
rejected
needs-follow-up
cited
verified

These states may later be refined or moved into a shared model if they become central across subsystems.

---

Initial Evidence States

Evidence items shown in the review workspace should initially support states such as:

candidate
confirmed
rejected
needs-check
strong-support
weak-support
contradicts

The canonical state model should remain aligned with citation-engine.

---

Initial UI Areas

The first review workspace should likely contain:

Workspace Header
  collection name, document count, review progress

Document Navigation
  document list, filters, status indicators

Document Viewer Shell
  PDF / Markdown / HTML viewer integration

Annotation Toolbar
  create annotation, add commentary, tag, save

Evidence Sidebar
  collected evidence, comments, tags, status, source jump

Status / Filter Controls
  review status, evidence status, tags, search

Reference layout:

┌─────────────────────────────────────────────────────────────┐
│ Workspace Header                                             │
├───────────────┬───────────────────────────────┬─────────────┤
│ Document List  │ Document Viewer                │ Evidence    │
│ / Filters      │                               │ Sidebar     │
└───────────────┴───────────────────────────────┴─────────────┘

---

Design Principles

Review Flow First

The interface should minimize friction between reading, marking, commenting, and moving on.

Evidence Visibility

Collected evidence should remain visible enough that users understand what has already been captured.

Source Context Is Always Recoverable

Every evidence item should provide a direct path back to the source passage.

Format Neutrality

The review experience should work across PDFs, Markdown, HTML, and future document formats through viewer adapters.

Domain Alignment

The repository should use concepts from citation-engine rather than inventing parallel local models.

Anchoring Delegation

Selector creation, resolution, and re-anchoring should be delegated to evidence-anchor.

Progressive Complexity

The first version should support a simple review loop before adding advanced search, collaboration, or automated suggestions.

Agent Compatibility

The workflow should be explicit enough that agentic assistants can help find candidate evidence, summarize marked passages, propose tags, or identify missing evidence.

---

Expected Dependencies

This repository is expected to depend on:

citation-engine
  domain types, services, citation rendering contracts

evidence-anchor
  selection capture contracts, selector creation, annotation resolution

evidence-source
  document representations and viewer-ready sources

possibly citation-evidence
  for integration shell during reference app development

It should avoid direct dependency on evidence-binder unless building a review-to-binding bridge. Binding-specific behavior should remain outside the core review workspace.

---

First Useful Version

A first useful version of citation-work should provide:

• a simple document collection view,
• a PDF document viewer shell,
• text selection capture through an adapter,
• annotation creation flow,
• commentary input,
• evidence item creation through citation-engine,
• evidence sidebar,
• click evidence item to reopen highlighted source context,
• basic document and evidence status display.

This version should prove that a user can review a document and produce reusable evidence.

---

Success Criteria

The repository is successful when a user can efficiently perform the basic evidence capture loop:

1. open a document collection,
2. select a document,
3. read the document,
4. mark a relevant passage,
5. add commentary,
6. save it as evidence,
7. see it in the evidence sidebar,
8. return to the cited passage by clicking the evidence item.

A developer or coding agent should also be able to understand which parts of the workflow belong here and which belong to the underlying subsystems.

---

Repository Character

This repository should be:

• user-workflow-oriented,
• interface-focused,
• thin over the domain engine,
• explicit about review concepts,
• careful not to absorb core model responsibilities,
• friendly to fast MVP iteration,
• suitable for later integration into the umbrella product shell.

---

MVP Coordination — Code Lives Upstream

During the umbrella-first MVP phase (decided 2026-05-24), the source code for this subsystem does not live in this repository yet. It lives in the umbrella repo at citation-evidence/src/work/.

This INTENT.md documents the intended responsibilities and boundaries. When the review workspace UX has stabilized through actual MVP use, the corresponding code extracts into this repository.

Shared contracts (Document.reviewStatus enum, EvidenceItem.status enum, viewer adapter contract, allowed dependency edges) are maintained in the umbrella repo:

• citation-evidence/wiki/SharedContracts.md
• citation-evidence/wiki/DependencyMap.md
• citation-evidence/docs/decisions/ (ADRs)

This subsystem's eventual code must not contradict those documents. The extra evidence states (strong-support, weak-support, contradicts) mentioned in the original INTENT now live on EvidenceLink.relation, not on the item itself — see SharedContracts.md §2.5.

Under the dependency map, citation-work may depend on citation-engine, evidence-anchor, and evidence-source — but NOT on evidence-binder. The review workspace must function without form-binding logic. A separate "evidence-backed form" application composes citation-work + evidence-binder.

---

Guiding Statement

citation-work exists to turn document review into reusable evidence capture.