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 == 10. MVP Scope ==
779
780 **Phase 1 (Months 1-3): Read-Only MVP**
781
782 Build:
783
784 * Automated claim analysis
785 * Confidence scoring
786 * Source evaluation
787 * Browse/search interface
788 * User flagging system
789
790 **Goal**: Prove AI quality before adding user editing
791
792 **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
793
794 **Phase 2 (Months 4-6): User Contributions**
795
796 Add only if needed:
797
798 * Simple editing (Wikipedia-style)
799 * Reputation system
800 * Basic moderation
801 * In-article claim highlighting (FR13)
802
803 **Additional User Needs fulfilled**: UN-13, UN-17
804
805 **Phase 3 (Months 7-12): Refinement**
806
807 * Continuous quality improvement
808 * Feature additions based on real usage
809 * Scale infrastructure
810
811 **Additional User Needs fulfilled**: UN-14 (API access), UN-15 (Full evolution tracking)
812
813 **Deferred**:
814
815 * Federation (until multiple successful instances exist)
816 * Complex contribution workflows (focus on automation)
817 * Extensive role hierarchy (keep simple)
818
819 == 11. Success Metrics ==
820
821 **System Quality** (track weekly):
822
823 * Error rate by category (target: -10%/month)
824 * Average confidence score (target: increase)
825 * Source quality distribution (target: more high-quality)
826 * Contradiction detection rate (target: increase)
827
828 **Efficiency** (track monthly):
829
830 * Claims processed per hour (target: increase)
831 * Human hours per claim (target: decrease)
832 * Automation coverage (target: >90%)
833 * Re-work rate (target: <5%)
834
835 **User Satisfaction** (track quarterly):
836
837 * User flag rate (issues found)
838 * Correction acceptance rate (flags valid)
839 * Return user rate
840 * Trust indicators (surveys)
841
842 **User Needs Metrics** (track quarterly):
843
844 * UN-1: % users who understand trust scores
845 * UN-4: Time to verify social media claim (target: <30s)
846 * UN-7: % users who access evidence details
847 * UN-8: % users who view multiple scenarios
848 * UN-15: % users who check evolution timeline
849 * UN-17: % users who enable in-article highlighting; avg. time spent on highlighted vs. non-highlighted articles
850
851 == 12. Requirements Traceability ==
852
853 For full traceability matrix showing which requirements fulfill which user needs, see:
854
855 * [[User Needs>>Archive.FactHarbor 2026\.01\.20.Specification.Requirements.User Needs.WebHome]] - Section 8 includes comprehensive mapping tables
856
857 == 13. Related Pages ==
858
859 * **[[User Needs>>Archive.FactHarbor 2026\.01\.20.Specification.Requirements.User Needs.WebHome]]** - What users need (drives these requirements)
860 * [[Architecture>>Archive.FactHarbor 2026\.01\.20.Specification.Architecture.WebHome]] - How requirements are implemented
861 * [[Data Model>>Archive.FactHarbor 2026\.01\.20.Specification.Data Model.WebHome]] - Data structures supporting requirements
862 * [[Workflows>>Archive.FactHarbor 2026\.01\.20.Specification.Workflows.WebHome]] - User interaction workflows
863 * [[AKEL>>Archive.FactHarbor 2026\.01\.20.Specification.AI Knowledge Extraction Layer (AKEL).WebHome]] - AI system fulfilling automation requirements
864 * [[Global Rules>>Archive.FactHarbor.Organisation.How-We-Work-Together.GlobalRules.WebHome]]
865 * [[Privacy Policy>>FactHarbor.Organisation.How-We-Work-Together.Privacy-Policy]]