Wiki source code of User Needs

Last modified by Robert Schaub on 2026/02/08 08:27

author	version	line-number	content
		1	= User Needs =
		2
		3	This page defines user needs that drive FactHarbor's requirements and design decisions. Template: As a <specific user role>, I want to <action/goal>, so that I can <benefit/outcome> Purpose: User needs inform functional requirements (FR) and non-functional requirements (NFR). Each need maps to one or more requirements that fulfill it. == 1. Core Reading & Discovery == === UN-1: Trust Assessment at a Glance === As an article reader (any content type), I want to see a trust score and overall verdict summary at a glance, so that I can quickly decide if the content is worth my time to read in detail. Maps to: FR7 (Automated Verdicts), NFR3 (Transparency) === UN-2: Claim Extraction and Verification === As an article reader, I want to see the key factual claims extracted from content with verification verdicts (likelihood ranges + uncertainty ratings) for each relevant scenario, so that I can distinguish proven facts from speculation and understand context-dependent truth. Maps to: FR1 (Claim Intake), FR4 (Scenario Generation), FR7 (Automated Verdicts) === UN-3: Article Summary with FactHarbor Analysis Summary === As an article reader, I want to see an article summary (the document's position, key claims, and reasoning) side-by-side with FactHarbor's analysis summary (source credibility assessment, claim-by-claim verdicts, methodology evaluation, and overall quality verdict), so that I can quickly understand both what the document claims and FactHarbor's complete analysis of its credibility without reading the full detailed report. Maps to: FR7 (Automated Verdicts), FR6 (Scenario Comparison), FR12 (Two-Panel Summary View - Article Summary with FactHarbor Analysis Summary) ==== Example: Two-Panel Summary Layout ==== \|=ARTICLE SUMMARY\|=FACTHARBOR ANALYSIS SUMMARY \|
		4
		5	(((
		6	FactHarbor Summary: AHA Alcohol & Heart Health Statement (2025) Source: American Heart Association Scientific Statement, //Circulation//, June 2025 Credibility: Very High (peer-reviewed expert consensus) === The Big Picture === Old belief: "A glass of wine is good for your heart" New position: We're no longer sure that's true === Key Findings === \|=Drinking Level\|=Verdict \|Heavy (≥3 drinks/day)\|(% style="color:red" %)❌ Harmful – consistent across ALL studies \|Moderate (1-2 drinks/day)\|(% style="color:orange" %)❓ Uncertain – benefits may have been overstated \|None\|(% style="color:green" %)✅ Don't start drinking for heart health === Why the Shift? === Newer genetic studies (Mendelian randomization) found no evidence that moderate drinking protects the heart. The apparent benefits in older studies were likely due to lifestyle differences and methodological bias. === AHA Bottom Line ===
		7
		8	(% class="box" %)
		9	(((
		10	If you don't drink, don't start. If you do drink, keep it to ≤2/day (men) or ≤1/day (women). Focus on proven healthy behaviors instead—exercise, diet, not smoking. //The "wine for heart health" era appears to be over.//
		11	)))
		12	)))
		13
		14	~\|
		15
		16	(((
		17	FactHarbor Analysis Summary Document: AHA Scientific Statement on Alcohol and Cardiovascular Disease (2025) === Source Assessment === Credibility: (% style="color:green" %)VERY HIGH(%%) – Official AHA statement, peer-reviewed, expert panel, published in top journal (//Circulation//) === Analysis Findings === \|=Claim in Document\|=FactHarbor Verdict\|=Confidence \|Heavy drinking harms heart health\|(% style="color:green" %)STRONGLY SUPPORTED\|95% \|Moderate drinking benefits uncertain\|WELL SUPPORTED\|85% \|Prior "cardioprotective" claims overstated\|SUPPORTED\|80% \|More research needed\|APPROPRIATE\|N/A === Assessment === ✅(%%) Strengths: Transparent about methodological limitations, incorporates newer Mendelian randomization evidence, appropriately cautious, avoids overstatement (% style="color:green" %)✅(%%) Methodology: Sound synthesis of observational and genetic evidence (% style="color:orange" %)⚠️(%%) Limitation: Still relies heavily on observational data; RCT evidence limited === Verdict on the Statement Itself ===
		18
		19	(% class="box successmessage" %)
		20	(((
		21	WELL-SUPPORTED SCIENTIFIC SYNTHESIS – The AHA statement is credible, balanced, and appropriately reflects the current state of evidence. It correctly signals a shift away from previous assumptions about moderate drinking benefits without overclaiming in either direction.
		22	)))
		23
		24	Analysis ID: FH-AHA-ALCO-2025-12-17
		25	)))
		26
		27	Key Elements of Two-Panel Layout: Left Panel (Article Summary): * Document title and source * Source credibility (document's own authority) * "The Big Picture" - old belief vs. new position * "Key Findings" - document's main claims in structured format * "Why the Shift?" - document's reasoning * "Bottom Line" - document's conclusion Right Panel (FactHarbor Analysis Summary): * FactHarbor's source assessment (independent credibility check) * Claim-by-claim analysis with verdicts and confidence scores * Assessment of methodology (strengths/limitations) * Overall verdict on the document itself * Analysis ID for reference Design Principle: User sees what they claim and FactHarbor's complete analysis side-by-side without scrolling. === UN-4: Social Media Fact-Checking === As a social media user, I want to check claims in posts before sharing, so that I can avoid spreading misinformation. Maps to: FR1 (Claim Intake), FR7 (Automated Verdicts), NFR1 (Performance - fast processing) === UN-17: In-Article Claim Highlighting === As a reader viewing an article, I want to see factual claims highlighted with color-coded credibility indicators (green for well-supported, yellow for uncertain, red for refuted), so that I can immediately identify which statements are trustworthy and which require skepticism without interrupting my reading flow. Maps to: FR7 (Automated Verdicts), FR13 (In-Article Claim Highlighting), NFR1 (Performance - real-time highlighting) ==== Visual Concept ==== When reading an article on FactHarbor:
		28
		29	(% style="font-family:monospace; background-color:#f5f5f5; padding:10px; display:block;" %)
		30	(((
		31	Regular article text flows normally... (% style="background-color:#90EE90; padding:2px 5px;" %)This claim is well-supported by evidence(%%) and you can continue reading... More context and explanation... (% style="background-color:#FFD700; padding:2px 5px;" %)This claim is uncertain with conflicting evidence(%%) but the article continues... Additional information... (% style="background-color:#FFB6C6; padding:2px 5px;" %)This claim has been refuted by research(%%) and understanding that helps readers...
		32	)))
		33
		34	Hover/Click on any highlighted claim → See verdict, confidence score, and evidence summary == 2. Source Tracing & Credibility == === UN-5: Source Provenance and Track Records === As an article reader, I want to trace each piece of evidence back to its original source and see that source's historical track record, so that I can assess the reliability of the information chain and learn which sources are consistently trustworthy. Maps to: FR5 (Evidence Linking), Section 4.1 (Source Requirements - track record system) === UN-6: Publisher Reliability History === As an article reader, I want to see historical accuracy track records for sources and publishers, so that I can learn which outlets are consistently reliable over time. Maps to: Section 4.1 (Source Requirements), Data Model (Source entity with track_record_score) == 3. Understanding the Analysis == === UN-7: Evidence Transparency === As a skeptical reader, I want to see the evidence and reasoning behind each verdict, so that I can judge whether I agree with the assessment and form my own conclusions. Maps to: FR5 (Evidence Linking), NFR3 (Transparency) === UN-8: Understanding Disagreement and Consensus === As an article reader, I want to see which scenarios have strong supporting evidence versus which have conflicting evidence or high uncertainty, so that I can understand where legitimate disagreement exists versus where consensus is clear. Maps to: FR6 (Scenario Comparison), FR7 (Automated Verdicts - uncertainty factors), AKEL Gate 2 (Contradiction Search) === UN-9: Methodology Transparency === As an article reader, I want to understand how likelihood ranges and confidence scores are calculated, so that I can trust the verification process itself. Maps to: NFR3 (Transparency), Architecture (documented algorithms), AKEL (Quality Gates) == 4. Pattern Recognition & Learning == === UN-10: Manipulation Tactics Detection === As an article reader, I want to see common manipulation tactics or logical fallacies identified in content, so that I can recognize them elsewhere and become a more critical consumer of information. Maps to: AKEL (Bubble Detection), Section 5 (Automated Risk Scoring) === UN-11: Filtered Research === As a researcher, I want to filter content by verification status, confidence levels, and source quality, so that I can work only with reliable information appropriate for my research needs. Maps to: FR1 (Claim Classification), Section 4.4 (Confidence Scoring), NFR1 (Performance) == 5. Taking Action == === UN-12: Submit Unchecked Claims === As a reader who finds unchecked claims, I want to submit them for verification, so that I can help expand fact-checking coverage and contribute to the knowledge base. Maps to: FR1 (Claim Intake), Section 1.1 (Reader role) === UN-13: Cite FactHarbor Verdicts === As a content creator, I want to cite FactHarbor verdicts when sharing content, so that I can add credibility to what I publish and help my audience distinguish fact from speculation. Maps to: FR7 (Automated Verdicts), NFR3 (Transparency - exportable data) == 6. Professional Use == === UN-14: API Access for Integration === As a journalist/researcher, I want API access to verification data and claim histories, so that I can integrate fact-checking into my professional workflow without manual lookups. Maps to: Architecture (REST API), NFR2 (Scalability), FR11 (Audit Trail) == 7. Understanding Evolution & Trust Labels == === UN-15: Verdict Evolution Timeline === As an article reader, I want to see how a claim's verdict has evolved over time with clear timestamps, so that I can understand whether the current assessment is stable or recently changed based on new evidence. Maps to: FR8 (Time Evolution), Data Model (Versioned entities), NFR3 (Transparency) === UN-16: AI vs. Human Review Status === As an article reader, I want to know if the verdict was AI-generated, human-reviewed, or expert-validated, so that I can gauge the appropriate level of trust and understand the review process used. Maps to: AKEL (Publication Modes), Section 5 (Risk Tiers), Data Model (AuthorType field) == 8. User Need → Requirements Mapping Summary == This section provides a consolidated view of how user needs drive system requirements. === 8.1 Functional Requirements Coverage === (% style="width:100%" %) ~\|=(% style="width:10%" %)FR#\|=(% style="width:35%" %)Requirement\|=(% style="width:55%" %)Fulfills User Needs \|(% style="width:10%" %)FR1\|(% style="width:35%" %)Claim Intake\|(% style="width:55%" %)UN-2, UN-4, UN-12 \|(% style="width:10%" %)FR4\|(% style="width:35%" %)Scenario Generation\|(% style="width:55%" %)UN-2, UN-3 \|(% style="width:10%" %)FR5\|(% style="width:35%" %)Evidence Linking\|(% style="width:55%" %)UN-5, UN-7 \|(% style="width:10%" %)FR6\|(% style="width:35%" %)Scenario Comparison\|(% style="width:55%" %)UN-3, UN-8 \|(% style="width:10%" %)FR7\|(% style="width:35%" %)Automated Verdicts\|(% style="width:55%" %)UN-1, UN-2, UN-3, UN-4, UN-13, UN-17 \|(% style="width:10%" %)FR8\|(% style="width:35%" %)Time Evolution\|(% style="width:55%" %)UN-15 \|(% style="width:10%" %)FR11\|(% style="width:35%" %)Audit Trail\|(% style="width:55%" %)UN-14, UN-16 \|(% style="width:10%" %)FR12\|(% style="width:35%" %)Two-Panel Summary View\|(% style="width:55%" %)UN-3 \|(% style="width:10%" %)FR13\|(% style="width:35%" %)In-Article Claim Highlighting\|(% style="width:55%" %)UN-17 === 8.2 Non-Functional Requirements Coverage === (% style="width:100%" %) ~\|=(% style="width:10%" %)NFR#\|=(% style="width:35%" %)Requirement\|=(% style="width:55%" %)Fulfills User Needs \|(% style="width:10%" %)NFR1\|(% style="width:35%" %)Performance\|(% style="width:55%" %)UN-4 (fast fact-checking), UN-11 (responsive filtering), UN-17 (real-time highlighting) \|(% style="width:10%" %)NFR2\|(% style="width:35%" %)Scalability\|(% style="width:55%" %)UN-14 (API access at scale) \|(% style="width:10%" %)NFR3\|(% style="width:35%" %)Transparency\|(% style="width:55%" %)UN-1, UN-7, UN-9, UN-13, UN-15 === 8.3 AKEL System Coverage === (% style="width:100%" %) ~\|=(% style="width:45%" %)AKEL Component\|=(% style="width:55%" %)Fulfills User Needs \|(% style="width:45%" %)Quality Gates\|(% style="width:55%" %)UN-9 (methodology transparency) \|(% style="width:45%" %)Contradiction Search (Gate 2)\|(% style="width:55%" %)UN-8 (understanding disagreement) \|(% style="width:45%" %)Bubble Detection\|(% style="width:55%" %)UN-10 (manipulation tactics) \|(% style="width:45%" %)Publication Modes\|(% style="width:55%" %)UN-16 (AI vs. human review status) \|(% style="width:45%" %)Risk Tiers\|(% style="width:55%" %)UN-16 (appropriate review level) === 8.4 Data Model Coverage === (% style="width:100%" %) ~\|=(% style="width:45%" %)Entity\|=(% style="width:55%" %)Fulfills User Needs \|(% style="width:45%" %)Source (with track_record_score)\|(% style="width:55%" %)UN-5, UN-6 (source reliability) \|(% style="width:45%" %)Scenario\|(% style="width:55%" %)UN-2, UN-3, UN-8 (context-dependent truth) \|(% style="width:45%" %)Verdict (with likelihood_range, uncertainty_factors)\|(% style="width:55%" %)UN-1, UN-2, UN-3, UN-8 (detailed assessment) \|(% style="width:45%" %)Versioned entities\|(% style="width:55%" %)UN-15 (evolution timeline) \|(% style="width:45%" %)AuthorType field\|(% style="width:55%" %)UN-16 (AI vs. human status) == 9. User Need Gaps & Future Considerations == This section identifies user needs that may emerge as the platform matures: Potential Future Needs: * Collaborative annotation: Users want to discuss verdicts with others * Personal tracking: Users want to track claims they're following * Custom alerts: Users want notifications when tracked claims are updated * Export capabilities: Users want to export claim analyses for their own documentation * Comparative analysis: Users want to compare how different fact-checkers rate the same claim When to address: These needs should be considered when: 1. User feedback explicitly requests them 2. Usage metrics show users attempting these workflows 3. Competitive analysis shows these as differentiators Principle: Start simple (current User Needs), add complexity only when metrics prove necessity. == 10. Related Pages == * [[Requirements>>Archive.FactHarbor 2026\.01\.20.Specification.Requirements.WebHome]] - Parent page with roles, rules, and functional requirements * [[Architecture>>Archive.FactHarbor 2026\.01\.20.Specification.Architecture.WebHome]] - How requirements are implemented * [[Data Model>>Archive.FactHarbor 2026\.01\.20.Specification.Data Model.WebHome]] - Data structures supporting user needs * [[AKEL (AI Knowledge Extraction Layer)>>Archive.FactHarbor 2026\.01\.20.Specification.AI Knowledge Extraction Layer (AKEL).WebHome]] - AI system fulfilling automation needs * [[Workflows>>Archive.FactHarbor 2026\.01\.20.Specification.Workflows.WebHome]] - User interaction workflows == Additional User Needs (V0.9.70) == === UN-26: Search Engine Visibility === As a content consumer I want FactHarbor analyses to appear in Google search results So that I can find fact-checks when searching Requirements: FR44 (ClaimReview schema) === UN-27: Visual Claim Verification === As a social media user I want to verify images shared with claims So that I can detect manipulated photos Requirements: FR46 (Image Verification) === UN-28: Safe Contribution Environment === As a fact-checking contributor I want protection from harassment So that I can contribute without fear Requirements: FR48 (Safety Framework)