diff --git a/INTENT.md b/INTENT.md new file mode 100644 index 0000000..a6a87b3 --- /dev/null +++ b/INTENT.md @@ -0,0 +1,399 @@ +# 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: + +```text +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 + +```text +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. + +```text +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. + +```text +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. + +```text +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. + +```text +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: + +```text +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: + +```text +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: + +```text +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: + +```text +┌─────────────────────────────────────────────────────────────┐ +│ 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: + +```text +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. + +--- + +## Guiding Statement + +**citation-work exists to turn document review into reusable evidence capture.** diff --git a/README.md b/README.md index fcd7b8f..7457775 100644 --- a/README.md +++ b/README.md @@ -1,3 +1 @@ -# repo-seed - -A git repository template to bootstrap coulomb projects from. \ No newline at end of file +A document review workspace.