Wiki source code of User Needs
Last modified by Robert Schaub on 2026/02/08 08:27
Hide last authors
| author | 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 === | ||
| |
1.3 | 12 | |
| |
1.1 | 13 | **As** an article reader (any content type), |
| 14 | **I want** to see a trust score and overall verdict summary at a glance, | ||
| 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 === | ||
| |
1.3 | 20 | |
| |
1.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, | ||
| 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 | |||
| 27 | === UN-3: Article Summary with FactHarbor Analysis Summary === | ||
| |
1.3 | 28 | |
| |
1.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), | ||
| 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. | ||
| 32 | |||
| 33 | **Maps to**: FR7 (Automated Verdicts), FR6 (Scenario Comparison), FR12 (Two-Panel Summary View - Article Summary with FactHarbor Analysis Summary) | ||
| 34 | |||
| 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 === | ||
| |
1.3 | 45 | |
| |
1.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? === | ||
| |
1.3 | 57 | |
| |
1.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 === | ||
| |
1.3 | 61 | |
| |
1.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 === | ||
| |
1.3 | 74 | |
| |
1.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)**: | ||
| |
1.3 | 106 | |
| |
1.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)**: | ||
| |
1.3 | 115 | |
| |
1.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 | |||
| 124 | === UN-4: Social Media Fact-Checking === | ||
| |
1.3 | 125 | |
| |
1.1 | 126 | **As** a social media user, |
| 127 | **I want** to check claims in posts before sharing, | ||
| 128 | **so that** I can avoid spreading misinformation. | ||
| 129 | |||
| 130 | **Maps to**: FR1 (Claim Intake), FR7 (Automated Verdicts), NFR1 (Performance - fast processing) | ||
| 131 | |||
| 132 | === UN-17: In-Article Claim Highlighting === | ||
| |
1.3 | 133 | |
| |
1.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), | ||
| 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 | |||
| 161 | == 2. Source Tracing & Credibility == | ||
| 162 | |||
| 163 | === UN-5: Source Provenance and Track Records === | ||
| |
1.3 | 164 | |
| |
1.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, | ||
| 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 === | ||
| |
1.3 | 172 | |
| |
1.1 | 173 | **As** an article reader, |
| 174 | **I want** to see historical accuracy track records for sources and publishers, | ||
| 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 === | ||
| |
1.3 | 182 | |
| |
1.1 | 183 | **As** a skeptical reader, |
| 184 | **I want** to see the evidence and reasoning behind each verdict, | ||
| 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 === | ||
| |
1.3 | 190 | |
| |
1.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, | ||
| 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 === | ||
| |
1.3 | 198 | |
| |
1.1 | 199 | **As** an article reader, |
| 200 | **I want** to understand how likelihood ranges and confidence scores are calculated, | ||
| 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 === | ||
| |
1.3 | 208 | |
| |
1.1 | 209 | **As** an article reader, |
| 210 | **I want** to see common manipulation tactics or logical fallacies identified in content, | ||
| 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 === | ||
| |
1.3 | 216 | |
| |
1.1 | 217 | **As** a researcher, |
| 218 | **I want** to filter content by verification status, confidence levels, and source quality, | ||
| 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 === | ||
| |
1.3 | 226 | |
| |
1.1 | 227 | **As** a reader who finds unchecked claims, |
| 228 | **I want** to submit them for verification, | ||
| 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 === | ||
| |
1.3 | 234 | |
| |
1.1 | 235 | **As** a content creator, |
| 236 | **I want** to cite FactHarbor verdicts when sharing content, | ||
| 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 === | ||
| |
1.3 | 244 | |
| |
1.1 | 245 | **As** a journalist/researcher, |
| 246 | **I want** API access to verification data and claim histories, | ||
| 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 === | ||
| |
1.3 | 254 | |
| |
1.1 | 255 | **As** an article reader, |
| 256 | **I want** to see how a claim's verdict has evolved over time with clear timestamps, | ||
| 257 | **so that** I can understand whether the current assessment is stable or recently changed based on new evidence. | ||
| 258 | |||
| 259 | **Maps to**: FR8 (Time Evolution), Data Model (Versioned entities), NFR3 (Transparency) | ||
| 260 | |||
| 261 | === UN-16: AI vs. Human Review Status === | ||
| |
1.3 | 262 | |
| |
1.1 | 263 | **As** an article reader, |
| 264 | **I want** to know if the verdict was AI-generated, human-reviewed, or expert-validated, | ||
| 265 | **so that** I can gauge the appropriate level of trust and understand the review process used. | ||
| 266 | |||
| 267 | **Maps to**: AKEL (Publication Modes), Section 5 (Risk Tiers), Data Model (AuthorType field) | ||
| 268 | |||
| 269 | == 8. User Need → Requirements Mapping Summary == | ||
| 270 | |||
| 271 | This section provides a consolidated view of how user needs drive system requirements. | ||
| 272 | |||
| 273 | === 8.1 Functional Requirements Coverage === | ||
| 274 | |||
| 275 | (% style="width:100%" %) | ||
| 276 | |=(% style="width:10%" %)FR#|=(% style="width:35%" %)Requirement|=(% style="width:55%" %)Fulfills User Needs | ||
| 277 | |(% style="width:10%" %)FR1|(% style="width:35%" %)Claim Intake|(% style="width:55%" %)UN-2, UN-4, UN-12 | ||
| 278 | |(% style="width:10%" %)FR4|(% style="width:35%" %)Scenario Generation|(% style="width:55%" %)UN-2, UN-3 | ||
| 279 | |(% style="width:10%" %)FR5|(% style="width:35%" %)Evidence Linking|(% style="width:55%" %)UN-5, UN-7 | ||
| 280 | |(% style="width:10%" %)FR6|(% style="width:35%" %)Scenario Comparison|(% style="width:55%" %)UN-3, UN-8 | ||
| 281 | |(% style="width:10%" %)FR7|(% style="width:35%" %)Automated Verdicts|(% style="width:55%" %)UN-1, UN-2, UN-3, UN-4, UN-13, UN-17 | ||
| 282 | |(% style="width:10%" %)FR8|(% style="width:35%" %)Time Evolution|(% style="width:55%" %)UN-15 | ||
| 283 | |(% style="width:10%" %)FR11|(% style="width:35%" %)Audit Trail|(% style="width:55%" %)UN-14, UN-16 | ||
| 284 | |(% style="width:10%" %)FR12|(% style="width:35%" %)Two-Panel Summary View|(% style="width:55%" %)UN-3 | ||
| 285 | |(% style="width:10%" %)FR13|(% style="width:35%" %)In-Article Claim Highlighting|(% style="width:55%" %)UN-17 | ||
| 286 | |||
| 287 | === 8.2 Non-Functional Requirements Coverage === | ||
| 288 | |||
| 289 | (% style="width:100%" %) | ||
| 290 | |=(% style="width:10%" %)NFR#|=(% style="width:35%" %)Requirement|=(% style="width:55%" %)Fulfills User Needs | ||
| 291 | |(% 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) | ||
| 292 | |(% style="width:10%" %)NFR2|(% style="width:35%" %)Scalability|(% style="width:55%" %)UN-14 (API access at scale) | ||
| 293 | |(% style="width:10%" %)NFR3|(% style="width:35%" %)Transparency|(% style="width:55%" %)UN-1, UN-7, UN-9, UN-13, UN-15 | ||
| 294 | |||
| 295 | === 8.3 AKEL System Coverage === | ||
| 296 | |||
| 297 | (% style="width:100%" %) | ||
| 298 | |=(% style="width:45%" %)AKEL Component|=(% style="width:55%" %)Fulfills User Needs | ||
| 299 | |(% style="width:45%" %)Quality Gates|(% style="width:55%" %)UN-9 (methodology transparency) | ||
| 300 | |(% style="width:45%" %)Contradiction Search (Gate 2)|(% style="width:55%" %)UN-8 (understanding disagreement) | ||
| 301 | |(% style="width:45%" %)Bubble Detection|(% style="width:55%" %)UN-10 (manipulation tactics) | ||
| 302 | |(% style="width:45%" %)Publication Modes|(% style="width:55%" %)UN-16 (AI vs. human review status) | ||
| 303 | |(% style="width:45%" %)Risk Tiers|(% style="width:55%" %)UN-16 (appropriate review level) | ||
| 304 | |||
| 305 | === 8.4 Data Model Coverage === | ||
| 306 | |||
| 307 | (% style="width:100%" %) | ||
| 308 | |=(% style="width:45%" %)Entity|=(% style="width:55%" %)Fulfills User Needs | ||
| 309 | |(% style="width:45%" %)Source (with track_record_score)|(% style="width:55%" %)UN-5, UN-6 (source reliability) | ||
| 310 | |(% style="width:45%" %)Scenario|(% style="width:55%" %)UN-2, UN-3, UN-8 (context-dependent truth) | ||
| 311 | |(% style="width:45%" %)Verdict (with likelihood_range, uncertainty_factors)|(% style="width:55%" %)UN-1, UN-2, UN-3, UN-8 (detailed assessment) | ||
| 312 | |(% style="width:45%" %)Versioned entities|(% style="width:55%" %)UN-15 (evolution timeline) | ||
| 313 | |(% style="width:45%" %)AuthorType field|(% style="width:55%" %)UN-16 (AI vs. human status) | ||
| 314 | |||
| 315 | == 9. User Need Gaps & Future Considerations == | ||
| 316 | |||
| 317 | This section identifies user needs that may emerge as the platform matures: | ||
| 318 | |||
| 319 | **Potential Future Needs**: | ||
| |
1.3 | 320 | |
| |
1.1 | 321 | * **Collaborative annotation**: Users want to discuss verdicts with others |
| 322 | * **Personal tracking**: Users want to track claims they're following | ||
| 323 | * **Custom alerts**: Users want notifications when tracked claims are updated | ||
| 324 | * **Export capabilities**: Users want to export claim analyses for their own documentation | ||
| 325 | * **Comparative analysis**: Users want to compare how different fact-checkers rate the same claim | ||
| 326 | |||
| 327 | **When to address**: These needs should be considered when: | ||
| |
1.3 | 328 | |
| |
1.1 | 329 | 1. User feedback explicitly requests them |
| 330 | 2. Usage metrics show users attempting these workflows | ||
| 331 | 3. Competitive analysis shows these as differentiators | ||
| 332 | |||
| 333 | **Principle**: Start simple (current User Needs), add complexity only when metrics prove necessity. | ||
| 334 | |||
| 335 | == 10. Related Pages == | ||
| 336 | |||
| |
1.11 | 337 | * [[Requirements>>Archive.FactHarbor 2026\.01\.20.Specification.Requirements.WebHome]] - Parent page with roles, rules, and functional requirements |
| |
1.9 | 338 | * [[Architecture>>Archive.FactHarbor 2026\.01\.20.Specification.Architecture.WebHome]] - How requirements are implemented |
| |
1.10 | 339 | * [[Data Model>>Archive.FactHarbor 2026\.01\.20.Specification.Data Model.WebHome]] - Data structures supporting user needs |
| |
1.8 | 340 | * [[AKEL (AI Knowledge Extraction Layer)>>Archive.FactHarbor 2026\.01\.20.Specification.AI Knowledge Extraction Layer (AKEL).WebHome]] - AI system fulfilling automation needs |
| |
1.12 | 341 | * [[Workflows>>Archive.FactHarbor 2026\.01\.20.Specification.Workflows.WebHome]] - User interaction workflows |
| |
1.1 | 342 | |
| 343 | == Additional User Needs (V0.9.70) == | ||
| 344 | |||
| 345 | === UN-26: Search Engine Visibility === | ||
| 346 | |||
| 347 | **As a** content consumer | ||
| 348 | **I want** FactHarbor analyses to appear in Google search results | ||
| 349 | **So that** I can find fact-checks when searching | ||
| 350 | |||
| 351 | **Requirements:** FR44 (ClaimReview schema) | ||
| 352 | |||
| 353 | |||
| 354 | === UN-27: Visual Claim Verification === | ||
| 355 | |||
| 356 | **As a** social media user | ||
| 357 | **I want** to verify images shared with claims | ||
| 358 | **So that** I can detect manipulated photos | ||
| 359 | |||
| 360 | **Requirements:** FR46 (Image Verification) | ||
| 361 | |||
| 362 | |||
| 363 | === UN-28: Safe Contribution Environment === | ||
| 364 | |||
| 365 | **As a** fact-checking contributor | ||
| 366 | **I want** protection from harassment | ||
| 367 | **So that** I can contribute without fear | ||
| 368 | |||
| 369 | **Requirements:** FR48 (Safety Framework) |