Drafting Engine

Relevant source files

The following files were used as context for generating this wiki page:

• lib/drafting/generate.ts
• lib/drafting/contribution.ts
• lib/drafting/repository.ts
• app/api/drafts/route.ts
• app/opportunities/[id]/draft-panel.tsx
• lib/db/schema.ts

The Drafting Engine generates and manages evidence-backed contributions or research briefs for social listening opportunities. It ensures that every generated sentence remains grounded in specific evidence documents and adheres to community-specific AI policies. The engine transitions drafts through states of generation, user editing, and final approval for handoff to social platforms.

Architecture and Data Flow

The Drafting Engine operates as a pipeline between the Opportunity Queue and external social platforms. It utilizes Large Language Models (LLMs) via the AI Gateway or deterministic local logic to produce text.

Components and Key Functions

• generateContribution: Coordinates the LLM pipeline, including triage and validation. It returns a GeneratedDraft or falls back to a research brief if rules prohibit AI text.
  • Sources: [lib/drafting/contribution.ts:107-130](https://github.com/sodown4thecause/vantage/blob/86aefd48162fae92ec050a94174ef8121f8c5ea2/lib/drafting/contribution.ts#L107-L130)
• validateContribution: Enforces lexical similarity checks against existing replies and verifies that every factual claim in the draft contains a verbatim quote from the evidence.
  • Sources: [lib/drafting/contribution.ts:28-85](https://github.com/sodown4thecause/vantage/blob/86aefd48162fae92ec050a94174ef8121f8c5ea2/lib/drafting/contribution.ts#L28-L85)
• generateGroundedDraft: Provides a deterministic, non-LLM alternative that builds a draft by concatenating workspace product material with specific evidence snippets.
  • Sources: [lib/drafting/generate.ts:74-124](https://github.com/sodown4thecause/vantage/blob/86aefd48162fae92ec050a94174ef8121f8c5ea2/lib/drafting/generate.ts#L74-L124)

Draft Quality and Classification

The engine classifies every output into one of three specific kinds stored in the ContributionReview object.

Kind	Description	Use Case
draft	Ready-to-post prose for human review.	Standard actionable opportunities.
brief	A research brief containing reference material.	Prohibited AI venues or discovery-only evidence.
abstain	A recommendation not to reply.	When the AI adds no new value or repeats existing replies.

Sources: [lib/drafting/generate.ts:55-57](https://github.com/sodown4thecause/vantage/blob/86aefd48162fae92ec050a94174ef8121f8c5ea2/lib/drafting/generate.ts#L55-L57), [lib/drafting/contribution.ts:29-33](https://github.com/sodown4thecause/vantage/blob/86aefd48162fae92ec050a94174ef8121f8c5ea2/lib/drafting/contribution.ts#L29-L33)

Validation and Grounding Logic

To maintain technical accuracy, the engine validates LLM outputs against strict grounding rules.

Claim Verification

The validateContribution function requires an evidence claim ledger. Every complete factual statement, question, or recommendation in the draft must appear in the claims array with a matching documentId and a verbatim quote from that document.
Sources: [lib/drafting/contribution.ts:50-70](https://github.com/sodown4thecause/vantage/blob/86aefd48162fae92ec050a94174ef8121f8c5ea2/lib/drafting/contribution.ts#L50-L70)

Flagging and Softening

The engine flags unsupported absolute claims (e.g., "guaranteed", "best in the world") using flagUnsupportedClaims. It can automatically soften these terms during the deterministic generation process.
Sources: [lib/drafting/generate.ts:126-148](https://github.com/sodown4thecause/vantage/blob/86aefd48162fae92ec050a94174ef8121f8c5ea2/lib/drafting/generate.ts#L126-L148)

Duplicate Detection

The engine performs a lexical comparison between the new draft and existing replies in the thread. If the shared tokens exceed 80%, the engine throws a ContributionValidationError to prevent repetitive content.
Sources: [lib/drafting/contribution.ts:44-48](https://github.com/sodown4thecause/vantage/blob/86aefd48162fae92ec050a94174ef8121f8c5ea2/lib/drafting/contribution.ts#L44-L48)

Data Model and Repository

Drafts are persisted in the opportunity_draft table. The repository manages the state, ensuring that edits and approvals are scoped to the correct workspace and opportunity.

Repository Actions

• createDraftForOpportunity: Fetches the workspace monitoring profile and opportunity details to initiate generation.
  • Sources: [lib/drafting/repository.ts:60-106](https://github.com/sodown4thecause/vantage/blob/86aefd48162fae92ec050a94174ef8121f8c5ea2/lib/drafting/repository.ts#L60-L106)
• approveDraftForHandoff: Validates the draft one final time before setting approvedAt. It checks if the community rules and facts were manually reviewed by the user.
  • Sources: [lib/drafting/repository.ts:153-200](https://github.com/sodown4thecause/vantage/blob/86aefd48162fae92ec050a94174ef8121f8c5ea2/lib/drafting/repository.ts#L153-L200)
• getLatestDraft: Retrieves the most recent draft, optionally scoped to a specific targetDocumentId.
  • Sources: [lib/drafting/repository.ts:108-126](https://github.com/sodown4thecause/vantage/blob/86aefd48162fae92ec050a94174ef8121f8c5ea2/lib/drafting/repository.ts#L108-L126)

API Operations

The system exposes draft management through the /api/drafts endpoint.

Method	Action	Parameters	Description
GET	N/A	workspaceId, opportunityId, targetDocumentId	Retrieves the latest draft for an opportunity.
POST	create	opportunityId, targetDocumentId, rulesReviewed	Generates a new draft.
POST	update	draftId, editedText	Saves user modifications to the draft.
POST	approve	draftId, rulesReviewed, factsReviewed	Finalizes the draft for clipboard copy.

Sources: [app/api/drafts/route.ts:11-105](https://github.com/sodown4thecause/vantage/blob/86aefd48162fae92ec050a94174ef8121f8c5ea2/app/api/drafts/route.ts#L11-L105)

Handoff Logic

During the approval process, the engine checks the community policy again. If a venue (like Hacker News or Stack Overflow) prohibits AI text, the engine blocks the approve action for draft types, allowing only brief types to proceed as reference material.
Sources: [lib/drafting/repository.ts:173-178](https://github.com/sodown4thecause/vantage/blob/86aefd48162fae92ec050a94174ef8121f8c5ea2/lib/drafting/repository.ts#L173-L178), [lib/drafting/contribution.ts:98-103](https://github.com/sodown4thecause/vantage/blob/86aefd48162fae92ec050a94174ef8121f8c5ea2/lib/drafting/contribution.ts#L98-L103)

Conclusion

The Drafting Engine serves as a safety-first generation layer. It prioritizes human review and factual grounding over automated posting. By strictly enforcing citation quotes and community rules, the engine reduces the risk of hallucinations and ensures that contributions add distinct value to developer conversations.