Skip to Content

Wiki source code of User Needs

Version 2.1 by Robert Schaub on 2025/12/19 09:56
Show last authors
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
25 === UN-3: Article Summary with FactHarbor Analysis Summary ===
26 **As** an article reader,
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.
29
30 **Maps to**: FR7 (Automated Verdicts), FR6 (Scenario Comparison), FR12 (Two-Panel Summary View - Article Summary with FactHarbor Analysis Summary)
31
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
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
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
234
235 === 8.2 Non-Functional Requirements Coverage ===
236
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
242
243 === 8.3 AKEL System Coverage ===
244
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)
252
253 === 8.4 Data Model Coverage ===
254
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)
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