Planning Vault · Service Contract Intelligence MVP
Sanitized workflow recreation
Reading view27 links9 sections↗⋮
00-Shared › Initiatives › 10 Evaluating › Service Contract Intelligence MVP › 00 Idea

Service Contract Intelligence MVP

Canonical idea · detailed evaluation consolidated from pruned session context and explicit user decisions

typeidea
statusapproved
initiative_idSCI-MVP-001
lifecycle10 Evaluating
sourcepruned session brief
decision_date2026-07-24
preferred_implementerpi
preferred_reviewerhermes
Approved by explicit user decisionThe evaluation is durable in this canonical note. Approval authorizes specification planning only—not implementation, handoff, review, commit, push, deployment, or production access.

Executive summary

Create a narrow enterprise-AI MVP that lets a contract-review analyst upload one synthetic service contract, inspect cited obligations and renewal dates, ask grounded questions, and record a human review decision. The MVP tests product value and engineering ways of working without using customer data or making autonomous contract decisions.

Problem, user, and opportunity

ProblemCritical terms are distributed across long contracts, manual review is slow, and unsupported AI answers are difficult to audit.
First userContract-review analyst preparing a traceable review for a service-contract owner. Exact enterprise roles remain an assumption to validate.
OpportunityCitation-first extraction can shorten review while preserving a visible path back to source text and human judgment.
HypothesisA reviewer will trust AI assistance when every material claim is cited, uncertainty is explicit, and approval remains human-owned.

Desired outcomes and success signals

OutcomeObservable signalDecision use
Cited extractionEvery displayed obligation/date links to a source passage.Trust and auditability
Grounded answersUnsupported questions return “not found” rather than fabricated guidance.Safety boundary
Human reviewReviewer can approve, reject, or annotate the generated record.Accountability
Team adoptionArchitecture, CI starter, prompts, and handover are understandable to the next team.Sustainability

MVP scope and non-goals

In scope
  • One synthetic PDF contract
  • Obligation and renewal-date extraction
  • Citations and grounded Q&A
  • Human review record
  • Reusable architecture and tooling decision
Explicitly out of scope
  • Customer or production data
  • ERP/CRM or contract-system integration
  • Autonomous legal interpretation
  • Production SSO, scale, or SLA claims
  • Commit, push, deployment, or release authority

Evidence, assumptions, and open questions

Supports

Citation-first output makes extraction and answers inspectable; synthetic data keeps the initial evaluation bounded.

Assumption

A contract-review analyst is the correct first user and can judge whether the record meaningfully improves review speed and confidence.

Open

Source-system integration, legal sign-off, retention, model hosting, access control, and production operating ownership require later discovery.

Risks and mitigations

Unsupported answerRequire citations and explicit “not found”; never infer legal advice.high
Sensitive data exposureUse synthetic fixtures only in the MVP; production data work remains blocked.high
Tool lock-inKeep model, retrieval, and workflow boundaries replaceable and document the decision record.medium
Team handover gapDefine CI, prompts, architecture, and operating playbooks as delivery artifacts.medium

Preferred agents and independence

Implementation preference: Pi, subject to availability and workspace checks at the action boundary. Review preference: Hermes, preserving role separation when available. Preferences are sticky planning context; they are not assignments or authority.

Evaluation decision

RecommendationApprove for specification planning.
User decisionApproved after review and clarification.
ProvenanceExplicit decision recorded in this canonical note.
Authority boundaryImplementation and publication: false.

Specification handoff

Carry the validated problem, success signals, risks, scope, non-goals, agent preferences, and unresolved assumptions into [[Service Contract Intelligence MVP — Specification]]. Do not infer production architecture or execution authority.

checkpoint_contract
checkpoint_version1
initiative_idSCI-MVP-001
canonical_artifacts[[Service Contract Intelligence MVP]]
completed_stageidea decision
current_statusidea approved · initiative evaluating
first_incomplete_dependencyspecification decision
next_actiondevelop specification
decision_provenanceEvaluation Decision · approved by user · 2026-07-24
authority_boundaryplanning only · no execution authority
Reading view41 links14 sections↗⋮
00-Shared › Initiatives › 10 Evaluating › Service Contract Intelligence MVP › 10 Specification

Service Contract Intelligence MVP — Specification

Canonical specification · testable system boundary generated from one verified approved idea

typespecification
statusapproved
initiative_idSCI-MVP-001
version0.1 planning baseline
source_idea[[Service Contract Intelligence MVP]]
decision_date2026-07-24
data_classsynthetic only
next_stageticket planning
Approved for ticket planningRequirements, system boundaries, failure behavior, testing, and non-goals are durable enough to decompose into tickets. No handoff, implementation, commit, deployment, or production authority is created.

Document control and traceability

Source: [[Service Contract Intelligence MVP]] · Idea decision: approved by user · Specification decision: approved by user · State: initiative evaluating.
00-Shared/Initiatives/10 Evaluating/Service Contract Intelligence MVP/10 Specification/Service Contract Intelligence MVP — Specification.md

System context and proposed architecture

Synthetic contractsingle PDF fixture
→
Ingestionparse + normalize
→
Contract indexchunks + provenance
→
AI servicesextract + grounded Q&A
→
Review workspacecitations + human decision

Boundary: adapters isolate model and retrieval choices; the MVP stores only synthetic fixtures, derived citations, prompts by version, and reviewer actions. Production identity, integration, and scale are deferred.

Actors and critical user stories

US-01

As a contract-review analyst, I can import one synthetic contract and confirm its source identity before analysis.

US-02

I can inspect obligations and renewal dates with exact source citations and visible confidence/uncertainty.

US-03

I can ask a question and receive a grounded answer or an explicit “not found” response.

US-04

I can approve, reject, or annotate the AI-generated review while preserving an audit record.

Domain vocabulary and implementation decisions

FindingA proposed obligation, date, or clause interpretation that is never accepted without supporting evidence and human review.
Evidence spanAn immutable source passage identified by document checksum, page, and offsets.
Grounded answerAn answer assembled only from retrieved evidence spans; otherwise the result is “not found”.
Review recordA versioned human action that approves, rejects, or annotates a finding without changing its source.

Decisions: keep ingestion, retrieval, model inference, and review storage behind replaceable interfaces; treat prompts as versioned configuration; preserve provenance from source checksum to reviewer action.

Functional requirements and acceptance checks

IDRequirementAcceptance check
FR-01Import one approved synthetic PDF and record a stable source identifier.fixture identity retained
FR-02Extract obligations, responsible party, relevant date, and source passage.all fields + citation
FR-03Extract renewal/termination dates without calculating unsupported legal meaning.date + exact source
FR-04Answer questions only from indexed contract evidence.answer cites evidence
FR-05Return “not found” when retrieved evidence cannot support an answer.negative fixture passes
FR-06Record human approval, rejection, annotation, timestamp, and source version.review event durable

Data and interface contracts

ContractDocumentdocument_id, filename, checksum, pages, imported_at
EvidenceSpandocument_id, page, start, end, text, checksum
ContractFindingtype, value, party, date, evidence_ids, status
ReviewEventfinding_id, action, note, actor, timestamp, version

Security, privacy, and governance

  • Accept only the supplied synthetic fixture in the MVP.
  • Keep prompts and model configuration versioned; exclude credentials and raw private conversations.
  • Reject unsupported file types and redact stack details from user-facing errors.
  • Require a human review event before a result is considered accepted.
  • Treat future customer-data ingestion, SSO, retention, and legal review as separate approval-gated work.

Non-functional and operational requirements

IDRequirementAcceptance check
NFR-01Preserve a deterministic source-to-output provenance chain for every accepted result.replayable trace
NFR-02Keep model and retrieval providers replaceable through explicit adapter contracts.provider swap test
NFR-03Emit structured events for ingestion, extraction, answer generation, and human review.event schema valid
NFR-04Complete the synthetic happy-path demonstration within an agreed local evaluation budget.budget recorded

Failure and recovery behavior

Parsing failsStop analysis, retain source identity, show a safe actionable error.
Citation is missingDo not display the finding as supported; route it for human review.
Grounding is insufficientReturn “not found”; do not substitute model memory.
Model call failsRetry only within bounded policy; preserve the prior human-reviewed record.
RollbackRestore the previous prompt/config version without losing source or review history.

Testing strategy and release evidence

LayerRepresentative evidenceGate
Unitschema validation, source offsets, “not found” policyrequired
Integrationsynthetic PDF → findings → citations → review eventrequired
Evaluationgolden obligations/dates and unsupported-question fixturerequired
Securityfile rejection, prompt/version handling, safe errorsrequired
Human acceptanceanalyst can verify every material result from the sourcerequired

Proposed delivery structure

V1-S1 · Contract insight MVPCited extraction, grounded Q&A, human review, focused tests.First eligible implementation batch after a separate handoff and authorization.
V1-S2 · Engineering adoption kitArchitecture record, tooling rationale, CI starter, prompt and handover playbooks.Later batch; not automatically authorized or started.

Migration, rollout, observability, and rollback

Local evaluationRun against the frozen synthetic fixture, versioned prompts, and a recorded expected-result set.
ObservabilityTrack source checksum, pipeline version, model/config version, latency, citation coverage, and review outcome.
Rollout gateNo customer-data pilot until security, legal, identity, retention, and operating ownership are separately approved.
RollbackRestore the prior prompt/config and schema-compatible review view; retain source and human-review history.

Acceptance and kill criteria

Accept when
  • Every material result has a usable citation
  • Unsupported questions fail safely
  • Human review is durable and reversible
  • Boundaries and handover are documented
Stop or rethink when
  • Citations cannot reliably support findings
  • Synthetic evaluation cannot represent the workflow
  • Required controls make the MVP infeasible
  • Tooling cannot be handed to the target team

Specification decision

RecommendationApprove for ticket planning.
User decisionApproved after scope and recovery review.
AcceptanceRequirements are independently checkable.
Authority boundaryImplementation and handoff: false.
checkpoint_contract
checkpoint_version1
initiative_idSCI-MVP-001
canonical_artifacts[[Service Contract Intelligence MVP]], [[Service Contract Intelligence MVP — Specification]]
completed_stagespecification decision
current_statusspec approved · initiative evaluating
first_incomplete_dependencyticket-plan decision
next_actiondevelop reviewed ticket bundle
decision_provenanceSpecification Decision · approved by user · 2026-07-24
authority_boundaryplanning only · no handoff or execution