Skip to Content

Wiki source code of Requirements

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