Skip to Content

Wiki source code of Requirements

Last modified by Robert Schaub on 2025/12/22 13:50
Hide last authors
Robert Schaub 1.1 1 = Requirements =
2
3 **This page defines Roles, Content States, Rules, and System Requirements for FactHarbor.**
4
5 **Core Philosophy:** Invest in system improvement, not manual data correction. When AI makes errors, improve the algorithm and re-process automatically.
6
7 == Navigation ==
8
9 * **[[User Needs>>FactHarbor.Specification.Requirements.User Needs.WebHome]]** - What users need from FactHarbor (drives these requirements)
10 * **This page** - How we fulfill those needs through system design
11
12 (% class="box infomessage" %)
13 (((
14 **How to read this page:**
15
16 1. **User Needs drive Requirements**: See [[User Needs>>FactHarbor.Specification.Requirements.User Needs.WebHome]] for what users need
17 2. **Requirements define implementation**: This page shows how we fulfill those needs
18 3. **Functional Requirements (FR)**: Specific features and capabilities
19 4. **Non-Functional Requirements (NFR)**: Quality attributes (performance, security, etc.)
20
21 Each requirement references which User Needs it fulfills.
22 )))
23
24 == 1. Roles ==
25
26 **Fulfills**: UN-12 (Submit claims), UN-13 (Cite verdicts), UN-14 (API access)
27
28 FactHarbor uses three simple roles plus a reputation system.
29
30 === 1.1 Reader ===
31
32 **Who**: Anyone (no login required)
33
34 **Can**:
35 * Browse and search claims
36 * View scenarios, evidence, verdicts, and confidence scores
37 * Flag issues or errors
38 * Use filters, search, and visualization tools
39 * Submit claims automatically (new claims added if not duplicates)
40
41 **Cannot**:
42 * Modify content
43 * Access edit history details
44
45 **User Needs served**: UN-1 (Trust assessment), UN-2 (Claim verification), UN-3 (Article summary with FactHarbor analysis summary), UN-4 (Social media fact-checking), UN-5 (Source tracing), UN-7 (Evidence transparency), UN-8 (Understanding disagreement), UN-12 (Submit claims), UN-17 (In-article highlighting)
46
47 === 1.2 Contributor ===
48
49 **Who**: Registered users (earns reputation through contributions)
50
51 **Can**:
52 * Everything a Reader can do
53 * Edit claims, evidence, and scenarios
54 * Add sources and citations
55 * Suggest improvements to AI-generated content
56 * Participate in discussions
57 * Earn reputation points for quality contributions
58
59 **Reputation System**:
60 * New contributors: Limited edit privileges
61 * Established contributors (established reputation): Full edit access
62 * Trusted contributors (substantial reputation): Can approve certain changes
63 * Reputation earned through: Accepted edits, helpful flags, quality contributions
64 * Reputation lost through: Reverted edits, invalid flags, abuse
65
66 **Cannot**:
67 * Delete or hide content (only moderators)
68 * Override moderation decisions
69
70 **User Needs served**: UN-13 (Cite and contribute)
71
72 === 1.3 Moderator ===
73
74 **Who**: Trusted community members with proven track record, appointed by governance board
75
76 **Can**:
77 * Review flagged content
78 * Hide harmful or abusive content
79 * Resolve disputes between contributors
80 * Issue warnings or temporary bans
81 * Make final decisions on content disputes
82 * Access full audit logs
83
84 **Cannot**:
85 * Change governance rules
86 * Permanently ban users without board approval
87 * Override technical quality gates
88
89 **Note**: Small team (3-5 initially), supported by automated moderation tools.
90
91 === 1.4 Domain Trusted Contributors (Optional, Task-Specific) ===
92
93 **Who**: Subject matter specialists invited for specific high-stakes disputes
94
95 **Not a permanent role**: Contacted externally when needed for contested claims in their domain
96
97 **When used**:
98 * Medical claims with life/safety implications
99 * Legal interpretations with significant impact
100 * Scientific claims with high controversy
101 * Technical claims requiring specialized knowledge
102
103 **Process**:
104 * Moderator identifies need for expert input
105 * Contact expert externally (don't require them to be users)
106 * Trusted Contributor provides written opinion with sources
107 * Opinion added to claim record
108 * Trusted Contributor acknowledged in claim
109
110 **User Needs served**: UN-16 (Expert validation status)
111
112 == 2. Content States ==
113
114 **Fulfills**: UN-1 (Trust indicators), UN-16 (Review status transparency)
115
116 FactHarbor uses two content states. Focus is on transparency and confidence scoring, not gatekeeping.
117
118 === 2.1 Published ===
119
120 **Status**: Visible to all users
121
122 **Includes**:
123 * AI-generated analyses (default state)
124 * User-contributed content
125 * Edited/improved content
126
127 **Quality Indicators** (displayed with content):
128 * **Confidence Score**: 0-100% (AI's confidence in analysis)
129 * **Source Quality Score**: 0-100% (based on source track record)
130 * **Controversy Flag**: If high dispute/edit activity
131 * **Completeness Score**: % of expected fields filled
132 * **Last Updated**: Date of most recent change
133 * **Edit Count**: Number of revisions
134 * **Review Status**: AI-generated / Human-reviewed / Expert-validated
135
136 **Automatic Warnings**:
137 * Confidence < 60%: "Low confidence - use caution"
138 * Source quality < 40%: "Sources may be unreliable"
139 * High controversy: "Disputed - multiple interpretations exist"
140 * Medical/Legal/Safety domain: "Seek professional advice"
141
142 **User Needs served**: UN-1 (Trust score), UN-9 (Methodology transparency), UN-15 (Evolution timeline), UN-16 (Review status)
143
144 === 2.2 Hidden ===
145
146 **Status**: Not visible to regular users (only to moderators)
147
148 **Reasons**:
149 * Spam or advertising
150 * Personal attacks or harassment
151 * Illegal content
152 * Privacy violations
153 * Deliberate misinformation (verified)
154 * Abuse or harmful content
155
156 **Process**:
157 * Automated detection flags for moderator review
158 * Moderator confirms and hides
159 * Original author notified with reason
160 * Can appeal to board if disputes moderator decision
161
162 **Note**: Content is hidden, not deleted (for audit trail)
163
164 == 3. Contribution Rules ==
165
166 === 3.1 All Contributors Must ===
167
168 * Provide sources for factual claims
169 * Use clear, neutral language in FactHarbor's own summaries
170 * Respect others and maintain civil discourse
171 * Accept community feedback constructively
172 * Focus on improving quality, not protecting ego
173
174 === 3.2 AKEL (AI System) ===
175
176 **AKEL is the primary system**. Human contributions supplement and train AKEL.
177
178 **AKEL Must**:
179 * Mark all outputs as AI-generated
180 * Display confidence scores prominently
181 * Provide source citations
182 * Flag uncertainty clearly
183 * Identify contradictions in evidence
184 * Learn from human corrections
185
186 **When AKEL Makes Errors**:
187 1. Capture the error pattern (what, why, how common)
188 2. Improve the system (better prompt, model, validation)
189 3. Re-process affected claims automatically
190 4. Measure improvement (did quality increase?)
191
192 **Human Role**: Train AKEL through corrections, not replace AKEL
193
194 === 3.3 Contributors Should ===
195
196 * Improve clarity and structure
197 * Add missing sources
198 * Flag errors for system improvement
199 * Suggest better ways to present information
200 * Participate in quality discussions
201
202 === 3.4 Moderators Must ===
203
204 * Be impartial
205 * Document moderation decisions
206 * Respond to appeals promptly
207 * Use automated tools to scale efforts
208 * Focus on abuse/harm, not routine quality control
209
210 == 4. Quality Standards ==
211
212 **Fulfills**: UN-5 (Source reliability), UN-6 (Publisher track records), UN-7 (Evidence transparency), UN-9 (Methodology transparency)
213
214 === 4.1 Source Requirements ===
215
216 **Track Record Over Credentials**:
217 * Sources evaluated by historical accuracy
218 * Correction policy matters
219 * Independence from conflicts of interest
220 * Methodology transparency
221
222 **Source Quality Database**:
223 * Automated tracking of source accuracy
224 * Correction frequency
225 * Reliability score (updated continuously)
226 * Users can see source track record
227
228 **No automatic trust** for government, academia, or media - all evaluated by track record.
229
230 **User Needs served**: UN-5 (Source provenance), UN-6 (Publisher reliability)
231
232 === 4.2 Claim Requirements ===
233
234 * Clear subject and assertion
235 * Verifiable with available information
236 * Sourced (or explicitly marked as needing sources)
237 * Neutral language in FactHarbor summaries
238 * Appropriate context provided
239
240 **User Needs served**: UN-2 (Claim extraction and verification)
241
242 === 4.3 Evidence Requirements ===
243
244 * Publicly accessible (or explain why not)
245 * Properly cited with attribution
246 * Relevant to claim being evaluated
247 * Original source preferred over secondary
248
249 **User Needs served**: UN-7 (Evidence transparency)
250
251 === 4.4 Confidence Scoring ===
252
253 **Automated confidence calculation based on**:
254 * Source quality scores
255 * Evidence consistency
256 * Contradiction detection
257 * Completeness of analysis
258 * Historical accuracy of similar claims
259
260 **Thresholds**:
261 * < 40%: Too low to publish (needs improvement)
262 * 40-60%: Published with "Low confidence" warning
263 * 60-80%: Published as standard
264 * 80-100%: Published as "High confidence"
265
266 **User Needs served**: UN-1 (Trust assessment), UN-9 (Methodology transparency)
267
268 == 5. Automated Risk Scoring ==
269
270 **Fulfills**: UN-10 (Manipulation detection), UN-16 (Appropriate review level)
271
272 **Replace manual risk tiers with continuous automated scoring**.
273
274 === 5.1 Risk Score Calculation ===
275
276 **Factors** (weighted algorithm):
277 * **Domain sensitivity**: Medical, legal, safety auto-flagged higher
278 * **Potential impact**: Views, citations, spread
279 * **Controversy level**: Flags, disputes, edit wars
280 * **Uncertainty**: Low confidence, contradictory evidence
281 * **Source reliability**: Track record of sources used
282
283 **Score**: 0-100 (higher = more risk)
284
285 === 5.2 Automated Actions ===
286
287 * **Score > 80**: Flag for moderator review before publication
288 * **Score 60-80**: Publish with prominent warnings
289 * **Score 40-60**: Publish with standard warnings
290 * **Score < 40**: Publish normally
291
292 **Continuous monitoring**: Risk score recalculated as new information emerges
293
294 **User Needs served**: UN-10 (Detect manipulation tactics), UN-16 (Review status)
295
296 == 6. System Improvement Process ==
297
298 **Core principle**: Fix the system, not just the data.
299
300 === 6.1 Error Capture ===
301
302 **When users flag errors or make corrections**:
303 1. What was wrong? (categorize)
304 2. What should it have been?
305 3. Why did the system fail? (root cause)
306 4. How common is this pattern?
307 5. Store in ErrorPattern table (improvement queue)
308
309 === 6.2 Weekly Improvement Cycle ===
310
311 1. **Review**: Analyze top error patterns
312 2. **Develop**: Create fix (prompt, model, validation)
313 3. **Test**: Validate fix on sample claims
314 4. **Deploy**: Roll out if quality improves
315 5. **Re-process**: Automatically update affected claims
316 6. **Monitor**: Track quality metrics
317
318 === 6.3 Quality Metrics Dashboard ===
319
320 **Track continuously**:
321 * Error rate by category
322 * Source quality distribution
323 * Confidence score trends
324 * User flag rate (issues found)
325 * Correction acceptance rate
326 * Re-work rate
327 * Claims processed per hour
328
329 **Goal**: 10% monthly improvement in error rate
330
331 == 7. Automated Quality Monitoring ==
332
333 **Replace manual audit sampling with automated monitoring**.
334
335 === 7.1 Continuous Metrics ===
336
337 * **Source quality**: Track record database
338 * **Consistency**: Contradiction detection
339 * **Clarity**: Readability scores
340 * **Completeness**: Field validation
341 * **Accuracy**: User corrections tracked
342
343 === 7.2 Anomaly Detection ===
344
345 **Automated alerts for**:
346 * Sudden quality drops
347 * Unusual patterns
348 * Contradiction clusters
349 * Source reliability changes
350 * User behavior anomalies
351
352 === 7.3 Targeted Review ===
353
354 * Review only flagged items
355 * Random sampling for calibration (not quotas)
356 * Learn from corrections to improve automation
357
358 == 8. Functional Requirements ==
359
360 This section defines specific features that fulfill user needs.
361
362 === 8.1 Claim Intake & Normalization ===
363
364 ==== FR1 — Claim Intake ====
365
366 **Fulfills**: UN-2 (Claim extraction), UN-4 (Quick fact-checking), UN-12 (Submit claims)
367
368 * Users submit claims via simple form or API
369 * Claims can be text, URL, or image
370 * Duplicate detection (semantic similarity)
371 * Auto-categorization by domain
372
373 ==== FR2 — Claim Normalization ====
374
375 **Fulfills**: UN-2 (Claim verification)
376
377 * Standardize to clear assertion format
378 * Extract key entities (who, what, when, where)
379 * Identify claim type (factual, predictive, evaluative)
380 * Link to existing similar claims
381
382 ==== FR3 — Claim Classification ====
383
384 **Fulfills**: UN-11 (Filtered research)
385
386 * Domain: Politics, Science, Health, etc.
387 * Type: Historical fact, current stat, prediction, etc.
388 * Risk score: Automated calculation
389 * Complexity: Simple, moderate, complex
390
391 === 8.2 Scenario System ===
392
393 ==== FR4 — Scenario Generation ====
394
395 **Fulfills**: UN-2 (Context-dependent verification), UN-3 (Article summary with FactHarbor analysis summary), UN-8 (Understanding disagreement)
396
397 **Automated scenario creation**:
398 * AKEL analyzes claim and generates likely scenarios (use-cases and contexts)
399 * Each scenario includes: assumptions, definitions, boundaries, evidence context
400 * Users can flag incorrect scenarios
401 * System learns from corrections
402
403 **Key Concept**: Scenarios represent different interpretations or contexts (e.g., "Clinical trials with healthy adults" vs. "Real-world data with diverse populations")
404
405 ==== FR5 — Evidence Linking ====
406
407 **Fulfills**: UN-5 (Source tracing), UN-7 (Evidence transparency)
408
409 * Automated evidence discovery from sources
410 * Relevance scoring
411 * Contradiction detection
412 * Source quality assessment
413
414 ==== FR6 — Scenario Comparison ====
415
416 **Fulfills**: UN-3 (Article summary with FactHarbor analysis summary), UN-8 (Understanding disagreement)
417
418 * Side-by-side comparison interface
419 * Highlight key differences between scenarios
420 * Show evidence supporting each scenario
421 * Display confidence scores per scenario
422
423 === 8.3 Verdicts & Analysis ===
424
425 ==== FR7 — Automated Verdicts ====
426
427 **Fulfills**: UN-1 (Trust score), UN-2 (Verification verdicts), UN-3 (Article summary with FactHarbor analysis summary), UN-13 (Cite verdicts)
428
429 * AKEL generates verdict based on evidence within each scenario
430 * **Likelihood range** displayed (e.g., "0.70-0.85 (likely true)") - NOT binary true/false
431 * **Uncertainty factors** explicitly listed (e.g., "Small sample sizes", "Long-term effects unknown")
432 * Confidence score displayed prominently
433 * Source quality indicators shown
434 * Contradictions noted
435 * Uncertainty acknowledged
436
437 **Key Innovation**: Detailed probabilistic verdicts with explicit uncertainty, not binary judgments
438
439 ==== FR8 — Time Evolution ====
440
441 **Fulfills**: UN-15 (Verdict evolution timeline)
442
443 * Claims and verdicts update as new evidence emerges
444 * Version history maintained for all verdicts
445 * Changes highlighted
446 * Confidence score trends visible
447 * Users can see "as of date X, what did we know?"
448
449 === 8.4 User Interface & Presentation ===
450
451 ==== FR12 — Two-Panel Summary View (Article Summary with FactHarbor Analysis Summary) ====
452
453 **Fulfills**: UN-3 (Article Summary with FactHarbor Analysis Summary)
454
455 **Purpose**: Provide side-by-side comparison of what a document claims vs. FactHarbor's complete analysis of its credibility
456
457 **Left Panel: Article Summary**:
458 * Document title, source, and claimed credibility
459 * "The Big Picture" - main thesis or position change
460 * "Key Findings" - structured summary of document's main claims
461 * "Reasoning" - document's explanation for positions
462 * "Conclusion" - document's bottom line
463
464 **Right Panel: FactHarbor Analysis Summary**:
465 * FactHarbor's independent source credibility assessment
466 * Claim-by-claim verdicts with confidence scores
467 * Methodology assessment (strengths, limitations)
468 * Overall verdict on document quality
469 * Analysis ID for reference
470
471 **Design Principles**:
472 * No scrolling required - both panels visible simultaneously
473 * Visual distinction between "what they say" and "FactHarbor's analysis"
474 * Color coding for verdicts (supported, uncertain, refuted)
475 * Confidence percentages clearly visible
476 * Mobile responsive (panels stack vertically on small screens)
477
478 **Implementation Notes**:
479 * Generated automatically by AKEL for every analyzed document
480 * Updates when verdict evolves (maintains version history)
481 * Exportable as standalone summary report
482 * Shareable via permanent URL
483
484 ==== FR13 — In-Article Claim Highlighting ====
485
486 **Fulfills**: UN-17 (In-article claim highlighting)
487
488 **Purpose**: Enable readers to quickly assess claim credibility while reading by visually highlighting factual claims with color-coded indicators
489
490 ==== Visual Example: Article with Highlighted Claims ====
491
492 (% class="box" %)
493 (((
494 **Article: "New Study Shows Benefits of Mediterranean Diet"**
495
496 A recent study published in the Journal of Nutrition has revealed new findings about the Mediterranean diet.
497
498 (% class="box successmessage" style="margin:10px 0;" %)
499 (((
500 🟢 **Researchers found that Mediterranean diet followers had a 25% lower risk of heart disease compared to control groups**
501
502 (% style="font-size:0.9em; color:#666;" %)
503 ↑ WELL SUPPORTED • 87% confidence
504 [[Click for evidence details →]]
505 (%%)
506 )))
507
508 The study, which followed 10,000 participants over five years, showed significant improvements in cardiovascular health markers.
509
510 (% class="box warningmessage" style="margin:10px 0;" %)
511 (((
512 🟡 **Some experts believe this diet can completely prevent heart attacks**
513
514 (% style="font-size:0.9em; color:#666;" %)
515 ↑ UNCERTAIN • 45% confidence
516 Overstated - evidence shows risk reduction, not prevention
517 [[Click for details →]]
518 (%%)
519 )))
520
521 Dr. Maria Rodriguez, lead researcher, recommends incorporating more olive oil, fish, and vegetables into daily meals.
522
523 (% class="box errormessage" style="margin:10px 0;" %)
524 (((
525 🔴 **The study proves that saturated fats cause heart disease**
526
527 (% style="font-size:0.9em; color:#666;" %)
528 ↑ REFUTED • 15% confidence
529 Claim not supported by study design; correlation ≠ causation
530 [[Click for counter-evidence →]]
531 (%%)
532 )))
533
534 Participants also reported feeling more energetic and experiencing better sleep quality, though these were secondary measures.
535 )))
536
537 **Legend:**
538 * 🟢 = Well-supported claim (confidence ≥75%)
539 * 🟡 = Uncertain claim (confidence 40-74%)
540 * 🔴 = Refuted/unsupported claim (confidence <40%)
541 * Plain text = Non-factual content (context, opinions, recommendations)
542
543 ==== Tooltip on Hover/Click ====
544
545 (% class="box infomessage" %)
546 (((
547 **FactHarbor Analysis**
548
549 **Claim:**
550 "Researchers found that Mediterranean diet followers had a 25% lower risk of heart disease"
551
552 **Verdict:** WELL SUPPORTED
553 **Confidence:** 87%
554
555 **Evidence Summary:**
556 * Meta-analysis of 12 RCTs confirms 23-28% risk reduction
557 * Consistent findings across multiple populations
558 * Published in peer-reviewed journal (high credibility)
559
560 **Uncertainty Factors:**
561 * Exact percentage varies by study (20-30% range)
562
563 [[View Full Analysis →]]
564 )))
565
566 **Color-Coding System**:
567 * **Green**: Well-supported claims (confidence ≥75%, strong evidence)
568 * **Yellow/Orange**: Uncertain claims (confidence 40-74%, conflicting or limited evidence)
569 * **Red**: Refuted or unsupported claims (confidence <40%, contradicted by evidence)
570 * **Gray/Neutral**: Non-factual content (opinions, questions, procedural text)
571
572 ==== Interactive Highlighting Example (Detailed View) ====
573
574 (% style="width:100%; border-collapse:collapse;" %)
575 |=**Article Text**|=**Status**|=**Analysis**
576 |(((A recent study published in the Journal of Nutrition has revealed new findings about the Mediterranean diet.)))|(% style="text-align:center;" %)Plain text|(% style="font-style:italic; color:#888;" %)Context - no highlighting
577 |(((//Researchers found that Mediterranean diet followers had a 25% lower risk of heart disease compared to control groups//)))|(% style="background-color:#D4EDDA; text-align:center; padding:8px;" %)🟢 **WELL SUPPORTED**|(((
578 **87% confidence**
579
580 Meta-analysis of 12 RCTs confirms 23-28% risk reduction
581
582 [[View Full Analysis]]
583 )))
584 |(((The study, which followed 10,000 participants over five years, showed significant improvements in cardiovascular health markers.)))|(% style="text-align:center;" %)Plain text|(% style="font-style:italic; color:#888;" %)Methodology - no highlighting
585 |(((//Some experts believe this diet can completely prevent heart attacks//)))|(% style="background-color:#FFF3CD; text-align:center; padding:8px;" %)🟡 **UNCERTAIN**|(((
586 **45% confidence**
587
588 Overstated - evidence shows risk reduction, not prevention
589
590 [[View Details]]
591 )))
592 |(((Dr. Rodriguez recommends incorporating more olive oil, fish, and vegetables into daily meals.)))|(% style="text-align:center;" %)Plain text|(% style="font-style:italic; color:#888;" %)Recommendation - no highlighting
593 |(((//The study proves that saturated fats cause heart disease//)))|(% style="background-color:#F8D7DA; text-align:center; padding:8px;" %)🔴 **REFUTED**|(((
594 **15% confidence**
595
596 Claim not supported by study; correlation ≠ causation
597
598 [[View Counter-Evidence]]
599 )))
600
601 **Design Notes:**
602 * Highlighted claims use italics to distinguish from plain text
603 * Color backgrounds match XWiki message box colors (success/warning/error)
604 * Status column shows verdict prominently
605 * Analysis column provides quick summary with link to details
606
607 **User Actions**:
608 * **Hover** over highlighted claim → Tooltip appears
609 * **Click** highlighted claim → Detailed analysis modal/panel
610 * **Toggle** button to turn highlighting on/off
611 * **Keyboard**: Tab through highlighted claims
612
613 **Interaction Design**:
614 * Hover/click on highlighted claim → Show tooltip with:
615 * Claim text
616 * Verdict (e.g., "WELL SUPPORTED")
617 * Confidence score (e.g., "85%")
618 * Brief evidence summary
619 * Link to detailed analysis
620 * Toggle highlighting on/off (user preference)
621 * Adjustable color intensity for accessibility
622
623 **Technical Requirements**:
624 * Real-time highlighting as page loads (non-blocking)
625 * Claim boundary detection (start/end of assertion)
626 * Handle nested or overlapping claims
627 * Preserve original article formatting
628 * Work with various content formats (HTML, plain text, PDFs)
629
630 **Performance Requirements**:
631 * Highlighting renders within 500ms of page load
632 * No perceptible delay in reading experience
633 * Efficient DOM manipulation (avoid reflows)
634
635 **Accessibility**:
636 * Color-blind friendly palette (use patterns/icons in addition to color)
637 * Screen reader compatible (ARIA labels for claim credibility)
638 * Keyboard navigation to highlighted claims
639
640 **Implementation Notes**:
641 * Claims extracted and analyzed by AKEL during initial processing
642 * Highlighting data stored as annotations with byte offsets
643 * Client-side rendering of highlights based on verdict data
644 * Mobile responsive (tap instead of hover)
645
646 === 8.5 Workflow & Moderation ===
647
648 ==== FR9 — Publication Workflow ====
649
650 **Fulfills**: UN-1 (Fast access to verified content), UN-16 (Clear review status)
651
652 **Simple flow**:
653 1. Claim submitted
654 2. AKEL processes (automated)
655 3. If confidence > threshold: Publish (labeled as AI-generated)
656 4. If confidence < threshold: Flag for improvement
657 5. If risk score > threshold: Flag for moderator
658
659 **No multi-stage approval process**
660
661 ==== FR10 — Moderation ====
662
663 **Focus on abuse, not routine quality**:
664 * Automated abuse detection
665 * Moderators handle flags
666 * Quick response to harmful content
667 * Minimal involvement in routine content
668
669 ==== FR11 — Audit Trail ====
670
671 **Fulfills**: UN-14 (API access to histories), UN-15 (Evolution tracking)
672
673 * All edits logged
674 * Version history public
675 * Moderation decisions documented
676 * System improvements tracked
677
678 == 9. Non-Functional Requirements ==
679
680 === 9.1 NFR1 — Performance ===
681
682 **Fulfills**: UN-4 (Fast fact-checking), UN-11 (Responsive filtering)
683
684 * Claim processing: < 30 seconds
685 * Search response: < 2 seconds
686 * Page load: < 3 seconds
687 * 99% uptime
688
689 === 9.2 NFR2 — Scalability ===
690
691 **Fulfills**: UN-14 (API access at scale)
692
693 * Handle 10,000 claims initially
694 * Scale to 1M+ claims
695 * Support 100K+ concurrent users
696 * Automated processing scales linearly
697
698 === 9.3 NFR3 — Transparency ===
699
700 **Fulfills**: UN-7 (Evidence transparency), UN-9 (Methodology transparency), UN-13 (Citable verdicts), UN-15 (Evolution visibility)
701
702 * All algorithms open source
703 * All data exportable
704 * All decisions documented
705 * Quality metrics public
706
707 === 9.4 NFR4 — Security & Privacy ===
708
709 * Follow [[Privacy Policy>>FactHarbor.Organisation.How-We-Work-Together.Privacy-Policy]]
710 * Secure authentication
711 * Data encryption
712 * Regular security audits
713
714 === 9.5 NFR5 — Maintainability ===
715
716 * Modular architecture
717 * Automated testing
718 * Continuous integration
719 * Comprehensive documentation
720
721 === NFR11: AKEL Quality Assurance Framework ===
722
723 **Fulfills:** AI safety, IFCN methodology transparency
724
725 **Specification:**
726
727 Multi-layer AI quality gates to detect hallucinations, low-confidence results, and logical inconsistencies.
728
729 ==== Quality Gate 1: Claim Extraction Validation ====
730
731 **Purpose:** Ensure extracted claims are factual assertions (not opinions/predictions)
732
733 **Checks:**
734 1. **Factual Statement Test:** Is this verifiable? (Yes/No)
735 2. **Opinion Detection:** Contains hedging language? ("I think", "probably", "best")
736 3. **Future Prediction Test:** Makes claims about future events?
737 4. **Specificity Score:** Contains specific entities, numbers, dates?
738
739 **Thresholds:**
740 * Factual: Must be "Yes"
741 * Opinion markers: <2 hedging phrases
742 * Specificity: ≥3 specific elements
743
744 **Action if Failed:** Flag as "Non-verifiable", do NOT generate verdict
745
746 ==== Quality Gate 2: Evidence Relevance Validation ====
747
748 **Purpose:** Ensure AI-linked evidence actually relates to claim
749
750 **Checks:**
751 1. **Semantic Similarity Score:** Evidence vs. claim (embeddings)
752 2. **Entity Overlap:** Shared people/places/things?
753 3. **Topic Relevance:** Discusses claim subject?
754
755 **Thresholds:**
756 * Similarity: ≥0.6 (cosine similarity)
757 * Entity overlap: ≥1 shared entity
758 * Topic relevance: ≥0.5
759
760 **Action if Failed:** Discard irrelevant evidence
761
762 ==== Quality Gate 3: Scenario Coherence Check ====
763
764 **Purpose:** Validate scenario assumptions are logical and complete
765
766 **Checks:**
767 1. **Completeness:** All required fields populated
768 2. **Internal Consistency:** Assumptions don't contradict
769 3. **Distinguishability:** Scenarios meaningfully different
770
771 **Thresholds:**
772 * Required fields: 100%
773 * Contradiction score: <0.3
774 * Scenario similarity: <0.8
775
776 **Action if Failed:** Merge duplicates, reduce confidence -20%
777
778 ==== Quality Gate 4: Verdict Confidence Assessment ====
779
780 **Purpose:** Only publish high-confidence verdicts
781
782 **Checks:**
783 1. **Evidence Count:** Minimum 2 sources
784 2. **Source Quality:** Average reliability ≥0.6
785 3. **Evidence Agreement:** Supporting vs. contradicting ≥0.6
786 4. **Uncertainty Factors:** Hedging in reasoning
787
788 **Confidence Tiers:**
789 * **HIGH (80-100%):** ≥3 sources, ≥0.7 quality, ≥80% agreement
790 * **MEDIUM (50-79%):** ≥2 sources, ≥0.6 quality, ≥60% agreement
791 * **LOW (0-49%):** <2 sources OR low quality/agreement
792 * **INSUFFICIENT:** <2 sources → DO NOT PUBLISH
793
794 **Implementation Phases:**
795 * **POC1:** Gates 1 & 4 only (basic validation)
796 * **POC2:** All 4 gates (complete framework)
797 * **V1.0:** Hardened with <5% hallucination rate
798
799 **Acceptance Criteria:**
800 * ✅ All gates operational
801 * ✅ Hallucination rate <5%
802 * ✅ Quality metrics public
803
804 === NFR12: Security Controls ===
805
806 **Fulfills:** Production readiness, legal compliance
807
808 **Requirements:**
809 1. **Input Validation:** SQL injection, XSS, CSRF prevention
810 2. **Rate Limiting:** 5 analyses per minute per IP
811 3. **Authentication:** Secure sessions, API key rotation
812 4. **Data Protection:** HTTPS, encryption, backups
813 5. **Security Audit:** Penetration testing, GDPR compliance
814
815 **Milestone:** Beta 0 (essential), V1.0 (complete) **BLOCKER**
816
817 === NFR13: Quality Metrics Transparency ===
818
819 **Fulfills:** IFCN transparency, user trust
820
821 **Public Metrics:**
822 * Quality gates performance
823 * Evidence quality stats
824 * Hallucination rate
825 * User feedback
826
827 **Milestone:** POC2 (internal), Beta 0 (public), V1.0 (real-time)
828
829 == 10. Requirements Priority Matrix ==
830
831 This table shows all functional and non-functional requirements ordered by urgency and priority.
832
833 **Note:** Implementation phases (POC1, POC2, Beta 0, V1.0) are defined in [[POC Requirements>>FactHarbor.Specification.POC.Requirements]] and [[Implementation Roadmap>>FactHarbor.Implementation-Roadmap.WebHome]], not in this priority matrix.
834
835 **Priority Levels:**
836 * **CRITICAL** - System doesn't work without it, or major safety/legal risk
837 * **HIGH** - Core functionality, essential for success
838 * **MEDIUM** - Important but not blocking
839 * **LOW** - Nice to have, can be deferred
840
841 **Urgency Levels:**
842 * **HIGH** - Immediate need (critical for proof of concept)
843 * **MEDIUM** - Important but not immediate
844 * **LOW** - Future enhancement
845
846 |= ID |= Title |= Priority |= Urgency
847 | **HIGH URGENCY** |||
848 | **FR1** | Claim Intake | CRITICAL | HIGH
849 | **FR5** | Evidence Collection | CRITICAL | HIGH
850 | **FR7** | Verdict Computation | CRITICAL | HIGH
851 | **NFR11** | Quality Assurance Framework | CRITICAL | HIGH
852 | **FR2** | Claim Normalization | HIGH | HIGH
853 | **FR3** | Claim Classification | HIGH | HIGH
854 | **FR4** | Scenario Generation | HIGH | HIGH
855 | **FR6** | Evidence Evaluation | HIGH | HIGH
856 | **MEDIUM URGENCY** |||
857 | **NFR12** | Security Controls | CRITICAL | MEDIUM
858 | **FR9** | Corrections | HIGH | MEDIUM
859 | **FR44** | ClaimReview Schema | HIGH | MEDIUM
860 | **FR45** | Corrections Notification | HIGH | MEDIUM
861 | **FR48** | Safety Framework | HIGH | MEDIUM
862 | **NFR3** | Transparency | HIGH | MEDIUM
863 | **NFR13** | Quality Metrics | HIGH | MEDIUM
864 | **FR8** | User Contribution | MEDIUM | MEDIUM
865 | **FR10** | Publishing | MEDIUM | MEDIUM
866 | **FR13** | API | MEDIUM | MEDIUM
867 | **FR46** | Image Verification | MEDIUM | MEDIUM
868 | **FR47** | Archive.org Integration | MEDIUM | MEDIUM
869 | **NFR1** | Performance | MEDIUM | MEDIUM
870 | **NFR2** | Scalability | MEDIUM | MEDIUM
871 | **NFR4** | Security & Privacy | MEDIUM | MEDIUM
872 | **NFR5** | Maintainability | MEDIUM | MEDIUM
873 | **LOW URGENCY** |||
874 | **FR11** | Social Sharing | LOW | LOW
875 | **FR12** | Notifications | LOW | LOW
876 | **FR49** | A/B Testing | LOW | LOW
877 | **FR50** | OSINT Toolkit Integration | LOW | LOW
878 | **FR51** | Video Verification System | LOW | LOW
879 | **FR52** | Interactive Detection Training | LOW | LOW
880 | **FR53** | Cross-Organizational Sharing | LOW | LOW
881
882 **Total:** 31 requirements (23 Functional, 8 Non-Functional)
883
884 **See also:**
885 * [[POC Requirements>>FactHarbor.Specification.POC.Requirements]] - POC1 scope and simplifications
886 * [[Implementation Roadmap>>FactHarbor.Implementation-Roadmap.WebHome]] - Phase-by-phase implementation plan
887 * [[User Needs>>FactHarbor.Specification.Requirements.User Needs.WebHome]] - Foundation that drives these requirements
888
889 === 10.1 User Needs Priority ===
890
891 User Needs (UN) are the foundation that drives functional and non-functional requirements. They are not independently prioritized; instead, their priority is inherited from the FR/NFR requirements they drive.
892
893 |= ID |= Title |= Drives Requirements
894 | **UN-1** | Trust Assessment at a Glance | Multiple FR/NFR
895 | **UN-2** | Claim Extraction and Verification | FR1-7
896 | **UN-3** | Article Summary with FactHarbor Analysis Summary | FR4
897 | **UN-4** | Social Media Fact-Checking | FR1, FR4
898 | **UN-5** | Source Provenance and Track Records | FR6
899 | **UN-6** | Publisher Reliability History | FR6
900 | **UN-7** | Evidence Transparency | NFR3
901 | **UN-8** | Understanding Disagreement and Consensus | FR4
902 | **UN-9** | Methodology Transparency | NFR3, NFR11
903 | **UN-10** | Manipulation Tactics Detection | FR48
904 | **UN-11** | Filtered Research | FR3
905 | **UN-12** | Submit Unchecked Claims | FR8
906 | **UN-13** | Cite FactHarbor Verdicts | FR10
907 | **UN-14** | API Access for Integration | FR13
908 | **UN-15** | Verdict Evolution Timeline | FR7
909 | **UN-16** | AI vs. Human Review Status | FR9
910 | **UN-17** | In-Article Claim Highlighting | FR1
911 | **UN-26** | Search Engine Visibility | FR44
912 | **UN-27** | Visual Claim Verification | FR46
913 | **UN-28** | Safe Contribution Environment | FR48
914
915 **Total:** 20 User Needs
916
917 **Note:** Each User Need inherits priority from the requirements it drives. For example, UN-2 (Claim Extraction and Verification) drives FR1-7, which are CRITICAL/HIGH priority, therefore UN-2 is also critical to the project.
918
919 == 11. MVP Scope ==
920
921 **Phase 1 (Months 1-3): Read-Only MVP**
922
923 Build:
924 * Automated claim analysis
925 * Confidence scoring
926 * Source evaluation
927 * Browse/search interface
928 * User flagging system
929
930 **Goal**: Prove AI quality before adding user editing
931
932 **User Needs fulfilled in Phase 1**: UN-1, UN-2, UN-3, UN-4, UN-5, UN-6, UN-7, UN-8, UN-9, UN-12
933
934 **Phase 2 (Months 4-6): User Contributions**
935
936 Add only if needed:
937 * Simple editing (Wikipedia-style)
938 * Reputation system
939 * Basic moderation
940 * In-article claim highlighting (FR13)
941
942 **Additional User Needs fulfilled**: UN-13, UN-17
943
944 **Phase 3 (Months 7-12): Refinement**
945
946 * Continuous quality improvement
947 * Feature additions based on real usage
948 * Scale infrastructure
949
950 **Additional User Needs fulfilled**: UN-14 (API access), UN-15 (Full evolution tracking)
951
952 **Deferred**:
953 * Federation (until multiple successful instances exist)
954 * Complex contribution workflows (focus on automation)
955 * Extensive role hierarchy (keep simple)
956
957 == 12. Success Metrics ==
958
959 **System Quality** (track weekly):
960 * Error rate by category (target: -10%/month)
961 * Average confidence score (target: increase)
962 * Source quality distribution (target: more high-quality)
963 * Contradiction detection rate (target: increase)
964
965 **Efficiency** (track monthly):
966 * Claims processed per hour (target: increase)
967 * Human hours per claim (target: decrease)
968 * Automation coverage (target: >90%)
969 * Re-work rate (target: <5%)
970
971 **User Satisfaction** (track quarterly):
972 * User flag rate (issues found)
973 * Correction acceptance rate (flags valid)
974 * Return user rate
975 * Trust indicators (surveys)
976
977 **User Needs Metrics** (track quarterly):
978 * UN-1: % users who understand trust scores
979 * UN-4: Time to verify social media claim (target: <30s)
980 * UN-7: % users who access evidence details
981 * UN-8: % users who view multiple scenarios
982 * UN-15: % users who check evolution timeline
983 * UN-17: % users who enable in-article highlighting; avg. time spent on highlighted vs. non-highlighted articles
984
985 == 13. Requirements Traceability ==
986
987 For full traceability matrix showing which requirements fulfill which user needs, see:
988
989 * [[User Needs>>FactHarbor.Specification.Requirements.User Needs.WebHome]] - Section 8 includes comprehensive mapping tables
990
991 == 14. Related Pages ==
992
993 **Non-Functional Requirements (see Section 9):**
994 * [[NFR11 — AKEL Quality Assurance Framework>>#NFR11]]
995 * [[NFR12 — Security Controls>>#NFR12]]
996 * [[NFR13 — Quality Metrics Transparency>>#NFR13]]
997
998 **Other Requirements:**
999 * [[User Needs>>FactHarbor.Specification.Requirements.User Needs.WebHome]]
1000 * [[V1.0 Requirements>>FactHarbor.Specification.Requirements.V10.]]
1001 * [[Gap Analysis>>FactHarbor.Specification.Requirements.GapAnalysis]]
1002
1003 * **[[User Needs>>FactHarbor.Specification.Requirements.User Needs.WebHome]]** - What users need (drives these requirements)
1004 * [[Architecture>>FactHarbor.Specification.Architecture.WebHome]] - How requirements are implemented
1005 * [[Data Model>>FactHarbor.Specification.Data Model.WebHome]] - Data structures supporting requirements
1006 * [[Workflows>>FactHarbor.Specification.Workflows.WebHome]] - User interaction workflows
1007 * [[AKEL>>FactHarbor.Specification.AI Knowledge Extraction Layer (AKEL).WebHome]] - AI system fulfilling automation requirements
1008 * [[Global Rules>>FactHarbor.Organisation.How-We-Work-Together.GlobalRules.WebHome]]
1009 * [[Privacy Policy>>FactHarbor.Organisation.How-We-Work-Together.Privacy-Policy]]
1010
1011 = V0.9.70 Additional Requirements =
1012
1013 == Functional Requirements (Additional) ==
1014
1015 === FR44: ClaimReview Schema Implementation ===
1016
1017 Generate valid ClaimReview structured data for Google/Bing visibility.
1018
1019 **Schema.org Mapping:**
1020 * 80-100% likelihood → 5 (Highly Supported)
1021 * 60-79% → 4 (Supported)
1022 * 40-59% → 3 (Mixed)
1023 * 20-39% → 2 (Questionable)
1024 * 0-19% → 1 (Refuted)
1025
1026 **Milestone:** V1.0
1027
1028 === FR45: User Corrections Notification System ===
1029
1030 Notify users when analyses are corrected.
1031
1032 **Mechanisms:**
1033 1. In-page banner (30 days)
1034 2. Public correction log
1035 3. Email notifications (opt-in)
1036 4. RSS/API feed
1037
1038 **Milestone:** Beta 0 (basic), V1.0 (complete) **BLOCKER**
1039
1040 === FR46: Image Verification System ===
1041
1042 **Methods:**
1043 1. Reverse image search
1044 2. EXIF metadata analysis
1045 3. Manipulation detection (basic)
1046 4. Context verification
1047
1048 **Milestone:** Beta 0 (basic), V1.0 (extended)
1049
1050 === FR47: Archive.org Integration ===
1051
1052 Auto-save evidence sources to Wayback Machine.
1053
1054 **Milestone:** Beta 0
1055
1056 === FR48: Safety Framework for Contributors ===
1057
1058 Protect contributors from harassment and legal threats.
1059
1060 **Milestone:** V1.1
1061
1062 === FR49: A/B Testing Framework ===
1063
1064 Test AKEL approaches and UI designs systematically.
1065
1066 **Milestone:** V1.0
1067
1068 === FR50-FR53: Future Enhancements (V2.0+) ===
1069
1070 * **FR50:** OSINT Toolkit Integration
1071 * **FR51:** Video Verification System
1072 * **FR52:** Interactive Detection Training
1073 * **FR53:** Cross-Organizational Sharing
1074
1075 **Milestone:** V2.0+ (12-18 months post-launch)
1076
1077 == Enhanced Existing Requirements ==
1078
1079 === FR7: Automated Verdicts (Enhanced with Quality Gates) ===
1080
1081 **POC1+ Enhancement:**
1082
1083 After AKEL generates verdict, it passes through quality gates:
1084
1085 {{code}}
1086 Workflow:
1087 1. Extract claims
1088 ↓
1089 2. [GATE 1] Validate fact-checkable
1090 ↓
1091 3. Generate scenarios
1092 ↓
1093 4. Generate verdicts
1094 ↓
1095 5. [GATE 4] Validate confidence
1096 ↓
1097 6. Display to user
1098 {{/code}}
1099
1100 **Updated Verdict States:**
1101 * PUBLISHED
1102 * INSUFFICIENT_EVIDENCE
1103 * NON_FACTUAL_CLAIM
1104 * PROCESSING
1105 * ERROR
1106
1107 === FR4: Analysis Summary (Enhanced with Quality Metadata) ===
1108
1109 **POC1+ Enhancement:**
1110
1111 Display quality indicators:
1112
1113 {{code}}
1114 Analysis Summary:
1115 Verifiable Claims: 3/5
1116 High Confidence Verdicts: 1
1117 Medium Confidence: 2
1118 Evidence Sources: 12
1119 Avg Source Quality: 0.73
1120 Quality Score: 8.5/10
1121 {{/code}}
1122