Wiki source code of User Needs

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

version	line-number	content
1.1	1	= User Needs =
	2
	3	This page defines user needs that drive FactHarbor's requirements and design decisions.
	4
	5	Template: As a <specific user role>, I want to <action/goal>, so that I can <benefit/outcome>
	6
	7	Purpose: User needs inform functional requirements (FR) and non-functional requirements (NFR). Each need maps to one or more requirements that fulfill it.
	8
	9	== 1. Core Reading & Discovery ==
	10
	11	=== UN-1: Trust Assessment at a Glance ===
5.2	12
5.1	13	As an article reader (any content type),
	14	I want to see a trust score and overall verdict summary at a glance,
1.1	15	so that I can quickly decide if the content is worth my time to read in detail.
	16
	17	Maps to: FR7 (Automated Verdicts), NFR3 (Transparency)
	18
	19	=== UN-2: Claim Extraction and Verification ===
5.2	20
5.1	21	As an article reader,
	22	I want to see the key factual claims extracted from content with verification verdicts (likelihood ranges + uncertainty ratings) for each relevant scenario,
1.1	23	so that I can distinguish proven facts from speculation and understand context-dependent truth.
	24
	25	Maps to: FR1 (Claim Intake), FR4 (Scenario Generation), FR7 (Automated Verdicts)
	26
2.1	27	=== UN-3: Article Summary with FactHarbor Analysis Summary ===
5.2	28
5.1	29	As an article reader,
	30	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),
2.1	31	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.
1.1	32
2.1	33	Maps to: FR7 (Automated Verdicts), FR6 (Scenario Comparison), FR12 (Two-Panel Summary View - Article Summary with FactHarbor Analysis Summary)
1.1	34
2.1	35	==== Example: Two-Panel Summary Layout ====
	36
	37	\|=ARTICLE SUMMARY\|=FACTHARBOR ANALYSIS SUMMARY
	38	\|(((
	39	FactHarbor Summary: AHA Alcohol & Heart Health Statement (2025)
	40
	41	Source: American Heart Association Scientific Statement, //Circulation//, June 2025
	42	Credibility: Very High (peer-reviewed expert consensus)
	43
	44	=== The Big Picture ===
5.2	45
2.1	46	Old belief: "A glass of wine is good for your heart"
	47	New position: We're no longer sure that's true
	48
	49	=== Key Findings ===
	50
	51	\|=Drinking Level\|=Verdict
	52	\|Heavy (≥3 drinks/day)\|(% style="color:red" %)❌ Harmful – consistent across ALL studies
	53	\|Moderate (1-2 drinks/day)\|(% style="color:orange" %)❓ Uncertain – benefits may have been overstated
	54	\|None\|(% style="color:green" %)✅ Don't start drinking for heart health
	55
	56	=== Why the Shift? ===
5.2	57
2.1	58	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.
	59
	60	=== AHA Bottom Line ===
5.2	61
2.1	62	(% class="box" %)
	63	(((
	64	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.
	65
	66	//The "wine for heart health" era appears to be over.//
	67	)))
	68	)))\|(((
	69	FactHarbor Analysis Summary
	70
	71	Document: AHA Scientific Statement on Alcohol and Cardiovascular Disease (2025)
	72
	73	=== Source Assessment ===
5.2	74
2.1	75	Credibility: (% style="color:green" %)VERY HIGH(%%) – Official AHA statement, peer-reviewed, expert panel, published in top journal (//Circulation//)
	76
	77	=== Analysis Findings ===
	78
	79	\|=Claim in Document\|=FactHarbor Verdict\|=Confidence
	80	\|Heavy drinking harms heart health\|(% style="color:green" %)STRONGLY SUPPORTED\|(% style="color:green" %)95%
	81	\|Moderate drinking benefits uncertain\|(% style="color:green" %)WELL SUPPORTED\|(% style="color:green" %)85%
	82	\|Prior "cardioprotective" claims overstated\|(% style="color:green" %)SUPPORTED\|(% style="color:green" %)80%
	83	\|More research needed\|APPROPRIATE\|N/A
	84
	85	=== Assessment ===
	86
	87	(% style="color:green" %)✅(%%) Strengths: Transparent about methodological limitations, incorporates newer Mendelian randomization evidence, appropriately cautious, avoids overstatement
	88
	89	(% style="color:green" %)✅(%%) Methodology: Sound synthesis of observational and genetic evidence
	90
	91	(% style="color:orange" %)⚠️(%%) Limitation: Still relies heavily on observational data; RCT evidence limited
	92
	93	=== Verdict on the Statement Itself ===
	94
	95	(% class="box successmessage" %)
	96	(((
	97	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.
	98	)))
	99
	100	Analysis ID: FH-AHA-ALCO-2025-12-17
	101	)))
	102
	103	Key Elements of Two-Panel Layout:
	104
	105	Left Panel (Article Summary):
5.2	106
2.1	107	* Document title and source
	108	* Source credibility (document's own authority)
	109	* "The Big Picture" - old belief vs. new position
	110	* "Key Findings" - document's main claims in structured format
	111	* "Why the Shift?" - document's reasoning
	112	* "Bottom Line" - document's conclusion
	113
	114	Right Panel (FactHarbor Analysis Summary):
5.2	115
2.1	116	* FactHarbor's source assessment (independent credibility check)
	117	* Claim-by-claim analysis with verdicts and confidence scores
	118	* Assessment of methodology (strengths/limitations)
	119	* Overall verdict on the document itself
	120	* Analysis ID for reference
	121
	122	Design Principle: User sees what they claim and FactHarbor's complete analysis side-by-side without scrolling.
	123
1.1	124	=== UN-4: Social Media Fact-Checking ===
5.2	125
5.1	126	As a social media user,
	127	I want to check claims in posts before sharing,
1.1	128	so that I can avoid spreading misinformation.
	129
	130	Maps to: FR1 (Claim Intake), FR7 (Automated Verdicts), NFR1 (Performance - fast processing)
	131
4.1	132	=== UN-17: In-Article Claim Highlighting ===
5.2	133
5.1	134	As a reader viewing an article,
	135	I want to see factual claims highlighted with color-coded credibility indicators (green for well-supported, yellow for uncertain, red for refuted),
4.1	136	so that I can immediately identify which statements are trustworthy and which require skepticism without interrupting my reading flow.
	137
	138	Maps to: FR7 (Automated Verdicts), FR13 (In-Article Claim Highlighting), NFR1 (Performance - real-time highlighting)
	139
	140	==== Visual Concept ====
	141
	142	When reading an article on FactHarbor:
	143
	144	(% style="font-family:monospace; background-color:#f5f5f5; padding:10px; display:block;" %)
	145	(((
	146	Regular article text flows normally...
	147
	148	(% style="background-color:#90EE90; padding:2px 5px;" %)This claim is well-supported by evidence(%%) and you can continue reading...
	149
	150	More context and explanation...
	151
	152	(% style="background-color:#FFD700; padding:2px 5px;" %)This claim is uncertain with conflicting evidence(%%) but the article continues...
	153
	154	Additional information...
	155
	156	(% style="background-color:#FFB6C6; padding:2px 5px;" %)This claim has been refuted by research(%%) and understanding that helps readers...
	157	)))
	158
	159	Hover/Click on any highlighted claim → See verdict, confidence score, and evidence summary
	160
1.1	161	== 2. Source Tracing & Credibility ==
	162
	163	=== UN-5: Source Provenance and Track Records ===
5.2	164
5.1	165	As an article reader,
	166	I want to trace each piece of evidence back to its original source and see that source's historical track record,
1.1	167	so that I can assess the reliability of the information chain and learn which sources are consistently trustworthy.
	168
	169	Maps to: FR5 (Evidence Linking), Section 4.1 (Source Requirements - track record system)
	170
	171	=== UN-6: Publisher Reliability History ===
5.2	172
5.1	173	As an article reader,
	174	I want to see historical accuracy track records for sources and publishers,
1.1	175	so that I can learn which outlets are consistently reliable over time.
	176
	177	Maps to: Section 4.1 (Source Requirements), Data Model (Source entity with track_record_score)
	178
	179	== 3. Understanding the Analysis ==
	180
	181	=== UN-7: Evidence Transparency ===
5.2	182
5.1	183	As a skeptical reader,
	184	I want to see the evidence and reasoning behind each verdict,
1.1	185	so that I can judge whether I agree with the assessment and form my own conclusions.
	186
	187	Maps to: FR5 (Evidence Linking), NFR3 (Transparency)
	188
	189	=== UN-8: Understanding Disagreement and Consensus ===
5.2	190
5.1	191	As an article reader,
	192	I want to see which scenarios have strong supporting evidence versus which have conflicting evidence or high uncertainty,
1.1	193	so that I can understand where legitimate disagreement exists versus where consensus is clear.
	194
	195	Maps to: FR6 (Scenario Comparison), FR7 (Automated Verdicts - uncertainty factors), AKEL Gate 2 (Contradiction Search)
	196
	197	=== UN-9: Methodology Transparency ===
5.2	198
5.1	199	As an article reader,
	200	I want to understand how likelihood ranges and confidence scores are calculated,
1.1	201	so that I can trust the verification process itself.
	202
	203	Maps to: NFR3 (Transparency), Architecture (documented algorithms), AKEL (Quality Gates)
	204
	205	== 4. Pattern Recognition & Learning ==
	206
	207	=== UN-10: Manipulation Tactics Detection ===
5.2	208
5.1	209	As an article reader,
	210	I want to see common manipulation tactics or logical fallacies identified in content,
1.1	211	so that I can recognize them elsewhere and become a more critical consumer of information.
	212
	213	Maps to: AKEL (Bubble Detection), Section 5 (Automated Risk Scoring)
	214
	215	=== UN-11: Filtered Research ===
5.2	216
5.1	217	As a researcher,
	218	I want to filter content by verification status, confidence levels, and source quality,
1.1	219	so that I can work only with reliable information appropriate for my research needs.
	220
	221	Maps to: FR1 (Claim Classification), Section 4.4 (Confidence Scoring), NFR1 (Performance)
	222
	223	== 5. Taking Action ==
	224
	225	=== UN-12: Submit Unchecked Claims ===
5.2	226
5.1	227	As a reader who finds unchecked claims,
	228	I want to submit them for verification,
1.1	229	so that I can help expand fact-checking coverage and contribute to the knowledge base.
	230
	231	Maps to: FR1 (Claim Intake), Section 1.1 (Reader role)
	232
	233	=== UN-13: Cite FactHarbor Verdicts ===
5.2	234
5.1	235	As a content creator,
	236	I want to cite FactHarbor verdicts when sharing content,
1.1	237	so that I can add credibility to what I publish and help my audience distinguish fact from speculation.
	238
	239	Maps to: FR7 (Automated Verdicts), NFR3 (Transparency - exportable data)
	240
	241	== 6. Professional Use ==
	242
	243	=== UN-14: API Access for Integration ===
5.2	244
5.1	245	As a journalist/researcher,
	246	I want API access to verification data and claim histories,
1.1	247	so that I can integrate fact-checking into my professional workflow without manual lookups.
	248
	249	Maps to: Architecture (REST API), NFR2 (Scalability), FR11 (Audit Trail)
	250
	251	== 7. Understanding Evolution & Trust Labels ==
	252
	253	=== UN-15: Verdict Evolution Timeline ===
5.1	254
	255	{{warning}}
	256	Status: Deferred (Not in V1.0)
	257
	258	Full verdict evolution timeline has been dropped from V1.0. The system will track edit history only. Versioned entities and full evolution tracking are deferred to future releases.
	259	{{/warning}}
	260
	261	As an article reader,
	262	I want to see how a claim's verdict has evolved over time with clear timestamps,
1.1	263	so that I can understand whether the current assessment is stable or recently changed based on new evidence.
	264
5.1	265	Maps to: ~~FR8 (Deferred)~~, Data Model (Versioned entities), NFR3 (Transparency)
1.1	266
	267	=== UN-16: AI vs. Human Review Status ===
5.2	268
5.1	269	As an article reader,
	270	I want to know if the verdict was AI-generated, human-reviewed, or expert-validated,
1.1	271	so that I can gauge the appropriate level of trust and understand the review process used.
	272
	273	Maps to: AKEL (Publication Modes), Section 5 (Risk Tiers), Data Model (AuthorType field)
	274
	275	== 8. User Need → Requirements Mapping Summary ==
	276
	277	This section provides a consolidated view of how user needs drive system requirements.
	278
	279	=== 8.1 Functional Requirements Coverage ===
	280
2.1	281	(% style="width:100%" %)
	282	\|=(% style="width:10%" %)FR#\|=(% style="width:35%" %)Requirement\|=(% style="width:55%" %)Fulfills User Needs
	283	\|(% style="width:10%" %)FR1\|(% style="width:35%" %)Claim Intake\|(% style="width:55%" %)UN-2, UN-4, UN-12
	284	\|(% style="width:10%" %)FR4\|(% style="width:35%" %)Scenario Generation\|(% style="width:55%" %)UN-2, UN-3
	285	\|(% style="width:10%" %)FR5\|(% style="width:35%" %)Evidence Linking\|(% style="width:55%" %)UN-5, UN-7
	286	\|(% style="width:10%" %)FR6\|(% style="width:35%" %)Scenario Comparison\|(% style="width:55%" %)UN-3, UN-8
4.1	287	\|(% style="width:10%" %)FR7\|(% style="width:35%" %)Automated Verdicts\|(% style="width:55%" %)UN-1, UN-2, UN-3, UN-4, UN-13, UN-17
2.1	288	\|(% style="width:10%" %)FR8\|(% style="width:35%" %)Time Evolution\|(% style="width:55%" %)UN-15
	289	\|(% style="width:10%" %)FR11\|(% style="width:35%" %)Audit Trail\|(% style="width:55%" %)UN-14, UN-16
	290	\|(% style="width:10%" %)FR12\|(% style="width:35%" %)Two-Panel Summary View\|(% style="width:55%" %)UN-3
4.1	291	\|(% style="width:10%" %)FR13\|(% style="width:35%" %)In-Article Claim Highlighting\|(% style="width:55%" %)UN-17
1.1	292
	293	=== 8.2 Non-Functional Requirements Coverage ===
	294
2.1	295	(% style="width:100%" %)
	296	\|=(% style="width:10%" %)NFR#\|=(% style="width:35%" %)Requirement\|=(% style="width:55%" %)Fulfills User Needs
4.1	297	\|(% 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)
2.1	298	\|(% style="width:10%" %)NFR2\|(% style="width:35%" %)Scalability\|(% style="width:55%" %)UN-14 (API access at scale)
	299	\|(% style="width:10%" %)NFR3\|(% style="width:35%" %)Transparency\|(% style="width:55%" %)UN-1, UN-7, UN-9, UN-13, UN-15
1.1	300
	301	=== 8.3 AKEL System Coverage ===
	302
2.1	303	(% style="width:100%" %)
	304	\|=(% style="width:45%" %)AKEL Component\|=(% style="width:55%" %)Fulfills User Needs
	305	\|(% style="width:45%" %)Quality Gates\|(% style="width:55%" %)UN-9 (methodology transparency)
	306	\|(% style="width:45%" %)Contradiction Search (Gate 2)\|(% style="width:55%" %)UN-8 (understanding disagreement)
	307	\|(% style="width:45%" %)Bubble Detection\|(% style="width:55%" %)UN-10 (manipulation tactics)
	308	\|(% style="width:45%" %)Publication Modes\|(% style="width:55%" %)UN-16 (AI vs. human review status)
	309	\|(% style="width:45%" %)Risk Tiers\|(% style="width:55%" %)UN-16 (appropriate review level)
1.1	310
	311	=== 8.4 Data Model Coverage ===
	312
2.1	313	(% style="width:100%" %)
	314	\|=(% style="width:45%" %)Entity\|=(% style="width:55%" %)Fulfills User Needs
	315	\|(% style="width:45%" %)Source (with track_record_score)\|(% style="width:55%" %)UN-5, UN-6 (source reliability)
	316	\|(% style="width:45%" %)Scenario\|(% style="width:55%" %)UN-2, UN-3, UN-8 (context-dependent truth)
	317	\|(% style="width:45%" %)Verdict (with likelihood_range, uncertainty_factors)\|(% style="width:55%" %)UN-1, UN-2, UN-3, UN-8 (detailed assessment)
	318	\|(% style="width:45%" %)Versioned entities\|(% style="width:55%" %)UN-15 (evolution timeline)
	319	\|(% style="width:45%" %)AuthorType field\|(% style="width:55%" %)UN-16 (AI vs. human status)
1.1	320
	321	== 9. User Need Gaps & Future Considerations ==
	322
	323	This section identifies user needs that may emerge as the platform matures:
	324
	325	Potential Future Needs:
5.2	326
1.1	327	* Collaborative annotation: Users want to discuss verdicts with others
	328	* Personal tracking: Users want to track claims they're following
	329	* Custom alerts: Users want notifications when tracked claims are updated
	330	* Export capabilities: Users want to export claim analyses for their own documentation
	331	* Comparative analysis: Users want to compare how different fact-checkers rate the same claim
	332
	333	When to address: These needs should be considered when:
5.2	334
1.1	335	1. User feedback explicitly requests them
	336	2. Usage metrics show users attempting these workflows
	337	3. Competitive analysis shows these as differentiators
	338
	339	Principle: Start simple (current User Needs), add complexity only when metrics prove necessity.
	340
	341	== 10. Related Pages ==
	342
5.12	343	* [[Requirements>>Archive.FactHarbor 2026\.01\.20.Specification.Requirements.WebHome]] - Parent page with roles, rules, and functional requirements
5.9	344	* [[Architecture>>Archive.FactHarbor 2026\.01\.20.Specification.Architecture.WebHome]] - How requirements are implemented
5.10	345	* [[Data Model>>Archive.FactHarbor 2026\.01\.20.Specification.Data Model.WebHome]] - Data structures supporting user needs
5.8	346	* [[AKEL (AI Knowledge Extraction Layer)>>Archive.FactHarbor 2026\.01\.20.Specification.AI Knowledge Extraction Layer (AKEL).WebHome]] - AI system fulfilling automation needs
5.13	347	* [[Workflows>>Archive.FactHarbor 2026\.01\.20.Specification.Workflows.WebHome]] - User interaction workflows
5.1	348
	349	== Additional User Needs (V0.9.70) ==
	350
	351	=== UN-26: Search Engine Visibility ===
	352
	353	As a content consumer
	354	I want FactHarbor analyses to appear in Google search results
	355	So that I can find fact-checks when searching
	356
	357	Requirements: FR44 (ClaimReview schema)
	358
	359	=== UN-27: Visual Claim Verification ===
	360
	361	As a social media user
	362	I want to verify images shared with claims
	363	So that I can detect manipulated photos
	364
	365	Requirements: FR46 (Image Verification)
	366
	367	=== UN-28: Safe Contribution Environment ===
	368
	369	As a fact-checking contributor
	370	I want protection from harassment
	371	So that I can contribute without fear
	372
	373	Requirements: FR48 (Safety Framework)

Wiki source code of User Needs

Applications

Navigation

Need help?