Wiki source code of Requirements
Last modified by Robert Schaub on 2025/12/24 21:46
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 | |||
| |
4.1 | 9 | * **[[User Needs>>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 | |||
| |
4.1 | 16 | 1. **User Needs drive Requirements**: See [[User Needs>>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**: |
| 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) | ||
| |
2.1 | 40 | |
| |
1.1 | 41 | **Cannot**: |
| 42 | * Modify content | ||
| 43 | * Access edit history details | ||
| |
2.1 | 44 | |
| |
5.1 | 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) |
| |
2.1 | 46 | |
| |
1.1 | 47 | === 1.2 Contributor === |
| |
2.1 | 48 | |
| |
1.1 | 49 | **Who**: Registered users (earns reputation through contributions) |
| |
2.1 | 50 | |
| |
1.1 | 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 | ||
| |
2.1 | 58 | |
| |
1.1 | 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 | ||
| |
2.1 | 65 | |
| |
1.1 | 66 | **Cannot**: |
| 67 | * Delete or hide content (only moderators) | ||
| 68 | * Override moderation decisions | ||
| |
2.1 | 69 | |
| 70 | **User Needs served**: UN-13 (Cite and contribute) | ||
| 71 | |||
| |
1.1 | 72 | === 1.3 Moderator === |
| |
2.1 | 73 | |
| |
1.1 | 74 | **Who**: Trusted community members with proven track record, appointed by governance board |
| |
2.1 | 75 | |
| |
1.1 | 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 | ||
| |
2.1 | 83 | |
| |
1.1 | 84 | **Cannot**: |
| 85 | * Change governance rules | ||
| 86 | * Permanently ban users without board approval | ||
| 87 | * Override technical quality gates | ||
| |
2.1 | 88 | |
| |
1.1 | 89 | **Note**: Small team (3-5 initially), supported by automated moderation tools. |
| |
2.1 | 90 | |
| |
1.1 | 91 | === 1.4 Domain Trusted Contributors (Optional, Task-Specific) === |
| |
2.1 | 92 | |
| |
1.1 | 93 | **Who**: Subject matter specialists invited for specific high-stakes disputes |
| |
2.1 | 94 | |
| |
1.1 | 95 | **Not a permanent role**: Contacted externally when needed for contested claims in their domain |
| |
2.1 | 96 | |
| |
1.1 | 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 | ||
| |
2.1 | 102 | |
| |
1.1 | 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 | ||
| |
2.1 | 109 | |
| 110 | **User Needs served**: UN-16 (Expert validation status) | ||
| 111 | |||
| |
1.1 | 112 | == 2. Content States == |
| |
2.1 | 113 | |
| 114 | **Fulfills**: UN-1 (Trust indicators), UN-16 (Review status transparency) | ||
| 115 | |||
| |
1.1 | 116 | FactHarbor uses two content states. Focus is on transparency and confidence scoring, not gatekeeping. |
| |
2.1 | 117 | |
| |
1.1 | 118 | === 2.1 Published === |
| |
2.1 | 119 | |
| |
1.1 | 120 | **Status**: Visible to all users |
| |
2.1 | 121 | |
| |
1.1 | 122 | **Includes**: |
| 123 | * AI-generated analyses (default state) | ||
| 124 | * User-contributed content | ||
| 125 | * Edited/improved content | ||
| |
2.1 | 126 | |
| |
1.1 | 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 | ||
| |
2.1 | 134 | * **Review Status**: AI-generated / Human-reviewed / Expert-validated |
| 135 | |||
| |
1.1 | 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" | ||
| |
2.1 | 141 | |
| 142 | **User Needs served**: UN-1 (Trust score), UN-9 (Methodology transparency), UN-15 (Evolution timeline), UN-16 (Review status) | ||
| 143 | |||
| |
1.1 | 144 | === 2.2 Hidden === |
| |
2.1 | 145 | |
| |
1.1 | 146 | **Status**: Not visible to regular users (only to moderators) |
| |
2.1 | 147 | |
| |
1.1 | 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 | ||
| |
2.1 | 155 | |
| |
1.1 | 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 | ||
| |
2.1 | 161 | |
| |
1.1 | 162 | **Note**: Content is hidden, not deleted (for audit trail) |
| |
2.1 | 163 | |
| |
1.1 | 164 | == 3. Contribution Rules == |
| |
2.1 | 165 | |
| |
1.1 | 166 | === 3.1 All Contributors Must === |
| |
2.1 | 167 | |
| |
1.1 | 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 | ||
| |
2.1 | 173 | |
| |
1.1 | 174 | === 3.2 AKEL (AI System) === |
| |
2.1 | 175 | |
| |
1.1 | 176 | **AKEL is the primary system**. Human contributions supplement and train AKEL. |
| |
2.1 | 177 | |
| |
1.1 | 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 | ||
| |
2.1 | 185 | |
| |
1.1 | 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?) | ||
| |
2.1 | 191 | |
| |
1.1 | 192 | **Human Role**: Train AKEL through corrections, not replace AKEL |
| |
2.1 | 193 | |
| |
1.1 | 194 | === 3.3 Contributors Should === |
| |
2.1 | 195 | |
| |
1.1 | 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 | ||
| |
2.1 | 201 | |
| |
1.1 | 202 | === 3.4 Moderators Must === |
| |
2.1 | 203 | |
| |
1.1 | 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 | ||
| |
2.1 | 209 | |
| |
1.1 | 210 | == 4. Quality Standards == |
| |
2.1 | 211 | |
| 212 | **Fulfills**: UN-5 (Source reliability), UN-6 (Publisher track records), UN-7 (Evidence transparency), UN-9 (Methodology transparency) | ||
| 213 | |||
| |
1.1 | 214 | === 4.1 Source Requirements === |
| |
2.1 | 215 | |
| |
1.1 | 216 | **Track Record Over Credentials**: |
| 217 | * Sources evaluated by historical accuracy | ||
| 218 | * Correction policy matters | ||
| 219 | * Independence from conflicts of interest | ||
| 220 | * Methodology transparency | ||
| |
2.1 | 221 | |
| |
1.1 | 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 | ||
| |
2.1 | 227 | |
| |
1.1 | 228 | **No automatic trust** for government, academia, or media - all evaluated by track record. |
| |
2.1 | 229 | |
| 230 | **User Needs served**: UN-5 (Source provenance), UN-6 (Publisher reliability) | ||
| 231 | |||
| |
1.1 | 232 | === 4.2 Claim Requirements === |
| |
2.1 | 233 | |
| |
1.1 | 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 | ||
| |
2.1 | 239 | |
| 240 | **User Needs served**: UN-2 (Claim extraction and verification) | ||
| 241 | |||
| |
1.1 | 242 | === 4.3 Evidence Requirements === |
| |
2.1 | 243 | |
| |
1.1 | 244 | * Publicly accessible (or explain why not) |
| 245 | * Properly cited with attribution | ||
| 246 | * Relevant to claim being evaluated | ||
| 247 | * Original source preferred over secondary | ||
| |
2.1 | 248 | |
| 249 | **User Needs served**: UN-7 (Evidence transparency) | ||
| 250 | |||
| |
1.1 | 251 | === 4.4 Confidence Scoring === |
| |
2.1 | 252 | |
| |
1.1 | 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 | ||
| |
2.1 | 259 | |
| |
1.1 | 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" | ||
| |
2.1 | 265 | |
| 266 | **User Needs served**: UN-1 (Trust assessment), UN-9 (Methodology transparency) | ||
| 267 | |||
| |
1.1 | 268 | == 5. Automated Risk Scoring == |
| |
2.1 | 269 | |
| 270 | **Fulfills**: UN-10 (Manipulation detection), UN-16 (Appropriate review level) | ||
| 271 | |||
| |
1.1 | 272 | **Replace manual risk tiers with continuous automated scoring**. |
| |
2.1 | 273 | |
| |
1.1 | 274 | === 5.1 Risk Score Calculation === |
| |
2.1 | 275 | |
| |
1.1 | 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 | ||
| |
2.1 | 282 | |
| |
1.1 | 283 | **Score**: 0-100 (higher = more risk) |
| |
2.1 | 284 | |
| |
1.1 | 285 | === 5.2 Automated Actions === |
| |
2.1 | 286 | |
| |
1.1 | 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 | ||
| |
2.1 | 291 | |
| |
1.1 | 292 | **Continuous monitoring**: Risk score recalculated as new information emerges |
| |
2.1 | 293 | |
| 294 | **User Needs served**: UN-10 (Detect manipulation tactics), UN-16 (Review status) | ||
| 295 | |||
| |
1.1 | 296 | == 6. System Improvement Process == |
| |
2.1 | 297 | |
| |
1.1 | 298 | **Core principle**: Fix the system, not just the data. |
| |
2.1 | 299 | |
| |
1.1 | 300 | === 6.1 Error Capture === |
| |
2.1 | 301 | |
| |
1.1 | 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) | ||
| |
2.1 | 308 | |
| |
1.1 | 309 | === 6.2 Weekly Improvement Cycle === |
| |
2.1 | 310 | |
| |
1.1 | 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 | ||
| |
2.1 | 317 | |
| |
1.1 | 318 | === 6.3 Quality Metrics Dashboard === |
| |
2.1 | 319 | |
| |
1.1 | 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 | ||
| |
2.1 | 328 | |
| |
1.1 | 329 | **Goal**: 10% monthly improvement in error rate |
| |
2.1 | 330 | |
| |
1.1 | 331 | == 7. Automated Quality Monitoring == |
| |
2.1 | 332 | |
| |
1.1 | 333 | **Replace manual audit sampling with automated monitoring**. |
| |
2.1 | 334 | |
| |
1.1 | 335 | === 7.1 Continuous Metrics === |
| |
2.1 | 336 | |
| |
1.1 | 337 | * **Source quality**: Track record database |
| 338 | * **Consistency**: Contradiction detection | ||
| 339 | * **Clarity**: Readability scores | ||
| 340 | * **Completeness**: Field validation | ||
| 341 | * **Accuracy**: User corrections tracked | ||
| |
2.1 | 342 | |
| |
1.1 | 343 | === 7.2 Anomaly Detection === |
| |
2.1 | 344 | |
| |
1.1 | 345 | **Automated alerts for**: |
| 346 | * Sudden quality drops | ||
| 347 | * Unusual patterns | ||
| 348 | * Contradiction clusters | ||
| 349 | * Source reliability changes | ||
| 350 | * User behavior anomalies | ||
| |
2.1 | 351 | |
| |
1.1 | 352 | === 7.3 Targeted Review === |
| |
2.1 | 353 | |
| |
1.1 | 354 | * Review only flagged items |
| 355 | * Random sampling for calibration (not quotas) | ||
| 356 | * Learn from corrections to improve automation | ||
| |
2.1 | 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 | |||
| |
1.1 | 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 | ||
| |
2.1 | 372 | |
| 373 | ==== FR2 — Claim Normalization ==== | ||
| 374 | |||
| 375 | **Fulfills**: UN-2 (Claim verification) | ||
| 376 | |||
| |
1.1 | 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 | ||
| |
2.1 | 381 | |
| 382 | ==== FR3 — Claim Classification ==== | ||
| 383 | |||
| 384 | **Fulfills**: UN-11 (Filtered research) | ||
| 385 | |||
| |
1.1 | 386 | * Domain: Politics, Science, Health, etc. |
| 387 | * Type: Historical fact, current stat, prediction, etc. | ||
| 388 | * Risk score: Automated calculation | ||
| 389 | * Complexity: Simple, moderate, complex | ||
| |
2.1 | 390 | |
| 391 | === 8.2 Scenario System === | ||
| 392 | |||
| 393 | ==== FR4 — Scenario Generation ==== | ||
| 394 | |||
| |
3.1 | 395 | **Fulfills**: UN-2 (Context-dependent verification), UN-3 (Article summary with FactHarbor analysis summary), UN-8 (Understanding disagreement) |
| |
2.1 | 396 | |
| |
1.1 | 397 | **Automated scenario creation**: |
| |
2.1 | 398 | * AKEL analyzes claim and generates likely scenarios (use-cases and contexts) |
| 399 | * Each scenario includes: assumptions, definitions, boundaries, evidence context | ||
| |
1.1 | 400 | * Users can flag incorrect scenarios |
| 401 | * System learns from corrections | ||
| |
2.1 | 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 | |||
| |
1.1 | 409 | * Automated evidence discovery from sources |
| 410 | * Relevance scoring | ||
| 411 | * Contradiction detection | ||
| 412 | * Source quality assessment | ||
| |
2.1 | 413 | |
| 414 | ==== FR6 — Scenario Comparison ==== | ||
| 415 | |||
| |
3.1 | 416 | **Fulfills**: UN-3 (Article summary with FactHarbor analysis summary), UN-8 (Understanding disagreement) |
| |
2.1 | 417 | |
| |
1.1 | 418 | * Side-by-side comparison interface |
| |
2.1 | 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 | |||
| |
3.1 | 427 | **Fulfills**: UN-1 (Trust score), UN-2 (Verification verdicts), UN-3 (Article summary with FactHarbor analysis summary), UN-13 (Cite verdicts) |
| |
2.1 | 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") | ||
| |
1.1 | 432 | * Confidence score displayed prominently |
| |
2.1 | 433 | * Source quality indicators shown |
| |
1.1 | 434 | * Contradictions noted |
| 435 | * Uncertainty acknowledged | ||
| |
2.1 | 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 | ||
| |
1.1 | 445 | * Changes highlighted |
| 446 | * Confidence score trends visible | ||
| |
2.1 | 447 | * Users can see "as of date X, what did we know?" |
| 448 | |||
| |
3.1 | 449 | === 8.4 User Interface & Presentation === |
| |
2.1 | 450 | |
| |
3.1 | 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 | |||
| |
5.1 | 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 | |||
| |
6.1 | 492 | (% class="box" %) |
| 493 | ((( | ||
| 494 | **Article: "New Study Shows Benefits of Mediterranean Diet"** | ||
| |
5.1 | 495 | |
| |
6.1 | 496 | A recent study published in the Journal of Nutrition has revealed new findings about the Mediterranean diet. |
| |
5.1 | 497 | |
| |
6.1 | 498 | (% class="box successmessage" style="margin:10px 0;" %) |
| 499 | ((( | ||
| 500 | 🟢 **Researchers found that Mediterranean diet followers had a 25% lower risk of heart disease compared to control groups** | ||
| 501 | |||
| 502 | (% style="font-size:0.9em; color:#666;" %) | ||
| 503 | ↑ WELL SUPPORTED • 87% confidence | ||
| 504 | [[Click for evidence details →]] | ||
| 505 | (%%) | ||
| 506 | ))) | ||
| 507 | |||
| 508 | The study, which followed 10,000 participants over five years, showed significant improvements in cardiovascular health markers. | ||
| 509 | |||
| 510 | (% class="box warningmessage" style="margin:10px 0;" %) | ||
| 511 | ((( | ||
| 512 | 🟡 **Some experts believe this diet can completely prevent heart attacks** | ||
| 513 | |||
| 514 | (% style="font-size:0.9em; color:#666;" %) | ||
| 515 | ↑ UNCERTAIN • 45% confidence | ||
| 516 | Overstated - evidence shows risk reduction, not prevention | ||
| 517 | [[Click for details →]] | ||
| 518 | (%%) | ||
| 519 | ))) | ||
| 520 | |||
| 521 | Dr. Maria Rodriguez, lead researcher, recommends incorporating more olive oil, fish, and vegetables into daily meals. | ||
| 522 | |||
| 523 | (% class="box errormessage" style="margin:10px 0;" %) | ||
| 524 | ((( | ||
| 525 | 🔴 **The study proves that saturated fats cause heart disease** | ||
| 526 | |||
| 527 | (% style="font-size:0.9em; color:#666;" %) | ||
| 528 | ↑ REFUTED • 15% confidence | ||
| 529 | Claim not supported by study design; correlation ≠ causation | ||
| 530 | [[Click for counter-evidence →]] | ||
| 531 | (%%) | ||
| 532 | ))) | ||
| 533 | |||
| 534 | Participants also reported feeling more energetic and experiencing better sleep quality, though these were secondary measures. | ||
| 535 | ))) | ||
| 536 | |||
| 537 | **Legend:** | ||
| 538 | * 🟢 = Well-supported claim (confidence ≥75%) | ||
| 539 | * 🟡 = Uncertain claim (confidence 40-74%) | ||
| 540 | * 🔴 = Refuted/unsupported claim (confidence <40%) | ||
| 541 | * Plain text = Non-factual content (context, opinions, recommendations) | ||
| 542 | |||
| |
5.1 | 543 | ==== Tooltip on Hover/Click ==== |
| 544 | |||
| |
6.1 | 545 | (% class="box infomessage" %) |
| 546 | ((( | ||
| 547 | **FactHarbor Analysis** | ||
| |
5.1 | 548 | |
| |
6.1 | 549 | **Claim:** |
| 550 | "Researchers found that Mediterranean diet followers had a 25% lower risk of heart disease" | ||
| 551 | |||
| 552 | **Verdict:** WELL SUPPORTED | ||
| 553 | **Confidence:** 87% | ||
| 554 | |||
| 555 | **Evidence Summary:** | ||
| 556 | * Meta-analysis of 12 RCTs confirms 23-28% risk reduction | ||
| 557 | * Consistent findings across multiple populations | ||
| 558 | * Published in peer-reviewed journal (high credibility) | ||
| 559 | |||
| 560 | **Uncertainty Factors:** | ||
| 561 | * Exact percentage varies by study (20-30% range) | ||
| 562 | |||
| 563 | [[View Full Analysis →]] | ||
| 564 | ))) | ||
| 565 | |||
| |
5.1 | 566 | **Color-Coding System**: |
| 567 | * **Green**: Well-supported claims (confidence ≥75%, strong evidence) | ||
| 568 | * **Yellow/Orange**: Uncertain claims (confidence 40-74%, conflicting or limited evidence) | ||
| 569 | * **Red**: Refuted or unsupported claims (confidence <40%, contradicted by evidence) | ||
| 570 | * **Gray/Neutral**: Non-factual content (opinions, questions, procedural text) | ||
| 571 | |||
| |
6.1 | 572 | ==== Interactive Highlighting Example (Detailed View) ==== |
| |
5.1 | 573 | |
| |
6.1 | 574 | (% style="width:100%; border-collapse:collapse;" %) |
| 575 | |=**Article Text**|=**Status**|=**Analysis** | ||
| 576 | |(((A recent study published in the Journal of Nutrition has revealed new findings about the Mediterranean diet.)))|(% style="text-align:center;" %)Plain text|(% style="font-style:italic; color:#888;" %)Context - no highlighting | ||
| 577 | |(((//Researchers found that Mediterranean diet followers had a 25% lower risk of heart disease compared to control groups//)))|(% style="background-color:#D4EDDA; text-align:center; padding:8px;" %)🟢 **WELL SUPPORTED**|((( | ||
| 578 | **87% confidence** | ||
| |
5.1 | 579 | |
| |
6.1 | 580 | Meta-analysis of 12 RCTs confirms 23-28% risk reduction |
| |
5.1 | 581 | |
| |
6.1 | 582 | [[View Full Analysis]] |
| |
5.1 | 583 | ))) |
| |
6.1 | 584 | |(((The study, which followed 10,000 participants over five years, showed significant improvements in cardiovascular health markers.)))|(% style="text-align:center;" %)Plain text|(% style="font-style:italic; color:#888;" %)Methodology - no highlighting |
| 585 | |(((//Some experts believe this diet can completely prevent heart attacks//)))|(% style="background-color:#FFF3CD; text-align:center; padding:8px;" %)🟡 **UNCERTAIN**|((( | ||
| 586 | **45% confidence** | ||
| |
5.1 | 587 | |
| |
6.1 | 588 | Overstated - evidence shows risk reduction, not prevention |
| |
5.1 | 589 | |
| |
6.1 | 590 | [[View Details]] |
| |
5.1 | 591 | ))) |
| |
6.1 | 592 | |(((Dr. Rodriguez recommends incorporating more olive oil, fish, and vegetables into daily meals.)))|(% style="text-align:center;" %)Plain text|(% style="font-style:italic; color:#888;" %)Recommendation - no highlighting |
| 593 | |(((//The study proves that saturated fats cause heart disease//)))|(% style="background-color:#F8D7DA; text-align:center; padding:8px;" %)🔴 **REFUTED**|((( | ||
| 594 | **15% confidence** | ||
| |
5.1 | 595 | |
| |
6.1 | 596 | Claim not supported by study; correlation ≠ causation |
| |
5.1 | 597 | |
| |
6.1 | 598 | [[View Counter-Evidence]] |
| |
5.1 | 599 | ))) |
| 600 | |||
| |
6.1 | 601 | **Design Notes:** |
| 602 | * Highlighted claims use italics to distinguish from plain text | ||
| 603 | * Color backgrounds match XWiki message box colors (success/warning/error) | ||
| 604 | * Status column shows verdict prominently | ||
| 605 | * Analysis column provides quick summary with link to details | ||
| 606 | |||
| |
5.1 | 607 | **User Actions**: |
| 608 | * **Hover** over highlighted claim → Tooltip appears | ||
| 609 | * **Click** highlighted claim → Detailed analysis modal/panel | ||
| 610 | * **Toggle** button to turn highlighting on/off | ||
| 611 | * **Keyboard**: Tab through highlighted claims | ||
| 612 | |||
| 613 | **Interaction Design**: | ||
| 614 | * Hover/click on highlighted claim → Show tooltip with: | ||
| 615 | * Claim text | ||
| 616 | * Verdict (e.g., "WELL SUPPORTED") | ||
| 617 | * Confidence score (e.g., "85%") | ||
| 618 | * Brief evidence summary | ||
| 619 | * Link to detailed analysis | ||
| 620 | * Toggle highlighting on/off (user preference) | ||
| 621 | * Adjustable color intensity for accessibility | ||
| 622 | |||
| 623 | **Technical Requirements**: | ||
| 624 | * Real-time highlighting as page loads (non-blocking) | ||
| 625 | * Claim boundary detection (start/end of assertion) | ||
| 626 | * Handle nested or overlapping claims | ||
| 627 | * Preserve original article formatting | ||
| 628 | * Work with various content formats (HTML, plain text, PDFs) | ||
| 629 | |||
| 630 | **Performance Requirements**: | ||
| 631 | * Highlighting renders within 500ms of page load | ||
| 632 | * No perceptible delay in reading experience | ||
| 633 | * Efficient DOM manipulation (avoid reflows) | ||
| 634 | |||
| 635 | **Accessibility**: | ||
| 636 | * Color-blind friendly palette (use patterns/icons in addition to color) | ||
| 637 | * Screen reader compatible (ARIA labels for claim credibility) | ||
| 638 | * Keyboard navigation to highlighted claims | ||
| 639 | |||
| 640 | **Implementation Notes**: | ||
| 641 | * Claims extracted and analyzed by AKEL during initial processing | ||
| 642 | * Highlighting data stored as annotations with byte offsets | ||
| 643 | * Client-side rendering of highlights based on verdict data | ||
| 644 | * Mobile responsive (tap instead of hover) | ||
| 645 | |||
| |
3.1 | 646 | === 8.5 Workflow & Moderation === |
| 647 | |||
| |
2.1 | 648 | ==== FR9 — Publication Workflow ==== |
| 649 | |||
| 650 | **Fulfills**: UN-1 (Fast access to verified content), UN-16 (Clear review status) | ||
| 651 | |||
| |
1.1 | 652 | **Simple flow**: |
| 653 | 1. Claim submitted | ||
| 654 | 2. AKEL processes (automated) | ||
| |
2.1 | 655 | 3. If confidence > threshold: Publish (labeled as AI-generated) |
| |
1.1 | 656 | 4. If confidence < threshold: Flag for improvement |
| 657 | 5. If risk score > threshold: Flag for moderator | ||
| |
2.1 | 658 | |
| |
1.1 | 659 | **No multi-stage approval process** |
| |
2.1 | 660 | |
| 661 | ==== FR10 — Moderation ==== | ||
| 662 | |||
| |
1.1 | 663 | **Focus on abuse, not routine quality**: |
| 664 | * Automated abuse detection | ||
| 665 | * Moderators handle flags | ||
| 666 | * Quick response to harmful content | ||
| 667 | * Minimal involvement in routine content | ||
| |
2.1 | 668 | |
| 669 | ==== FR11 — Audit Trail ==== | ||
| 670 | |||
| 671 | **Fulfills**: UN-14 (API access to histories), UN-15 (Evolution tracking) | ||
| 672 | |||
| |
1.1 | 673 | * All edits logged |
| 674 | * Version history public | ||
| 675 | * Moderation decisions documented | ||
| 676 | * System improvements tracked | ||
| |
2.1 | 677 | |
| 678 | == 9. Non-Functional Requirements == | ||
| 679 | |||
| 680 | === 9.1 NFR1 — Performance === | ||
| 681 | |||
| 682 | **Fulfills**: UN-4 (Fast fact-checking), UN-11 (Responsive filtering) | ||
| 683 | |||
| |
1.1 | 684 | * Claim processing: < 30 seconds |
| 685 | * Search response: < 2 seconds | ||
| 686 | * Page load: < 3 seconds | ||
| 687 | * 99% uptime | ||
| |
2.1 | 688 | |
| 689 | === 9.2 NFR2 — Scalability === | ||
| 690 | |||
| 691 | **Fulfills**: UN-14 (API access at scale) | ||
| 692 | |||
| |
1.1 | 693 | * Handle 10,000 claims initially |
| 694 | * Scale to 1M+ claims | ||
| 695 | * Support 100K+ concurrent users | ||
| 696 | * Automated processing scales linearly | ||
| |
2.1 | 697 | |
| 698 | === 9.3 NFR3 — Transparency === | ||
| 699 | |||
| 700 | **Fulfills**: UN-7 (Evidence transparency), UN-9 (Methodology transparency), UN-13 (Citable verdicts), UN-15 (Evolution visibility) | ||
| 701 | |||
| |
1.1 | 702 | * All algorithms open source |
| 703 | * All data exportable | ||
| 704 | * All decisions documented | ||
| 705 | * Quality metrics public | ||
| |
2.1 | 706 | |
| 707 | === 9.4 NFR4 — Security & Privacy === | ||
| 708 | |||
| |
1.1 | 709 | * Follow [[Privacy Policy>>FactHarbor.Organisation.How-We-Work-Together.Privacy-Policy]] |
| 710 | * Secure authentication | ||
| 711 | * Data encryption | ||
| 712 | * Regular security audits | ||
| |
2.1 | 713 | |
| 714 | === 9.5 NFR5 — Maintainability === | ||
| 715 | |||
| |
1.1 | 716 | * Modular architecture |
| 717 | * Automated testing | ||
| 718 | * Continuous integration | ||
| 719 | * Comprehensive documentation | ||
| |
2.1 | 720 | |
| 721 | == 10. MVP Scope == | ||
| 722 | |||
| |
1.1 | 723 | **Phase 1 (Months 1-3): Read-Only MVP** |
| |
2.1 | 724 | |
| |
1.1 | 725 | Build: |
| 726 | * Automated claim analysis | ||
| 727 | * Confidence scoring | ||
| 728 | * Source evaluation | ||
| 729 | * Browse/search interface | ||
| 730 | * User flagging system | ||
| |
2.1 | 731 | |
| |
1.1 | 732 | **Goal**: Prove AI quality before adding user editing |
| |
2.1 | 733 | |
| 734 | **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 | ||
| 735 | |||
| |
1.1 | 736 | **Phase 2 (Months 4-6): User Contributions** |
| |
2.1 | 737 | |
| |
1.1 | 738 | Add only if needed: |
| 739 | * Simple editing (Wikipedia-style) | ||
| 740 | * Reputation system | ||
| 741 | * Basic moderation | ||
| |
5.1 | 742 | * In-article claim highlighting (FR13) |
| |
2.1 | 743 | |
| |
5.1 | 744 | **Additional User Needs fulfilled**: UN-13, UN-17 |
| |
2.1 | 745 | |
| |
1.1 | 746 | **Phase 3 (Months 7-12): Refinement** |
| |
2.1 | 747 | |
| |
1.1 | 748 | * Continuous quality improvement |
| 749 | * Feature additions based on real usage | ||
| 750 | * Scale infrastructure | ||
| |
2.1 | 751 | |
| 752 | **Additional User Needs fulfilled**: UN-14 (API access), UN-15 (Full evolution tracking) | ||
| 753 | |||
| |
1.1 | 754 | **Deferred**: |
| 755 | * Federation (until multiple successful instances exist) | ||
| 756 | * Complex contribution workflows (focus on automation) | ||
| 757 | * Extensive role hierarchy (keep simple) | ||
| |
2.1 | 758 | |
| 759 | == 11. Success Metrics == | ||
| 760 | |||
| |
1.1 | 761 | **System Quality** (track weekly): |
| 762 | * Error rate by category (target: -10%/month) | ||
| 763 | * Average confidence score (target: increase) | ||
| 764 | * Source quality distribution (target: more high-quality) | ||
| 765 | * Contradiction detection rate (target: increase) | ||
| |
2.1 | 766 | |
| |
1.1 | 767 | **Efficiency** (track monthly): |
| 768 | * Claims processed per hour (target: increase) | ||
| 769 | * Human hours per claim (target: decrease) | ||
| 770 | * Automation coverage (target: >90%) | ||
| 771 | * Re-work rate (target: <5%) | ||
| |
2.1 | 772 | |
| |
1.1 | 773 | **User Satisfaction** (track quarterly): |
| 774 | * User flag rate (issues found) | ||
| 775 | * Correction acceptance rate (flags valid) | ||
| 776 | * Return user rate | ||
| 777 | * Trust indicators (surveys) | ||
| |
2.1 | 778 | |
| 779 | **User Needs Metrics** (track quarterly): | ||
| 780 | * UN-1: % users who understand trust scores | ||
| 781 | * UN-4: Time to verify social media claim (target: <30s) | ||
| 782 | * UN-7: % users who access evidence details | ||
| 783 | * UN-8: % users who view multiple scenarios | ||
| 784 | * UN-15: % users who check evolution timeline | ||
| |
5.1 | 785 | * UN-17: % users who enable in-article highlighting; avg. time spent on highlighted vs. non-highlighted articles |
| |
2.1 | 786 | |
| 787 | == 12. Requirements Traceability == | ||
| 788 | |||
| 789 | For full traceability matrix showing which requirements fulfill which user needs, see: | ||
| 790 | |||
| |
4.1 | 791 | * [[User Needs>>FactHarbor.Specification.Requirements.User Needs.WebHome]] - Section 8 includes comprehensive mapping tables |
| |
2.1 | 792 | |
| 793 | == 13. Related Pages == | ||
| 794 | |||
| |
4.1 | 795 | * **[[User Needs>>FactHarbor.Specification.Requirements.User Needs.WebHome]]** - What users need (drives these requirements) |
| |
2.1 | 796 | * [[Architecture>>FactHarbor.Specification.Architecture.WebHome]] - How requirements are implemented |
| 797 | * [[Data Model>>FactHarbor.Specification.Data Model.WebHome]] - Data structures supporting requirements | ||
| 798 | * [[Workflows>>FactHarbor.Specification.Workflows.WebHome]] - User interaction workflows | ||
| 799 | * [[AKEL>>FactHarbor.Specification.AI Knowledge Extraction Layer (AKEL).WebHome]] - AI system fulfilling automation requirements | ||
| |
1.1 | 800 | * [[Global Rules>>FactHarbor.Organisation.How-We-Work-Together.GlobalRules.WebHome]] |
| 801 | * [[Privacy Policy>>FactHarbor.Organisation.How-We-Work-Together.Privacy-Policy]] |