generated from coulomb/repo-seed
Seeded INTENT.md
This commit is contained in:
399
INTENT.md
Normal file
399
INTENT.md
Normal file
@@ -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.**
|
||||
Reference in New Issue
Block a user