Skip to Content

Changes for page Requirements

Last modified by Robert Schaub on 2025/12/24 21:46
From version 2.1
edited by Robert Schaub
on 2025/12/19 09:13
Change comment: There is no comment for this version
To version 5.1
edited by Robert Schaub
on 2025/12/19 10:23
Change comment: There is no comment for this version

Summary

Details

Page properties
Content
... ... @@ -6,7 +6,7 @@
6 6  
7 7  == Navigation ==
8 8  
9 -* **[[User Needs>>FactHarbor.Specification.Requirements.User-Needs]]** - What users need from FactHarbor (drives these requirements)
9 +* **[[User Needs>>FactHarbor.Specification.Requirements.User Needs.WebHome]]** - What users need from FactHarbor (drives these requirements)
10 10  * **This page** - How we fulfill those needs through system design
11 11  
12 12  (% class="box infomessage" %)
... ... @@ -13,7 +13,7 @@
13 13  (((
14 14  **How to read this page:**
15 15  
16 -1. **User Needs drive Requirements**: See [[User Needs>>FactHarbor.Specification.Requirements.User-Needs]] for what users need
16 +1. **User Needs drive Requirements**: See [[User Needs>>FactHarbor.Specification.Requirements.User Needs.WebHome]] for what users need
17 17  2. **Requirements define implementation**: This page shows how we fulfill those needs
18 18  3. **Functional Requirements (FR)**: Specific features and capabilities
19 19  4. **Non-Functional Requirements (NFR)**: Quality attributes (performance, security, etc.)
... ... @@ -42,7 +42,7 @@
42 42  * Modify content
43 43  * Access edit history details
44 44  
45 -**User Needs served**: UN-1 (Trust assessment), UN-2 (Claim verification), UN-3 (Summary + verdict), UN-4 (Social media fact-checking), UN-5 (Source tracing), UN-7 (Evidence transparency), UN-8 (Understanding disagreement), UN-12 (Submit claims)
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 46  
47 47  === 1.2 Contributor ===
48 48  
... ... @@ -392,7 +392,7 @@
392 392  
393 393  ==== FR4 — Scenario Generation ====
394 394  
395 -**Fulfills**: UN-2 (Context-dependent verification), UN-3 (Summary with scenarios), UN-8 (Understanding disagreement)
395 +**Fulfills**: UN-2 (Context-dependent verification), UN-3 (Article summary with FactHarbor analysis summary), UN-8 (Understanding disagreement)
396 396  
397 397  **Automated scenario creation**:
398 398  * AKEL analyzes claim and generates likely scenarios (use-cases and contexts)
... ... @@ -413,7 +413,7 @@
413 413  
414 414  ==== FR6 — Scenario Comparison ====
415 415  
416 -**Fulfills**: UN-3 (Summary with verdicts), UN-8 (Understanding disagreement)
416 +**Fulfills**: UN-3 (Article summary with FactHarbor analysis summary), UN-8 (Understanding disagreement)
417 417  
418 418  * Side-by-side comparison interface
419 419  * Highlight key differences between scenarios
... ... @@ -424,7 +424,7 @@
424 424  
425 425  ==== FR7 — Automated Verdicts ====
426 426  
427 -**Fulfills**: UN-1 (Trust score), UN-2 (Verification verdicts), UN-3 (Verdict summaries), UN-13 (Cite verdicts)
427 +**Fulfills**: UN-1 (Trust score), UN-2 (Verification verdicts), UN-3 (Article summary with FactHarbor analysis summary), UN-13 (Cite verdicts)
428 428  
429 429  * AKEL generates verdict based on evidence within each scenario
430 430  * **Likelihood range** displayed (e.g., "0.70-0.85 (likely true)") - NOT binary true/false
... ... @@ -446,8 +446,190 @@
446 446  * Confidence score trends visible
447 447  * Users can see "as of date X, what did we know?"
448 448  
449 -=== 8.4 Workflow & Moderation ===
449 +=== 8.4 User Interface & Presentation ===
450 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 +
451 451  ==== FR9 — Publication Workflow ====
452 452  
453 453  **Fulfills**: UN-1 (Fast access to verified content), UN-16 (Clear review status)
... ... @@ -542,8 +542,9 @@
542 542  * Simple editing (Wikipedia-style)
543 543  * Reputation system
544 544  * Basic moderation
727 +* In-article claim highlighting (FR13)
545 545  
546 -**Additional User Needs fulfilled**: UN-13
729 +**Additional User Needs fulfilled**: UN-13, UN-17
547 547  
548 548  **Phase 3 (Months 7-12): Refinement**
549 549  
... ... @@ -584,16 +584,17 @@
584 584  * UN-7: % users who access evidence details
585 585  * UN-8: % users who view multiple scenarios
586 586  * 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
587 587  
588 588  == 12. Requirements Traceability ==
589 589  
590 590  For full traceability matrix showing which requirements fulfill which user needs, see:
591 591  
592 -* [[User Needs>>FactHarbor.Specification.Requirements.User-Needs]] - Section 8 includes comprehensive mapping tables
776 +* [[User Needs>>FactHarbor.Specification.Requirements.User Needs.WebHome]] - Section 8 includes comprehensive mapping tables
593 593  
594 594  == 13. Related Pages ==
595 595  
596 -* **[[User Needs>>FactHarbor.Specification.Requirements.User-Needs]]** - What users need (drives these requirements)
780 +* **[[User Needs>>FactHarbor.Specification.Requirements.User Needs.WebHome]]** - What users need (drives these requirements)
597 597  * [[Architecture>>FactHarbor.Specification.Architecture.WebHome]] - How requirements are implemented
598 598  * [[Data Model>>FactHarbor.Specification.Data Model.WebHome]] - Data structures supporting requirements
599 599  * [[Workflows>>FactHarbor.Specification.Workflows.WebHome]] - User interaction workflows