Skip to Content

Wiki source code of Requirements

Version 5.1 by Robert Schaub on 2025/12/19 10:23
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>>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 {{code language="none"}}
493 ┌─────────────────────────────────────────────────────────────────────────────┐
494 │ Article: "New Study Shows Benefits of Mediterranean Diet" │
495 ├─────────────────────────────────────────────────────────────────────────────┤
496 │ │
497 │ A recent study published in the Journal of Nutrition has revealed new │
498 │ findings about the Mediterranean diet. │
499 │ │
500 │ [🟢 Researchers found that Mediterranean diet followers had a 25% lower │
501 │ risk of heart disease compared to control groups] │
502 │ ↑ WELL SUPPORTED • 87% confidence │
503 │ Click for evidence details → │
504 │ │
505 │ The study, which followed 10,000 participants over five years, showed │
506 │ significant improvements in cardiovascular health markers. │
507 │ │
508 │ [🟡 Some experts believe this diet can completely prevent heart attacks] │
509 │ ↑ UNCERTAIN • 45% confidence │
510 │ Overstated - evidence shows risk reduction, not prevention │
511 │ Click for details → │
512 │ │
513 │ Dr. Maria Rodriguez, lead researcher, recommends incorporating more │
514 │ olive oil, fish, and vegetables into daily meals. │
515 │ │
516 │ [🔴 The study proves that saturated fats cause heart disease] │
517 │ ↑ REFUTED • 15% confidence │
518 │ Claim not supported by study design; correlation ≠ causation │
519 │ Click for counter-evidence → │
520 │ │
521 │ Participants also reported feeling more energetic and experiencing │
522 │ better sleep quality, though these were secondary measures. │
523 │ │
524 └─────────────────────────────────────────────────────────────────────────────┘
525
526 Legend:
527 🟢 = Well-supported claim (confidence ≥75%)
528 🟡 = Uncertain claim (confidence 40-74%)
529 🔴 = Refuted/unsupported claim (confidence <40%)
530 Plain text = Non-factual content (context, opinions, recommendations)
531 {{/code}}
532
533 ==== Tooltip on Hover/Click ====
534
535 {{code language="none"}}
536 ┌────────────────────────────────────────────────────────────┐
537 │ FactHarbor Analysis │
538 ├────────────────────────────────────────────────────────────┤
539 │ Claim: │
540 │ "Researchers found that Mediterranean diet followers had │
541 │ a 25% lower risk of heart disease" │
542 │ │
543 │ Verdict: WELL SUPPORTED │
544 │ Confidence: 87% │
545 │ │
546 │ Evidence Summary: │
547 │ • Meta-analysis of 12 RCTs confirms 23-28% risk reduction │
548 │ • Consistent findings across multiple populations │
549 │ • Published in peer-reviewed journal (high credibility) │
550 │ │
551 │ Uncertainty Factors: │
552 │ • Exact percentage varies by study (20-30% range) │
553 │ │
554 │ [View Full Analysis →] │
555 └────────────────────────────────────────────────────────────┘
556 {{/code}}
557
558 **Color-Coding System**:
559 * **Green**: Well-supported claims (confidence ≥75%, strong evidence)
560 * **Yellow/Orange**: Uncertain claims (confidence 40-74%, conflicting or limited evidence)
561 * **Red**: Refuted or unsupported claims (confidence <40%, contradicted by evidence)
562 * **Gray/Neutral**: Non-factual content (opinions, questions, procedural text)
563
564 ==== Interactive Highlighting Example (Table Format) ====
565
566 |=**Article Text**|=**Highlighting**|=**Tooltip Info**
567 |(((A recent study published in the Journal of Nutrition has revealed new findings about the Mediterranean diet.)))|Plain text|//No highlighting - context//
568 |(((Researchers found that Mediterranean diet followers had a 25% lower risk of heart disease compared to control groups)))|(% style="background-color:#90EE90; padding:5px;" %)**🟢 HIGHLIGHTED**|(((
569 **WELL SUPPORTED** • 87% confidence
570
571 Evidence: Meta-analysis of 12 RCTs confirms 23-28% risk reduction
572
573 [[View Full Analysis→]]
574 )))
575 |(((The study, which followed 10,000 participants over five years, showed significant improvements in cardiovascular health markers.)))|Plain text|//No highlighting - methodology//
576 |(((Some experts believe this diet can completely prevent heart attacks)))|(% style="background-color:#FFD700; padding:5px;" %)**🟡 HIGHLIGHTED**|(((
577 **UNCERTAIN** • 45% confidence
578
579 Issue: Overstated - evidence shows risk reduction, not prevention
580
581 [[View Details→]]
582 )))
583 |(((Dr. Rodriguez recommends incorporating more olive oil, fish, and vegetables into daily meals.)))|Plain text|//No highlighting - recommendation//
584 |(((The study proves that saturated fats cause heart disease)))|(% style="background-color:#FFB6C6; padding:5px;" %)**🔴 HIGHLIGHTED**|(((
585 **REFUTED** • 15% confidence
586
587 Issue: Claim not supported by study; correlation ≠ causation
588
589 [[View Counter-Evidence→]]
590 )))
591
592 **User Actions**:
593 * **Hover** over highlighted claim → Tooltip appears
594 * **Click** highlighted claim → Detailed analysis modal/panel
595 * **Toggle** button to turn highlighting on/off
596 * **Keyboard**: Tab through highlighted claims
597
598 **Interaction Design**:
599 * Hover/click on highlighted claim → Show tooltip with:
600 * Claim text
601 * Verdict (e.g., "WELL SUPPORTED")
602 * Confidence score (e.g., "85%")
603 * Brief evidence summary
604 * Link to detailed analysis
605 * Toggle highlighting on/off (user preference)
606 * Adjustable color intensity for accessibility
607
608 **Technical Requirements**:
609 * Real-time highlighting as page loads (non-blocking)
610 * Claim boundary detection (start/end of assertion)
611 * Handle nested or overlapping claims
612 * Preserve original article formatting
613 * Work with various content formats (HTML, plain text, PDFs)
614
615 **Performance Requirements**:
616 * Highlighting renders within 500ms of page load
617 * No perceptible delay in reading experience
618 * Efficient DOM manipulation (avoid reflows)
619
620 **Accessibility**:
621 * Color-blind friendly palette (use patterns/icons in addition to color)
622 * Screen reader compatible (ARIA labels for claim credibility)
623 * Keyboard navigation to highlighted claims
624
625 **Implementation Notes**:
626 * Claims extracted and analyzed by AKEL during initial processing
627 * Highlighting data stored as annotations with byte offsets
628 * Client-side rendering of highlights based on verdict data
629 * Mobile responsive (tap instead of hover)
630
631 === 8.5 Workflow & Moderation ===
632
633 ==== FR9 — Publication Workflow ====
634
635 **Fulfills**: UN-1 (Fast access to verified content), UN-16 (Clear review status)
636
637 **Simple flow**:
638 1. Claim submitted
639 2. AKEL processes (automated)
640 3. If confidence > threshold: Publish (labeled as AI-generated)
641 4. If confidence < threshold: Flag for improvement
642 5. If risk score > threshold: Flag for moderator
643
644 **No multi-stage approval process**
645
646 ==== FR10 — Moderation ====
647
648 **Focus on abuse, not routine quality**:
649 * Automated abuse detection
650 * Moderators handle flags
651 * Quick response to harmful content
652 * Minimal involvement in routine content
653
654 ==== FR11 — Audit Trail ====
655
656 **Fulfills**: UN-14 (API access to histories), UN-15 (Evolution tracking)
657
658 * All edits logged
659 * Version history public
660 * Moderation decisions documented
661 * System improvements tracked
662
663 == 9. Non-Functional Requirements ==
664
665 === 9.1 NFR1 — Performance ===
666
667 **Fulfills**: UN-4 (Fast fact-checking), UN-11 (Responsive filtering)
668
669 * Claim processing: < 30 seconds
670 * Search response: < 2 seconds
671 * Page load: < 3 seconds
672 * 99% uptime
673
674 === 9.2 NFR2 — Scalability ===
675
676 **Fulfills**: UN-14 (API access at scale)
677
678 * Handle 10,000 claims initially
679 * Scale to 1M+ claims
680 * Support 100K+ concurrent users
681 * Automated processing scales linearly
682
683 === 9.3 NFR3 — Transparency ===
684
685 **Fulfills**: UN-7 (Evidence transparency), UN-9 (Methodology transparency), UN-13 (Citable verdicts), UN-15 (Evolution visibility)
686
687 * All algorithms open source
688 * All data exportable
689 * All decisions documented
690 * Quality metrics public
691
692 === 9.4 NFR4 — Security & Privacy ===
693
694 * Follow [[Privacy Policy>>FactHarbor.Organisation.How-We-Work-Together.Privacy-Policy]]
695 * Secure authentication
696 * Data encryption
697 * Regular security audits
698
699 === 9.5 NFR5 — Maintainability ===
700
701 * Modular architecture
702 * Automated testing
703 * Continuous integration
704 * Comprehensive documentation
705
706 == 10. MVP Scope ==
707
708 **Phase 1 (Months 1-3): Read-Only MVP**
709
710 Build:
711 * Automated claim analysis
712 * Confidence scoring
713 * Source evaluation
714 * Browse/search interface
715 * User flagging system
716
717 **Goal**: Prove AI quality before adding user editing
718
719 **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
720
721 **Phase 2 (Months 4-6): User Contributions**
722
723 Add only if needed:
724 * Simple editing (Wikipedia-style)
725 * Reputation system
726 * Basic moderation
727 * In-article claim highlighting (FR13)
728
729 **Additional User Needs fulfilled**: UN-13, UN-17
730
731 **Phase 3 (Months 7-12): Refinement**
732
733 * Continuous quality improvement
734 * Feature additions based on real usage
735 * Scale infrastructure
736
737 **Additional User Needs fulfilled**: UN-14 (API access), UN-15 (Full evolution tracking)
738
739 **Deferred**:
740 * Federation (until multiple successful instances exist)
741 * Complex contribution workflows (focus on automation)
742 * Extensive role hierarchy (keep simple)
743
744 == 11. Success Metrics ==
745
746 **System Quality** (track weekly):
747 * Error rate by category (target: -10%/month)
748 * Average confidence score (target: increase)
749 * Source quality distribution (target: more high-quality)
750 * Contradiction detection rate (target: increase)
751
752 **Efficiency** (track monthly):
753 * Claims processed per hour (target: increase)
754 * Human hours per claim (target: decrease)
755 * Automation coverage (target: >90%)
756 * Re-work rate (target: <5%)
757
758 **User Satisfaction** (track quarterly):
759 * User flag rate (issues found)
760 * Correction acceptance rate (flags valid)
761 * Return user rate
762 * Trust indicators (surveys)
763
764 **User Needs Metrics** (track quarterly):
765 * UN-1: % users who understand trust scores
766 * UN-4: Time to verify social media claim (target: <30s)
767 * UN-7: % users who access evidence details
768 * UN-8: % users who view multiple scenarios
769 * UN-15: % users who check evolution timeline
770 * UN-17: % users who enable in-article highlighting; avg. time spent on highlighted vs. non-highlighted articles
771
772 == 12. Requirements Traceability ==
773
774 For full traceability matrix showing which requirements fulfill which user needs, see:
775
776 * [[User Needs>>FactHarbor.Specification.Requirements.User Needs.WebHome]] - Section 8 includes comprehensive mapping tables
777
778 == 13. Related Pages ==
779
780 * **[[User Needs>>FactHarbor.Specification.Requirements.User Needs.WebHome]]** - What users need (drives these requirements)
781 * [[Architecture>>FactHarbor.Specification.Architecture.WebHome]] - How requirements are implemented
782 * [[Data Model>>FactHarbor.Specification.Data Model.WebHome]] - Data structures supporting requirements
783 * [[Workflows>>FactHarbor.Specification.Workflows.WebHome]] - User interaction workflows
784 * [[AKEL>>FactHarbor.Specification.AI Knowledge Extraction Layer (AKEL).WebHome]] - AI system fulfilling automation requirements
785 * [[Global Rules>>FactHarbor.Organisation.How-We-Work-Together.GlobalRules.WebHome]]
786 * [[Privacy Policy>>FactHarbor.Organisation.How-We-Work-Together.Privacy-Policy]]