Wiki source code of User Needs
Version 3.1 by Robert Schaub on 2025/12/19 10:03
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 === | ||
| 12 | **As** an article reader (any content type), | ||
| 13 | **I want** to see a trust score and overall verdict summary at a glance, | ||
| 14 | **so that** I can quickly decide if the content is worth my time to read in detail. | ||
| 15 | |||
| 16 | **Maps to**: FR7 (Automated Verdicts), NFR3 (Transparency) | ||
| 17 | |||
| 18 | === UN-2: Claim Extraction and Verification === | ||
| 19 | **As** an article reader, | ||
| 20 | **I want** to see the key factual claims extracted from content with verification verdicts (likelihood ranges + uncertainty ratings) for each relevant scenario, | ||
| 21 | **so that** I can distinguish proven facts from speculation and understand context-dependent truth. | ||
| 22 | |||
| 23 | **Maps to**: FR1 (Claim Intake), FR4 (Scenario Generation), FR7 (Automated Verdicts) | ||
| 24 | |||
| |
2.1 | 25 | === UN-3: Article Summary with FactHarbor Analysis Summary === |
| |
1.1 | 26 | **As** an article reader, |
| |
2.1 | 27 | **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), |
| 28 | **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 | 29 | |
| |
2.1 | 30 | **Maps to**: FR7 (Automated Verdicts), FR6 (Scenario Comparison), FR12 (Two-Panel Summary View - Article Summary with FactHarbor Analysis Summary) |
| |
1.1 | 31 | |
| |
2.1 | 32 | ==== Example: Two-Panel Summary Layout ==== |
| 33 | |||
| 34 | |=**ARTICLE SUMMARY**|=**FACTHARBOR ANALYSIS SUMMARY** | ||
| 35 | |((( | ||
| 36 | **FactHarbor Summary: AHA Alcohol & Heart Health Statement (2025)** | ||
| 37 | |||
| 38 | **Source:** American Heart Association Scientific Statement, //Circulation//, June 2025 | ||
| 39 | **Credibility:** Very High (peer-reviewed expert consensus) | ||
| 40 | |||
| 41 | === The Big Picture === | ||
| 42 | **Old belief:** "A glass of wine is good for your heart" | ||
| 43 | **New position:** We're no longer sure that's true | ||
| 44 | |||
| 45 | === Key Findings === | ||
| 46 | |||
| 47 | |=**Drinking Level**|=**Verdict** | ||
| 48 | |Heavy (≥3 drinks/day)|(% style="color:red" %)❌ **Harmful** – consistent across ALL studies | ||
| 49 | |Moderate (1-2 drinks/day)|(% style="color:orange" %)❓ **Uncertain** – benefits may have been overstated | ||
| 50 | |None|(% style="color:green" %)✅ **Don't start drinking for heart health** | ||
| 51 | |||
| 52 | === Why the Shift? === | ||
| 53 | 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. | ||
| 54 | |||
| 55 | === AHA Bottom Line === | ||
| 56 | (% class="box" %) | ||
| 57 | ((( | ||
| 58 | 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. | ||
| 59 | |||
| 60 | //The "wine for heart health" era appears to be over.// | ||
| 61 | ))) | ||
| 62 | )))|((( | ||
| 63 | **FactHarbor Analysis Summary** | ||
| 64 | |||
| 65 | **Document:** AHA Scientific Statement on Alcohol and Cardiovascular Disease (2025) | ||
| 66 | |||
| 67 | === Source Assessment === | ||
| 68 | **Credibility:** (% style="color:green" %)**VERY HIGH**(%%) – Official AHA statement, peer-reviewed, expert panel, published in top journal (//Circulation//) | ||
| 69 | |||
| 70 | === Analysis Findings === | ||
| 71 | |||
| 72 | |=**Claim in Document**|=**FactHarbor Verdict**|=**Confidence** | ||
| 73 | |Heavy drinking harms heart health|(% style="color:green" %)**STRONGLY SUPPORTED**|(% style="color:green" %)**95%** | ||
| 74 | |Moderate drinking benefits uncertain|(% style="color:green" %)**WELL SUPPORTED**|(% style="color:green" %)**85%** | ||
| 75 | |Prior "cardioprotective" claims overstated|(% style="color:green" %)**SUPPORTED**|(% style="color:green" %)**80%** | ||
| 76 | |More research needed|**APPROPRIATE**|N/A | ||
| 77 | |||
| 78 | === Assessment === | ||
| 79 | |||
| 80 | (% style="color:green" %)✅(%%) **Strengths:** Transparent about methodological limitations, incorporates newer Mendelian randomization evidence, appropriately cautious, avoids overstatement | ||
| 81 | |||
| 82 | (% style="color:green" %)✅(%%) **Methodology:** Sound synthesis of observational and genetic evidence | ||
| 83 | |||
| 84 | (% style="color:orange" %)⚠️(%%) **Limitation:** Still relies heavily on observational data; RCT evidence limited | ||
| 85 | |||
| 86 | === Verdict on the Statement Itself === | ||
| 87 | |||
| 88 | (% class="box successmessage" %) | ||
| 89 | ((( | ||
| 90 | **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. | ||
| 91 | ))) | ||
| 92 | |||
| 93 | **Analysis ID:** FH-AHA-ALCO-2025-12-17 | ||
| 94 | ))) | ||
| 95 | |||
| 96 | **Key Elements of Two-Panel Layout**: | ||
| 97 | |||
| 98 | **Left Panel (Article Summary)**: | ||
| 99 | * Document title and source | ||
| 100 | * Source credibility (document's own authority) | ||
| 101 | * "The Big Picture" - old belief vs. new position | ||
| 102 | * "Key Findings" - document's main claims in structured format | ||
| 103 | * "Why the Shift?" - document's reasoning | ||
| 104 | * "Bottom Line" - document's conclusion | ||
| 105 | |||
| 106 | **Right Panel (FactHarbor Analysis Summary)**: | ||
| 107 | * FactHarbor's source assessment (independent credibility check) | ||
| 108 | * Claim-by-claim analysis with verdicts and confidence scores | ||
| 109 | * Assessment of methodology (strengths/limitations) | ||
| 110 | * Overall verdict on the document itself | ||
| 111 | * Analysis ID for reference | ||
| 112 | |||
| 113 | **Design Principle**: User sees **what they claim** and **FactHarbor's complete analysis** side-by-side without scrolling. | ||
| 114 | |||
| |
1.1 | 115 | === UN-4: Social Media Fact-Checking === |
| 116 | **As** a social media user, | ||
| 117 | **I want** to check claims in posts before sharing, | ||
| 118 | **so that** I can avoid spreading misinformation. | ||
| 119 | |||
| 120 | **Maps to**: FR1 (Claim Intake), FR7 (Automated Verdicts), NFR1 (Performance - fast processing) | ||
| 121 | |||
| 122 | == 2. Source Tracing & Credibility == | ||
| 123 | |||
| 124 | === UN-5: Source Provenance and Track Records === | ||
| 125 | **As** an article reader, | ||
| 126 | **I want** to trace each piece of evidence back to its original source and see that source's historical track record, | ||
| 127 | **so that** I can assess the reliability of the information chain and learn which sources are consistently trustworthy. | ||
| 128 | |||
| 129 | **Maps to**: FR5 (Evidence Linking), Section 4.1 (Source Requirements - track record system) | ||
| 130 | |||
| 131 | === UN-6: Publisher Reliability History === | ||
| 132 | **As** an article reader, | ||
| 133 | **I want** to see historical accuracy track records for sources and publishers, | ||
| 134 | **so that** I can learn which outlets are consistently reliable over time. | ||
| 135 | |||
| 136 | **Maps to**: Section 4.1 (Source Requirements), Data Model (Source entity with track_record_score) | ||
| 137 | |||
| 138 | == 3. Understanding the Analysis == | ||
| 139 | |||
| 140 | === UN-7: Evidence Transparency === | ||
| 141 | **As** a skeptical reader, | ||
| 142 | **I want** to see the evidence and reasoning behind each verdict, | ||
| 143 | **so that** I can judge whether I agree with the assessment and form my own conclusions. | ||
| 144 | |||
| 145 | **Maps to**: FR5 (Evidence Linking), NFR3 (Transparency) | ||
| 146 | |||
| 147 | === UN-8: Understanding Disagreement and Consensus === | ||
| 148 | **As** an article reader, | ||
| 149 | **I want** to see which scenarios have strong supporting evidence versus which have conflicting evidence or high uncertainty, | ||
| 150 | **so that** I can understand where legitimate disagreement exists versus where consensus is clear. | ||
| 151 | |||
| 152 | **Maps to**: FR6 (Scenario Comparison), FR7 (Automated Verdicts - uncertainty factors), AKEL Gate 2 (Contradiction Search) | ||
| 153 | |||
| 154 | === UN-9: Methodology Transparency === | ||
| 155 | **As** an article reader, | ||
| 156 | **I want** to understand how likelihood ranges and confidence scores are calculated, | ||
| 157 | **so that** I can trust the verification process itself. | ||
| 158 | |||
| 159 | **Maps to**: NFR3 (Transparency), Architecture (documented algorithms), AKEL (Quality Gates) | ||
| 160 | |||
| 161 | == 4. Pattern Recognition & Learning == | ||
| 162 | |||
| 163 | === UN-10: Manipulation Tactics Detection === | ||
| 164 | **As** an article reader, | ||
| 165 | **I want** to see common manipulation tactics or logical fallacies identified in content, | ||
| 166 | **so that** I can recognize them elsewhere and become a more critical consumer of information. | ||
| 167 | |||
| 168 | **Maps to**: AKEL (Bubble Detection), Section 5 (Automated Risk Scoring) | ||
| 169 | |||
| 170 | === UN-11: Filtered Research === | ||
| 171 | **As** a researcher, | ||
| 172 | **I want** to filter content by verification status, confidence levels, and source quality, | ||
| 173 | **so that** I can work only with reliable information appropriate for my research needs. | ||
| 174 | |||
| 175 | **Maps to**: FR1 (Claim Classification), Section 4.4 (Confidence Scoring), NFR1 (Performance) | ||
| 176 | |||
| 177 | == 5. Taking Action == | ||
| 178 | |||
| 179 | === UN-12: Submit Unchecked Claims === | ||
| 180 | **As** a reader who finds unchecked claims, | ||
| 181 | **I want** to submit them for verification, | ||
| 182 | **so that** I can help expand fact-checking coverage and contribute to the knowledge base. | ||
| 183 | |||
| 184 | **Maps to**: FR1 (Claim Intake), Section 1.1 (Reader role) | ||
| 185 | |||
| 186 | === UN-13: Cite FactHarbor Verdicts === | ||
| 187 | **As** a content creator, | ||
| 188 | **I want** to cite FactHarbor verdicts when sharing content, | ||
| 189 | **so that** I can add credibility to what I publish and help my audience distinguish fact from speculation. | ||
| 190 | |||
| 191 | **Maps to**: FR7 (Automated Verdicts), NFR3 (Transparency - exportable data) | ||
| 192 | |||
| 193 | == 6. Professional Use == | ||
| 194 | |||
| 195 | === UN-14: API Access for Integration === | ||
| 196 | **As** a journalist/researcher, | ||
| 197 | **I want** API access to verification data and claim histories, | ||
| 198 | **so that** I can integrate fact-checking into my professional workflow without manual lookups. | ||
| 199 | |||
| 200 | **Maps to**: Architecture (REST API), NFR2 (Scalability), FR11 (Audit Trail) | ||
| 201 | |||
| 202 | == 7. Understanding Evolution & Trust Labels == | ||
| 203 | |||
| 204 | === UN-15: Verdict Evolution Timeline === | ||
| 205 | **As** an article reader, | ||
| 206 | **I want** to see how a claim's verdict has evolved over time with clear timestamps, | ||
| 207 | **so that** I can understand whether the current assessment is stable or recently changed based on new evidence. | ||
| 208 | |||
| 209 | **Maps to**: FR8 (Time Evolution), Data Model (Versioned entities), NFR3 (Transparency) | ||
| 210 | |||
| 211 | === UN-16: AI vs. Human Review Status === | ||
| 212 | **As** an article reader, | ||
| 213 | **I want** to know if the verdict was AI-generated, human-reviewed, or expert-validated, | ||
| 214 | **so that** I can gauge the appropriate level of trust and understand the review process used. | ||
| 215 | |||
| 216 | **Maps to**: AKEL (Publication Modes), Section 5 (Risk Tiers), Data Model (AuthorType field) | ||
| 217 | |||
| 218 | == 8. User Need → Requirements Mapping Summary == | ||
| 219 | |||
| 220 | This section provides a consolidated view of how user needs drive system requirements. | ||
| 221 | |||
| 222 | === 8.1 Functional Requirements Coverage === | ||
| 223 | |||
| |
2.1 | 224 | (% style="width:100%" %) |
| 225 | |=(% style="width:10%" %)FR#|=(% style="width:35%" %)Requirement|=(% style="width:55%" %)Fulfills User Needs | ||
| 226 | |(% style="width:10%" %)FR1|(% style="width:35%" %)Claim Intake|(% style="width:55%" %)UN-2, UN-4, UN-12 | ||
| 227 | |(% style="width:10%" %)FR4|(% style="width:35%" %)Scenario Generation|(% style="width:55%" %)UN-2, UN-3 | ||
| 228 | |(% style="width:10%" %)FR5|(% style="width:35%" %)Evidence Linking|(% style="width:55%" %)UN-5, UN-7 | ||
| 229 | |(% style="width:10%" %)FR6|(% style="width:35%" %)Scenario Comparison|(% style="width:55%" %)UN-3, UN-8 | ||
| 230 | |(% style="width:10%" %)FR7|(% style="width:35%" %)Automated Verdicts|(% style="width:55%" %)UN-1, UN-2, UN-3, UN-4, UN-13 | ||
| 231 | |(% style="width:10%" %)FR8|(% style="width:35%" %)Time Evolution|(% style="width:55%" %)UN-15 | ||
| 232 | |(% style="width:10%" %)FR11|(% style="width:35%" %)Audit Trail|(% style="width:55%" %)UN-14, UN-16 | ||
| 233 | |(% style="width:10%" %)FR12|(% style="width:35%" %)Two-Panel Summary View|(% style="width:55%" %)UN-3 | ||
| |
1.1 | 234 | |
| 235 | === 8.2 Non-Functional Requirements Coverage === | ||
| 236 | |||
| |
2.1 | 237 | (% style="width:100%" %) |
| 238 | |=(% style="width:10%" %)NFR#|=(% style="width:35%" %)Requirement|=(% style="width:55%" %)Fulfills User Needs | ||
| 239 | |(% style="width:10%" %)NFR1|(% style="width:35%" %)Performance|(% style="width:55%" %)UN-4 (fast fact-checking), UN-11 (responsive filtering) | ||
| 240 | |(% style="width:10%" %)NFR2|(% style="width:35%" %)Scalability|(% style="width:55%" %)UN-14 (API access at scale) | ||
| 241 | |(% style="width:10%" %)NFR3|(% style="width:35%" %)Transparency|(% style="width:55%" %)UN-1, UN-7, UN-9, UN-13, UN-15 | ||
| |
1.1 | 242 | |
| 243 | === 8.3 AKEL System Coverage === | ||
| 244 | |||
| |
2.1 | 245 | (% style="width:100%" %) |
| 246 | |=(% style="width:45%" %)AKEL Component|=(% style="width:55%" %)Fulfills User Needs | ||
| 247 | |(% style="width:45%" %)Quality Gates|(% style="width:55%" %)UN-9 (methodology transparency) | ||
| 248 | |(% style="width:45%" %)Contradiction Search (Gate 2)|(% style="width:55%" %)UN-8 (understanding disagreement) | ||
| 249 | |(% style="width:45%" %)Bubble Detection|(% style="width:55%" %)UN-10 (manipulation tactics) | ||
| 250 | |(% style="width:45%" %)Publication Modes|(% style="width:55%" %)UN-16 (AI vs. human review status) | ||
| 251 | |(% style="width:45%" %)Risk Tiers|(% style="width:55%" %)UN-16 (appropriate review level) | ||
| |
1.1 | 252 | |
| 253 | === 8.4 Data Model Coverage === | ||
| 254 | |||
| |
2.1 | 255 | (% style="width:100%" %) |
| 256 | |=(% style="width:45%" %)Entity|=(% style="width:55%" %)Fulfills User Needs | ||
| 257 | |(% style="width:45%" %)Source (with track_record_score)|(% style="width:55%" %)UN-5, UN-6 (source reliability) | ||
| 258 | |(% style="width:45%" %)Scenario|(% style="width:55%" %)UN-2, UN-3, UN-8 (context-dependent truth) | ||
| 259 | |(% style="width:45%" %)Verdict (with likelihood_range, uncertainty_factors)|(% style="width:55%" %)UN-1, UN-2, UN-3, UN-8 (detailed assessment) | ||
| 260 | |(% style="width:45%" %)Versioned entities|(% style="width:55%" %)UN-15 (evolution timeline) | ||
| 261 | |(% style="width:45%" %)AuthorType field|(% style="width:55%" %)UN-16 (AI vs. human status) | ||
| |
1.1 | 262 | |
| 263 | == 9. User Need Gaps & Future Considerations == | ||
| 264 | |||
| 265 | This section identifies user needs that may emerge as the platform matures: | ||
| 266 | |||
| 267 | **Potential Future Needs**: | ||
| 268 | * **Collaborative annotation**: Users want to discuss verdicts with others | ||
| 269 | * **Personal tracking**: Users want to track claims they're following | ||
| 270 | * **Custom alerts**: Users want notifications when tracked claims are updated | ||
| 271 | * **Export capabilities**: Users want to export claim analyses for their own documentation | ||
| 272 | * **Comparative analysis**: Users want to compare how different fact-checkers rate the same claim | ||
| 273 | |||
| 274 | **When to address**: These needs should be considered when: | ||
| 275 | 1. User feedback explicitly requests them | ||
| 276 | 2. Usage metrics show users attempting these workflows | ||
| 277 | 3. Competitive analysis shows these as differentiators | ||
| 278 | |||
| 279 | **Principle**: Start simple (current User Needs), add complexity only when metrics prove necessity. | ||
| 280 | |||
| 281 | == 10. Related Pages == | ||
| 282 | |||
| 283 | * [[Requirements>>FactHarbor.Specification.Requirements.WebHome]] - Parent page with roles, rules, and functional requirements | ||
| 284 | * [[Architecture>>FactHarbor.Specification.Architecture.WebHome]] - How requirements are implemented | ||
| 285 | * [[Data Model>>FactHarbor.Specification.Data Model.WebHome]] - Data structures supporting user needs | ||
| 286 | * [[AKEL (AI Knowledge Extraction Layer)>>FactHarbor.Specification.AI Knowledge Extraction Layer (AKEL).WebHome]] - AI system fulfilling automation needs | ||
| 287 | * [[Workflows>>FactHarbor.Specification.Workflows.WebHome]] - User interaction workflows |