User Needs - XWiki

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

=== Key Findings ===

|=**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

=== Assessment ===

(% 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

=== UN-17: In-Article Claim Highlighting ===

123

**As** a reader viewing an article,

124

**I want** to see factual claims highlighted with color-coded credibility indicators (green for well-supported, yellow for uncertain, red for refuted),

125

**so that** I can immediately identify which statements are trustworthy and which require skepticism without interrupting my reading flow.

126

127

**Maps to**: FR7 (Automated Verdicts), FR13 (In-Article Claim Highlighting), NFR1 (Performance - real-time highlighting)

128

129

==== Visual Concept ====

130

131

When reading an article on FactHarbor:

132

133

(% style="font-family:monospace; background-color:#f5f5f5; padding:10px; display:block;" %)

134

(((

135

Regular article text flows normally...

136

137

(% style="background-color:#90EE90; padding:2px 5px;" %)This claim is well-supported by evidence(%%) and you can continue reading...

138

139

More context and explanation...

140

141

(% style="background-color:#FFD700; padding:2px 5px;" %)This claim is uncertain with conflicting evidence(%%) but the article continues...

142

143

Additional information...

144

145

(% style="background-color:#FFB6C6; padding:2px 5px;" %)This claim has been refuted by research(%%) and understanding that helps readers...

146

)))

147

148

**Hover/Click on any highlighted claim** → See verdict, confidence score, and evidence summary

149

150

== 2. Source Tracing & Credibility ==

151

152

=== UN-5: Source Provenance and Track Records ===

153

**As** an article reader,

154

**I want** to trace each piece of evidence back to its original source and see that source's historical track record,

155

**so that** I can assess the reliability of the information chain and learn which sources are consistently trustworthy.

156

157

**Maps to**: FR5 (Evidence Linking), Section 4.1 (Source Requirements - track record system)

158

159

=== UN-6: Publisher Reliability History ===

160

**As** an article reader,

161

**I want** to see historical accuracy track records for sources and publishers,

162

**so that** I can learn which outlets are consistently reliable over time.

163

164

**Maps to**: Section 4.1 (Source Requirements), Data Model (Source entity with track_record_score)

165

166

== 3. Understanding the Analysis ==

167

168

=== UN-7: Evidence Transparency ===

169

**As** a skeptical reader,

170

**I want** to see the evidence and reasoning behind each verdict,

171

**so that** I can judge whether I agree with the assessment and form my own conclusions.

172

173

**Maps to**: FR5 (Evidence Linking), NFR3 (Transparency)

174

175

=== UN-8: Understanding Disagreement and Consensus ===

176

**As** an article reader,

177

**I want** to see which scenarios have strong supporting evidence versus which have conflicting evidence or high uncertainty,

178

**so that** I can understand where legitimate disagreement exists versus where consensus is clear.

179

180

**Maps to**: FR6 (Scenario Comparison), FR7 (Automated Verdicts - uncertainty factors), AKEL Gate 2 (Contradiction Search)

181

182

=== UN-9: Methodology Transparency ===

183

**As** an article reader,

184

**I want** to understand how likelihood ranges and confidence scores are calculated,

185

**so that** I can trust the verification process itself.

186

187

**Maps to**: NFR3 (Transparency), Architecture (documented algorithms), AKEL (Quality Gates)

188

189

== 4. Pattern Recognition & Learning ==

190

191

=== UN-10: Manipulation Tactics Detection ===

192

**As** an article reader,

193

**I want** to see common manipulation tactics or logical fallacies identified in content,

194

**so that** I can recognize them elsewhere and become a more critical consumer of information.

195

196

**Maps to**: AKEL (Bubble Detection), Section 5 (Automated Risk Scoring)

197

198

=== UN-11: Filtered Research ===

199

**As** a researcher,

200

**I want** to filter content by verification status, confidence levels, and source quality,

201

**so that** I can work only with reliable information appropriate for my research needs.

202

203

**Maps to**: FR1 (Claim Classification), Section 4.4 (Confidence Scoring), NFR1 (Performance)

204

205

== 5. Taking Action ==

206

207

=== UN-12: Submit Unchecked Claims ===

208

**As** a reader who finds unchecked claims,

209

**I want** to submit them for verification,

210

**so that** I can help expand fact-checking coverage and contribute to the knowledge base.

211

212

**Maps to**: FR1 (Claim Intake), Section 1.1 (Reader role)

213

214

=== UN-13: Cite FactHarbor Verdicts ===

215

**As** a content creator,

216

**I want** to cite FactHarbor verdicts when sharing content,

217

**so that** I can add credibility to what I publish and help my audience distinguish fact from speculation.

218

219

**Maps to**: FR7 (Automated Verdicts), NFR3 (Transparency - exportable data)

220

221

== 6. Professional Use ==

222

223

=== UN-14: API Access for Integration ===

224

**As** a journalist/researcher,

225

**I want** API access to verification data and claim histories,

226

**so that** I can integrate fact-checking into my professional workflow without manual lookups.

227

228

**Maps to**: Architecture (REST API), NFR2 (Scalability), FR11 (Audit Trail)

229

230

== 7. Understanding Evolution & Trust Labels ==

231

232

=== UN-15: Verdict Evolution Timeline ===

233

234

235

**Status:** Deferred (Not in V1.0)

236

237

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.

238

239

240

**As** an article reader,

241

**I want** to see how a claim's verdict has evolved over time with clear timestamps,

242

**so that** I can understand whether the current assessment is stable or recently changed based on new evidence.

243

244

**Maps to**: ~~FR8 (Deferred)~~, Data Model (Versioned entities), NFR3 (Transparency)

245

246

=== UN-16: AI vs. Human Review Status ===

247

**As** an article reader,

248

**I want** to know if the verdict was AI-generated, human-reviewed, or expert-validated,

249

**so that** I can gauge the appropriate level of trust and understand the review process used.

250

251

**Maps to**: AKEL (Publication Modes), Section 5 (Risk Tiers), Data Model (AuthorType field)

252

253

== 8. User Need → Requirements Mapping Summary ==

254

255

This section provides a consolidated view of how user needs drive system requirements.

256

257

=== 8.1 Functional Requirements Coverage ===

258

259

(% style="width:100%" %)

260

|=(% style="width:10%" %)FR#|=(% style="width:35%" %)Requirement|=(% style="width:55%" %)Fulfills User Needs

261

|(% style="width:10%" %)FR1|(% style="width:35%" %)Claim Intake|(% style="width:55%" %)UN-2, UN-4, UN-12

262

|(% style="width:10%" %)FR4|(% style="width:35%" %)Scenario Generation|(% style="width:55%" %)UN-2, UN-3

263

|(% style="width:10%" %)FR5|(% style="width:35%" %)Evidence Linking|(% style="width:55%" %)UN-5, UN-7

264

|(% style="width:10%" %)FR6|(% style="width:35%" %)Scenario Comparison|(% style="width:55%" %)UN-3, UN-8

265

|(% style="width:10%" %)FR7|(% style="width:35%" %)Automated Verdicts|(% style="width:55%" %)UN-1, UN-2, UN-3, UN-4, UN-13, UN-17

266

|(% style="width:10%" %)FR8|(% style="width:35%" %)Time Evolution|(% style="width:55%" %)UN-15

267

|(% style="width:10%" %)FR11|(% style="width:35%" %)Audit Trail|(% style="width:55%" %)UN-14, UN-16

268

|(% style="width:10%" %)FR12|(% style="width:35%" %)Two-Panel Summary View|(% style="width:55%" %)UN-3

269

|(% style="width:10%" %)FR13|(% style="width:35%" %)In-Article Claim Highlighting|(% style="width:55%" %)UN-17

270

271

=== 8.2 Non-Functional Requirements Coverage ===

272

273

(% style="width:100%" %)

274

|=(% style="width:10%" %)NFR#|=(% style="width:35%" %)Requirement|=(% style="width:55%" %)Fulfills User Needs

275

|(% 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)

276

|(% style="width:10%" %)NFR2|(% style="width:35%" %)Scalability|(% style="width:55%" %)UN-14 (API access at scale)

277

|(% style="width:10%" %)NFR3|(% style="width:35%" %)Transparency|(% style="width:55%" %)UN-1, UN-7, UN-9, UN-13, UN-15

278

279

=== 8.3 AKEL System Coverage ===

280

281

(% style="width:100%" %)

282

|=(% style="width:45%" %)AKEL Component|=(% style="width:55%" %)Fulfills User Needs

283

|(% style="width:45%" %)Quality Gates|(% style="width:55%" %)UN-9 (methodology transparency)

284

|(% style="width:45%" %)Contradiction Search (Gate 2)|(% style="width:55%" %)UN-8 (understanding disagreement)

285

|(% style="width:45%" %)Bubble Detection|(% style="width:55%" %)UN-10 (manipulation tactics)

286

|(% style="width:45%" %)Publication Modes|(% style="width:55%" %)UN-16 (AI vs. human review status)

287

|(% style="width:45%" %)Risk Tiers|(% style="width:55%" %)UN-16 (appropriate review level)

288

289

=== 8.4 Data Model Coverage ===

290

291

(% style="width:100%" %)

292

|=(% style="width:45%" %)Entity|=(% style="width:55%" %)Fulfills User Needs

293

|(% style="width:45%" %)Source (with track_record_score)|(% style="width:55%" %)UN-5, UN-6 (source reliability)

294

|(% style="width:45%" %)Scenario|(% style="width:55%" %)UN-2, UN-3, UN-8 (context-dependent truth)

295

|(% style="width:45%" %)Verdict (with likelihood_range, uncertainty_factors)|(% style="width:55%" %)UN-1, UN-2, UN-3, UN-8 (detailed assessment)

296

|(% style="width:45%" %)Versioned entities|(% style="width:55%" %)UN-15 (evolution timeline)

297

|(% style="width:45%" %)AuthorType field|(% style="width:55%" %)UN-16 (AI vs. human status)

298

299

== 9. User Need Gaps & Future Considerations ==

300

301

This section identifies user needs that may emerge as the platform matures:

302

303

**Potential Future Needs**:

304

* **Collaborative annotation**: Users want to discuss verdicts with others

305

* **Personal tracking**: Users want to track claims they're following

306

* **Custom alerts**: Users want notifications when tracked claims are updated

307

* **Export capabilities**: Users want to export claim analyses for their own documentation

308

* **Comparative analysis**: Users want to compare how different fact-checkers rate the same claim

309

310

**When to address**: These needs should be considered when:

311

1. User feedback explicitly requests them

312

2. Usage metrics show users attempting these workflows

313

3. Competitive analysis shows these as differentiators

314

315

**Principle**: Start simple (current User Needs), add complexity only when metrics prove necessity.

316

317

== 10. Related Pages ==

318

319

* [[Requirements>>FactHarbor.Specification.Requirements.WebHome]] - Parent page with roles, rules, and functional requirements

320

* [[Architecture>>FactHarbor.Specification.Architecture.WebHome]] - How requirements are implemented

321

* [[Data Model>>FactHarbor.Specification.Data Model.WebHome]] - Data structures supporting user needs

322

* [[AKEL (AI Knowledge Extraction Layer)>>FactHarbor.Specification.AI Knowledge Extraction Layer (AKEL).WebHome]] - AI system fulfilling automation needs

323

* [[Workflows>>FactHarbor.Specification.Workflows.WebHome]] - User interaction workflows

324

325

== Additional User Needs (V0.9.70) ==

326

327

=== UN-26: Search Engine Visibility ===

328

329

**As a** content consumer

330