Wiki source code of Requirements
Version 6.8 by Robert Schaub on 2026/01/20 20:31
Hide last authors
| author | version | line-number | content |
|---|---|---|---|
 |
1.1 | 1 | = Requirements = |
| |
2.1 | 2 | |
| 3 | **This page defines Roles, Content States, Rules, and System Requirements for FactHarbor.** | ||
| 4 | |||
| |
1.1 | 5 | **Core Philosophy:** Invest in system improvement, not manual data correction. When AI makes errors, improve the algorithm and re-process automatically. |
| |
2.1 | 6 | |
| 7 | == Navigation == | ||
| 8 | |||
| |
6.7 | 9 | * **[[User Needs>>Archive.FactHarbor.Specification.Requirements.User Needs.WebHome]]** - What users need from FactHarbor (drives these requirements) |
| |
2.1 | 10 | * **This page** - How we fulfill those needs through system design |
| 11 | |||
| 12 | (% class="box infomessage" %) | ||
| 13 | ((( | ||
| 14 | **How to read this page:** | ||
| 15 | |||
| |
6.7 | 16 | 1. **User Needs drive Requirements**: See [[User Needs>>Archive.FactHarbor.Specification.Requirements.User Needs.WebHome]] for what users need |
| |
2.1 | 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 | |||
| |
1.1 | 24 | == 1. Roles == |
| |
2.1 | 25 | |
| 26 | **Fulfills**: UN-12 (Submit claims), UN-13 (Cite verdicts), UN-14 (API access) | ||
| 27 | |||
| |
1.1 | 28 | FactHarbor uses three simple roles plus a reputation system. |
| |
2.1 | 29 | |
| |
1.1 | 30 | === 1.1 Reader === |
| |
2.1 | 31 | |
| |
1.1 | 32 | **Who**: Anyone (no login required) |
| |
2.1 | 33 | |
| |
1.1 | 34 | **Can**: |
| |
6.3 | 35 | |
| |
1.1 | 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) | ||
| |
2.1 | 41 | |
| |
1.1 | 42 | **Cannot**: |
| |
6.3 | 43 | |
| |
1.1 | 44 | * Modify content |
| 45 | * Access edit history details | ||
| |
2.1 | 46 | |
| |
5.1 | 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) |
| |
2.1 | 48 | |
| |
1.1 | 49 | === 1.2 Contributor === |
| |
2.1 | 50 | |
| |
1.1 | 51 | **Who**: Registered users (earns reputation through contributions) |
| |
2.1 | 52 | |
| |
1.1 | 53 | **Can**: |
| |
6.3 | 54 | |
| |
1.1 | 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 | ||
| |
2.1 | 61 | |
| |
1.1 | 62 | **Reputation System**: |
| |
6.3 | 63 | |
| |
1.1 | 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 | ||
| |
2.1 | 69 | |
| |
1.1 | 70 | **Cannot**: |
| |
6.3 | 71 | |
| |
1.1 | 72 | * Delete or hide content (only moderators) |
| 73 | * Override moderation decisions | ||
| |
2.1 | 74 | |
| 75 | **User Needs served**: UN-13 (Cite and contribute) | ||
| 76 | |||
| |
1.1 | 77 | === 1.3 Moderator === |
| |
2.1 | 78 | |
| |
1.1 | 79 | **Who**: Trusted community members with proven track record, appointed by governance board |
| |
2.1 | 80 | |
| |
1.1 | 81 | **Can**: |
| |
6.3 | 82 | |
| |
1.1 | 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 | ||
| |
2.1 | 89 | |
| |
1.1 | 90 | **Cannot**: |
| |
6.3 | 91 | |
| |
1.1 | 92 | * Change governance rules |
| 93 | * Permanently ban users without board approval | ||
| 94 | * Override technical quality gates | ||
| |
2.1 | 95 | |
| |
1.1 | 96 | **Note**: Small team (3-5 initially), supported by automated moderation tools. |
| |
2.1 | 97 | |
| |
1.1 | 98 | === 1.4 Domain Trusted Contributors (Optional, Task-Specific) === |
| |
2.1 | 99 | |
| |
1.1 | 100 | **Who**: Subject matter specialists invited for specific high-stakes disputes |
| |
2.1 | 101 | |
| |
1.1 | 102 | **Not a permanent role**: Contacted externally when needed for contested claims in their domain |
| |
2.1 | 103 | |
| |
1.1 | 104 | **When used**: |
| |
6.3 | 105 | |
| |
1.1 | 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 | ||
| |
2.1 | 110 | |
| |
1.1 | 111 | **Process**: |
| |
6.3 | 112 | |
| |
1.1 | 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 | ||
| |
2.1 | 118 | |
| 119 | **User Needs served**: UN-16 (Expert validation status) | ||
| 120 | |||
| |
1.1 | 121 | == 2. Content States == |
| |
2.1 | 122 | |
| 123 | **Fulfills**: UN-1 (Trust indicators), UN-16 (Review status transparency) | ||
| 124 | |||
| |
1.1 | 125 | FactHarbor uses two content states. Focus is on transparency and confidence scoring, not gatekeeping. |
| |
2.1 | 126 | |
| |
1.1 | 127 | === 2.1 Published === |
| |
2.1 | 128 | |
| |
1.1 | 129 | **Status**: Visible to all users |
| |
2.1 | 130 | |
| |
1.1 | 131 | **Includes**: |
| |
6.3 | 132 | |
| |
1.1 | 133 | * AI-generated analyses (default state) |
| 134 | * User-contributed content | ||
| 135 | * Edited/improved content | ||
| |
2.1 | 136 | |
| |
1.1 | 137 | **Quality Indicators** (displayed with content): |
| |
6.3 | 138 | |
| |
1.1 | 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 | ||
| |
2.1 | 145 | * **Review Status**: AI-generated / Human-reviewed / Expert-validated |
| 146 | |||
| |
1.1 | 147 | **Automatic Warnings**: |
| |
6.3 | 148 | |
| |
1.1 | 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" | ||
| |
2.1 | 153 | |
| 154 | **User Needs served**: UN-1 (Trust score), UN-9 (Methodology transparency), UN-15 (Evolution timeline), UN-16 (Review status) | ||
| 155 | |||
| |
1.1 | 156 | === 2.2 Hidden === |
| |
2.1 | 157 | |
| |
1.1 | 158 | **Status**: Not visible to regular users (only to moderators) |
| |
2.1 | 159 | |
| |
1.1 | 160 | **Reasons**: |
| |
6.3 | 161 | |
| |
1.1 | 162 | * Spam or advertising |
| 163 | * Personal attacks or harassment | ||
| 164 | * Illegal content | ||
| 165 | * Privacy violations | ||
| 166 | * Deliberate misinformation (verified) | ||
| 167 | * Abuse or harmful content | ||
| |
2.1 | 168 | |
| |
1.1 | 169 | **Process**: |
| |
6.3 | 170 | |
| |
1.1 | 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 | ||
| |
2.1 | 175 | |
| |
1.1 | 176 | **Note**: Content is hidden, not deleted (for audit trail) |
| |
2.1 | 177 | |
| |
1.1 | 178 | == 3. Contribution Rules == |
| |
2.1 | 179 | |
| |
1.1 | 180 | === 3.1 All Contributors Must === |
| |
2.1 | 181 | |
| |
1.1 | 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 | ||
| |
2.1 | 187 | |
| |
1.1 | 188 | === 3.2 AKEL (AI System) === |
| |
2.1 | 189 | |
| |
1.1 | 190 | **AKEL is the primary system**. Human contributions supplement and train AKEL. |
| |
2.1 | 191 | |
| |
1.1 | 192 | **AKEL Must**: |
| |
6.3 | 193 | |
| |
1.1 | 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 | ||
| |
2.1 | 200 | |
| |
1.1 | 201 | **When AKEL Makes Errors**: |
| |
6.3 | 202 | |
| |
1.1 | 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?) | ||
| |
2.1 | 207 | |
| |
1.1 | 208 | **Human Role**: Train AKEL through corrections, not replace AKEL |
| |
2.1 | 209 | |
| |
1.1 | 210 | === 3.3 Contributors Should === |
| |
2.1 | 211 | |
| |
1.1 | 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 | ||
| |
2.1 | 217 | |
| |
1.1 | 218 | === 3.4 Moderators Must === |
| |
2.1 | 219 | |
| |
1.1 | 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 | ||
| |
2.1 | 225 | |
| |
1.1 | 226 | == 4. Quality Standards == |
| |
2.1 | 227 | |
| 228 | **Fulfills**: UN-5 (Source reliability), UN-6 (Publisher track records), UN-7 (Evidence transparency), UN-9 (Methodology transparency) | ||
| 229 | |||
| |
1.1 | 230 | === 4.1 Source Requirements === |
| |
2.1 | 231 | |
| |
1.1 | 232 | **Track Record Over Credentials**: |
| |
6.3 | 233 | |
| |
1.1 | 234 | * Sources evaluated by historical accuracy |
| 235 | * Correction policy matters | ||
| 236 | * Independence from conflicts of interest | ||
| 237 | * Methodology transparency | ||
| |
2.1 | 238 | |
| |
1.1 | 239 | **Source Quality Database**: |
| |
6.3 | 240 | |
| |
1.1 | 241 | * Automated tracking of source accuracy |
| 242 | * Correction frequency | ||
| 243 | * Reliability score (updated continuously) | ||
| 244 | * Users can see source track record | ||
| |
2.1 | 245 | |
| |
1.1 | 246 | **No automatic trust** for government, academia, or media - all evaluated by track record. |
| |
2.1 | 247 | |
| 248 | **User Needs served**: UN-5 (Source provenance), UN-6 (Publisher reliability) | ||
| 249 | |||
| |
1.1 | 250 | === 4.2 Claim Requirements === |
| |
2.1 | 251 | |
| |
1.1 | 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 | ||
| |
2.1 | 257 | |
| 258 | **User Needs served**: UN-2 (Claim extraction and verification) | ||
| 259 | |||
| |
1.1 | 260 | === 4.3 Evidence Requirements === |
| |
2.1 | 261 | |
| |
1.1 | 262 | * Publicly accessible (or explain why not) |
| 263 | * Properly cited with attribution | ||
| 264 | * Relevant to claim being evaluated | ||
| 265 | * Original source preferred over secondary | ||
| |
2.1 | 266 | |
| 267 | **User Needs served**: UN-7 (Evidence transparency) | ||
| 268 | |||
| |
1.1 | 269 | === 4.4 Confidence Scoring === |
| |
2.1 | 270 | |
| |
1.1 | 271 | **Automated confidence calculation based on**: |
| |
6.3 | 272 | |
| |
1.1 | 273 | * Source quality scores |
| 274 | * Evidence consistency | ||
| 275 | * Contradiction detection | ||
| 276 | * Completeness of analysis | ||
| 277 | * Historical accuracy of similar claims | ||
| |
2.1 | 278 | |
| |
1.1 | 279 | **Thresholds**: |
| |
6.3 | 280 | |
| |
1.1 | 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" | ||
| |
2.1 | 285 | |
| 286 | **User Needs served**: UN-1 (Trust assessment), UN-9 (Methodology transparency) | ||
| 287 | |||
| |
1.1 | 288 | == 5. Automated Risk Scoring == |
| |
2.1 | 289 | |
| 290 | **Fulfills**: UN-10 (Manipulation detection), UN-16 (Appropriate review level) | ||
| 291 | |||
| |
1.1 | 292 | **Replace manual risk tiers with continuous automated scoring**. |
| |
2.1 | 293 | |
| |
1.1 | 294 | === 5.1 Risk Score Calculation === |
| |
2.1 | 295 | |
| |
1.1 | 296 | **Factors** (weighted algorithm): |
| |
6.3 | 297 | |
| |
1.1 | 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 | ||
| |
2.1 | 303 | |
| |
1.1 | 304 | **Score**: 0-100 (higher = more risk) |
| |
2.1 | 305 | |
| |
1.1 | 306 | === 5.2 Automated Actions === |
| |
2.1 | 307 | |
| |
1.1 | 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 | ||
| |
2.1 | 312 | |
| |
1.1 | 313 | **Continuous monitoring**: Risk score recalculated as new information emerges |
| |
2.1 | 314 | |
| 315 | **User Needs served**: UN-10 (Detect manipulation tactics), UN-16 (Review status) | ||
| 316 | |||
| |
1.1 | 317 | == 6. System Improvement Process == |
| |
2.1 | 318 | |
| |
1.1 | 319 | **Core principle**: Fix the system, not just the data. |
| |
2.1 | 320 | |
| |
1.1 | 321 | === 6.1 Error Capture === |
| |
2.1 | 322 | |
| |
1.1 | 323 | **When users flag errors or make corrections**: |
| |
6.3 | 324 | |
| |
1.1 | 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) | ||
| |
2.1 | 330 | |
| |
1.1 | 331 | === 6.2 Weekly Improvement Cycle === |
| |
2.1 | 332 | |
| |
1.1 | 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 | ||
| |
2.1 | 339 | |
| |
1.1 | 340 | === 6.3 Quality Metrics Dashboard === |
| |
2.1 | 341 | |
| |
1.1 | 342 | **Track continuously**: |
| |
6.3 | 343 | |
| |
1.1 | 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 | ||
| |
2.1 | 351 | |
| |
1.1 | 352 | **Goal**: 10% monthly improvement in error rate |
| |
2.1 | 353 | |
| |
1.1 | 354 | == 7. Automated Quality Monitoring == |
| |
2.1 | 355 | |
| |
1.1 | 356 | **Replace manual audit sampling with automated monitoring**. |
| |
2.1 | 357 | |
| |
1.1 | 358 | === 7.1 Continuous Metrics === |
| |
2.1 | 359 | |
| |
1.1 | 360 | * **Source quality**: Track record database |
| 361 | * **Consistency**: Contradiction detection | ||
| 362 | * **Clarity**: Readability scores | ||
| 363 | * **Completeness**: Field validation | ||
| 364 | * **Accuracy**: User corrections tracked | ||
| |
2.1 | 365 | |
| |
1.1 | 366 | === 7.2 Anomaly Detection === |
| |
2.1 | 367 | |
| |
1.1 | 368 | **Automated alerts for**: |
| |
6.3 | 369 | |
| |
1.1 | 370 | * Sudden quality drops |
| 371 | * Unusual patterns | ||
| 372 | * Contradiction clusters | ||
| 373 | * Source reliability changes | ||
| 374 | * User behavior anomalies | ||
| |
2.1 | 375 | |
| |
1.1 | 376 | === 7.3 Targeted Review === |
| |
2.1 | 377 | |
| |
1.1 | 378 | * Review only flagged items |
| 379 | * Random sampling for calibration (not quotas) | ||
| 380 | * Learn from corrections to improve automation | ||
| |
2.1 | 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 | |||
| |
1.1 | 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 | ||
| |
2.1 | 396 | |
| 397 | ==== FR2 — Claim Normalization ==== | ||
| 398 | |||
| 399 | **Fulfills**: UN-2 (Claim verification) | ||
| 400 | |||
| |
1.1 | 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 | ||
| |
2.1 | 405 | |
| 406 | ==== FR3 — Claim Classification ==== | ||
| 407 | |||
| 408 | **Fulfills**: UN-11 (Filtered research) | ||
| 409 | |||
| |
1.1 | 410 | * Domain: Politics, Science, Health, etc. |
| 411 | * Type: Historical fact, current stat, prediction, etc. | ||
| 412 | * Risk score: Automated calculation | ||
| 413 | * Complexity: Simple, moderate, complex | ||
| |
2.1 | 414 | |
| 415 | === 8.2 Scenario System === | ||
| 416 | |||
| 417 | ==== FR4 — Scenario Generation ==== | ||
| 418 | |||
| |
3.1 | 419 | **Fulfills**: UN-2 (Context-dependent verification), UN-3 (Article summary with FactHarbor analysis summary), UN-8 (Understanding disagreement) |
| |
2.1 | 420 | |
| |
1.1 | 421 | **Automated scenario creation**: |
| |
6.3 | 422 | |
| |
2.1 | 423 | * AKEL analyzes claim and generates likely scenarios (use-cases and contexts) |
| 424 | * Each scenario includes: assumptions, definitions, boundaries, evidence context | ||
| |
1.1 | 425 | * Users can flag incorrect scenarios |
| 426 | * System learns from corrections | ||
| |
2.1 | 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 | |||
| |
1.1 | 434 | * Automated evidence discovery from sources |
| 435 | * Relevance scoring | ||
| 436 | * Contradiction detection | ||
| 437 | * Source quality assessment | ||
| |
2.1 | 438 | |
| 439 | ==== FR6 — Scenario Comparison ==== | ||
| 440 | |||
| |
3.1 | 441 | **Fulfills**: UN-3 (Article summary with FactHarbor analysis summary), UN-8 (Understanding disagreement) |
| |
2.1 | 442 | |
| |
1.1 | 443 | * Side-by-side comparison interface |
| |
2.1 | 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 | |||
| |
3.1 | 452 | **Fulfills**: UN-1 (Trust score), UN-2 (Verification verdicts), UN-3 (Article summary with FactHarbor analysis summary), UN-13 (Cite verdicts) |
| |
2.1 | 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") | ||
| |
1.1 | 457 | * Confidence score displayed prominently |
| |
2.1 | 458 | * Source quality indicators shown |
| |
1.1 | 459 | * Contradictions noted |
| 460 | * Uncertainty acknowledged | ||
| |
2.1 | 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 | ||
| |
1.1 | 470 | * Changes highlighted |
| 471 | * Confidence score trends visible | ||
| |
2.1 | 472 | * Users can see "as of date X, what did we know?" |
| 473 | |||
| |
3.1 | 474 | === 8.4 User Interface & Presentation === |
| |
2.1 | 475 | |
| |
3.1 | 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**: | ||
| |
6.3 | 483 | |
| |
3.1 | 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**: | ||
| |
6.3 | 491 | |
| |
3.1 | 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**: | ||
| |
6.3 | 499 | |
| |
3.1 | 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**: | ||
| |
6.3 | 507 | |
| |
3.1 | 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 | |||
| |
5.1 | 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 | |||
| |
6.1 | 521 | (% class="box" %) |
| 522 | ((( | ||
| 523 | **Article: "New Study Shows Benefits of Mediterranean Diet"** | ||
| |
5.1 | 524 | |
| |
6.1 | 525 | A recent study published in the Journal of Nutrition has revealed new findings about the Mediterranean diet. |
| |
5.1 | 526 | |
| |
6.1 | 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 →]] | ||
| |
6.3 | 534 | |
| 535 | |||
| |
6.1 | 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 →]] | ||
| |
6.3 | 548 | |
| 549 | |||
| |
6.1 | 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 →]] | ||
| |
6.3 | 562 | |
| 563 | |||
| |
6.1 | 564 | ))) |
| 565 | |||
| 566 | Participants also reported feeling more energetic and experiencing better sleep quality, though these were secondary measures. | ||
| 567 | ))) | ||
| 568 | |||
| 569 | **Legend:** | ||
| |
6.3 | 570 | |
| |
6.1 | 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 | |||
| |
5.1 | 576 | ==== Tooltip on Hover/Click ==== |
| 577 | |||
| |
6.1 | 578 | (% class="box infomessage" %) |
| 579 | ((( | ||
| 580 | **FactHarbor Analysis** | ||
| |
5.1 | 581 | |
| |
6.1 | 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:** | ||
| |
6.3 | 589 | |
| |
6.1 | 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:** | ||
| |
6.3 | 595 | |
| |
6.1 | 596 | * Exact percentage varies by study (20-30% range) |
| 597 | |||
| 598 | [[View Full Analysis →]] | ||
| 599 | ))) | ||
| 600 | |||
| |
5.1 | 601 | **Color-Coding System**: |
| |
6.3 | 602 | |
| |
5.1 | 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 | |||
| |
6.1 | 608 | ==== Interactive Highlighting Example (Detailed View) ==== |
| |
5.1 | 609 | |
| |
6.1 | 610 | (% style="width:100%; border-collapse:collapse;" %) |
| 611 | |=**Article Text**|=**Status**|=**Analysis** | ||
| |
6.3 | 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**|((( | ||
| |
6.1 | 618 | **87% confidence** |
| |
5.1 | 619 | |
| |
6.1 | 620 | Meta-analysis of 12 RCTs confirms 23-28% risk reduction |
| |
5.1 | 621 | |
| |
6.1 | 622 | [[View Full Analysis]] |
| |
5.1 | 623 | ))) |
| |
6.3 | 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**|((( | ||
| |
6.1 | 630 | **45% confidence** |
| |
5.1 | 631 | |
| |
6.1 | 632 | Overstated - evidence shows risk reduction, not prevention |
| |
5.1 | 633 | |
| |
6.1 | 634 | [[View Details]] |
| |
5.1 | 635 | ))) |
| |
6.3 | 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**|((( | ||
| |
6.1 | 642 | **15% confidence** |
| |
5.1 | 643 | |
| |
6.1 | 644 | Claim not supported by study; correlation ≠causation |
| |
5.1 | 645 | |
| |
6.1 | 646 | [[View Counter-Evidence]] |
| |
5.1 | 647 | ))) |
| 648 | |||
| |
6.1 | 649 | **Design Notes:** |
| |
6.3 | 650 | |
| |
6.1 | 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 | |||
| |
5.1 | 656 | **User Actions**: |
| |
6.3 | 657 | |
| |
5.1 | 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**: | ||
| |
6.3 | 664 | |
| |
5.1 | 665 | * Hover/click on highlighted claim → Show tooltip with: |
| |
6.3 | 666 | * Claim text |
| 667 | * Verdict (e.g., "WELL SUPPORTED") | ||
| 668 | * Confidence score (e.g., "85%") | ||
| 669 | * Brief evidence summary | ||
| 670 | * Link to detailed analysis | ||
| |
5.1 | 671 | * Toggle highlighting on/off (user preference) |
| 672 | * Adjustable color intensity for accessibility | ||
| 673 | |||
| 674 | **Technical Requirements**: | ||
| |
6.3 | 675 | |
| |
5.1 | 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**: | ||
| |
6.3 | 683 | |
| |
5.1 | 684 | * Highlighting renders within 500ms of page load |
| 685 | * No perceptible delay in reading experience | ||
| 686 | * Efficient DOM manipulation (avoid reflows) | ||
| 687 | |||
| 688 | **Accessibility**: | ||
| |
6.3 | 689 | |
| |
5.1 | 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**: | ||
| |
6.3 | 695 | |
| |
5.1 | 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 | |||
| |
3.1 | 701 | === 8.5 Workflow & Moderation === |
| 702 | |||
| |
2.1 | 703 | ==== FR9 — Publication Workflow ==== |
| 704 | |||
| 705 | **Fulfills**: UN-1 (Fast access to verified content), UN-16 (Clear review status) | ||
| 706 | |||
| |
1.1 | 707 | **Simple flow**: |
| |
6.3 | 708 | |
| |
1.1 | 709 | 1. Claim submitted |
| 710 | 2. AKEL processes (automated) | ||
| |
2.1 | 711 | 3. If confidence > threshold: Publish (labeled as AI-generated) |
| |
1.1 | 712 | 4. If confidence < threshold: Flag for improvement |
| 713 | 5. If risk score > threshold: Flag for moderator | ||
| |
2.1 | 714 | |
| |
1.1 | 715 | **No multi-stage approval process** |
| |
2.1 | 716 | |
| 717 | ==== FR10 — Moderation ==== | ||
| 718 | |||
| |
1.1 | 719 | **Focus on abuse, not routine quality**: |
| |
6.3 | 720 | |
| |
1.1 | 721 | * Automated abuse detection |
| 722 | * Moderators handle flags | ||
| 723 | * Quick response to harmful content | ||
| 724 | * Minimal involvement in routine content | ||
| |
2.1 | 725 | |
| 726 | ==== FR11 — Audit Trail ==== | ||
| 727 | |||
| 728 | **Fulfills**: UN-14 (API access to histories), UN-15 (Evolution tracking) | ||
| 729 | |||
| |
1.1 | 730 | * All edits logged |
| 731 | * Version history public | ||
| 732 | * Moderation decisions documented | ||
| 733 | * System improvements tracked | ||
| |
2.1 | 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 | |||
| |
1.1 | 741 | * Claim processing: < 30 seconds |
| 742 | * Search response: < 2 seconds | ||
| 743 | * Page load: < 3 seconds | ||
| 744 | * 99% uptime | ||
| |
2.1 | 745 | |
| 746 | === 9.2 NFR2 — Scalability === | ||
| 747 | |||
| 748 | **Fulfills**: UN-14 (API access at scale) | ||
| 749 | |||
| |
1.1 | 750 | * Handle 10,000 claims initially |
| 751 | * Scale to 1M+ claims | ||
| 752 | * Support 100K+ concurrent users | ||
| 753 | * Automated processing scales linearly | ||
| |
2.1 | 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 | |||
| |
1.1 | 759 | * All algorithms open source |
| 760 | * All data exportable | ||
| 761 | * All decisions documented | ||
| 762 | * Quality metrics public | ||
| |
2.1 | 763 | |
| 764 | === 9.4 NFR4 — Security & Privacy === | ||
| 765 | |||
| |
1.1 | 766 | * Follow [[Privacy Policy>>FactHarbor.Organisation.How-We-Work-Together.Privacy-Policy]] |
| 767 | * Secure authentication | ||
| 768 | * Data encryption | ||
| 769 | * Regular security audits | ||
| |
2.1 | 770 | |
| 771 | === 9.5 NFR5 — Maintainability === | ||
| 772 | |||
| |
1.1 | 773 | * Modular architecture |
| 774 | * Automated testing | ||
| 775 | * Continuous integration | ||
| 776 | * Comprehensive documentation | ||
| |
2.1 | 777 | |
| 778 | == 10. MVP Scope == | ||
| 779 | |||
| |
1.1 | 780 | **Phase 1 (Months 1-3): Read-Only MVP** |
| |
2.1 | 781 | |
| |
1.1 | 782 | Build: |
| |
6.3 | 783 | |
| |
1.1 | 784 | * Automated claim analysis |
| 785 | * Confidence scoring | ||
| 786 | * Source evaluation | ||
| 787 | * Browse/search interface | ||
| 788 | * User flagging system | ||
| |
2.1 | 789 | |
| |
1.1 | 790 | **Goal**: Prove AI quality before adding user editing |
| |
2.1 | 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 | |||
| |
1.1 | 794 | **Phase 2 (Months 4-6): User Contributions** |
| |
2.1 | 795 | |
| |
1.1 | 796 | Add only if needed: |
| |
6.3 | 797 | |
| |
1.1 | 798 | * Simple editing (Wikipedia-style) |
| 799 | * Reputation system | ||
| 800 | * Basic moderation | ||
| |
5.1 | 801 | * In-article claim highlighting (FR13) |
| |
2.1 | 802 | |
| |
5.1 | 803 | **Additional User Needs fulfilled**: UN-13, UN-17 |
| |
2.1 | 804 | |
| |
1.1 | 805 | **Phase 3 (Months 7-12): Refinement** |
| |
2.1 | 806 | |
| |
1.1 | 807 | * Continuous quality improvement |
| 808 | * Feature additions based on real usage | ||
| 809 | * Scale infrastructure | ||
| |
2.1 | 810 | |
| 811 | **Additional User Needs fulfilled**: UN-14 (API access), UN-15 (Full evolution tracking) | ||
| 812 | |||
| |
1.1 | 813 | **Deferred**: |
| |
6.3 | 814 | |
| |
1.1 | 815 | * Federation (until multiple successful instances exist) |
| 816 | * Complex contribution workflows (focus on automation) | ||
| 817 | * Extensive role hierarchy (keep simple) | ||
| |
2.1 | 818 | |
| 819 | == 11. Success Metrics == | ||
| 820 | |||
| |
1.1 | 821 | **System Quality** (track weekly): |
| |
6.3 | 822 | |
| |
1.1 | 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) | ||
| |
2.1 | 827 | |
| |
1.1 | 828 | **Efficiency** (track monthly): |
| |
6.3 | 829 | |
| |
1.1 | 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%) | ||
| |
2.1 | 834 | |
| |
1.1 | 835 | **User Satisfaction** (track quarterly): |
| |
6.3 | 836 | |
| |
1.1 | 837 | * User flag rate (issues found) |
| 838 | * Correction acceptance rate (flags valid) | ||
| 839 | * Return user rate | ||
| 840 | * Trust indicators (surveys) | ||
| |
2.1 | 841 | |
| 842 | **User Needs Metrics** (track quarterly): | ||
| |
6.3 | 843 | |
| |
2.1 | 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 | ||
| |
5.1 | 849 | * UN-17: % users who enable in-article highlighting; avg. time spent on highlighted vs. non-highlighted articles |
| |
2.1 | 850 | |
| 851 | == 12. Requirements Traceability == | ||
| 852 | |||
| 853 | For full traceability matrix showing which requirements fulfill which user needs, see: | ||
| 854 | |||
| |
6.7 | 855 | * [[User Needs>>Archive.FactHarbor.Specification.Requirements.User Needs.WebHome]] - Section 8 includes comprehensive mapping tables |
| |
2.1 | 856 | |
| 857 | == 13. Related Pages == | ||
| 858 | |||
| |
6.7 | 859 | * **[[User Needs>>Archive.FactHarbor.Specification.Requirements.User Needs.WebHome]]** - What users need (drives these requirements) |
| |
6.5 | 860 | * [[Architecture>>Archive.FactHarbor.Specification.Architecture.WebHome]] - How requirements are implemented |
| |
6.6 | 861 | * [[Data Model>>Archive.FactHarbor.Specification.Data Model.WebHome]] - Data structures supporting requirements |
| |
6.8 | 862 | * [[Workflows>>Archive.FactHarbor.Specification.Workflows.WebHome]] - User interaction workflows |
| |
6.4 | 863 | * [[AKEL>>Archive.FactHarbor.Specification.AI Knowledge Extraction Layer (AKEL).WebHome]] - AI system fulfilling automation requirements |
| |
6.3 | 864 | * [[Global Rules>>Archive.FactHarbor.Organisation.How-We-Work-Together.GlobalRules.WebHome]] |
| |
1.1 | 865 | * [[Privacy Policy>>FactHarbor.Organisation.How-We-Work-Together.Privacy-Policy]] |