Changes for page Requirements

Last modified by Robert Schaub on 2025/12/24 21:46

From 4.1 to 3.1

From version 3.1

edited by Robert Schaub
on 2025/12/19 09:57

Change comment: There is no comment for this version

To version 1.1

edited by Robert Schaub
on 2025/12/18 12:03

Change comment: Imported from XAR

Raw
Rendered

Summary

Page properties (1 modified, 0 added, 0 removed)

Details

Page properties

Content

@@ -1,36 +1,10 @@
  = Requirements =
--
--**This page defines Roles, Content States, Rules, and System Requirements for FactHarbor.**
--
++This page defines **Roles**, **Content States**, **Rules**, and **System Principles** for FactHarbor.
  **Core Philosophy:** Invest in system improvement, not manual data correction. When AI makes errors, improve the algorithm and re-process automatically.
--
--== Navigation ==
--
--* **[[User Needs>>FactHarbor.Specification.Requirements.User-Needs]]** - What users need from FactHarbor (drives these requirements)
--* **This page** - How we fulfill those needs through system design
--
--(% class="box infomessage" %)
--(((
--**How to read this page:**
--
--1. **User Needs drive Requirements**: See [[User Needs>>FactHarbor.Specification.Requirements.User-Needs]] for what users need
--2. **Requirements define implementation**: This page shows how we fulfill those needs
--3. **Functional Requirements (FR)**: Specific features and capabilities
--4. **Non-Functional Requirements (NFR)**: Quality attributes (performance, security, etc.)
--
--Each requirement references which User Needs it fulfills.
--)))
--
  == 1. Roles ==
--
--**Fulfills**: UN-12 (Submit claims), UN-13 (Cite verdicts), UN-14 (API access)
--
  FactHarbor uses three simple roles plus a reputation system.
--
  === 1.1 Reader ===
--
  **Who**: Anyone (no login required)
--
  **Can**:
  * Browse and search claims
  * View scenarios, evidence, verdicts, and confidence scores
@@ -37,17 +37,11 @@
  * Flag issues or errors
  * Use filters, search, and visualization tools
  * Submit claims automatically (new claims added if not duplicates)
--
  **Cannot**:
  * Modify content
  * Access edit history details
--
--**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)
--
  === 1.2 Contributor ===
--
  **Who**: Registered users (earns reputation through contributions)
--
  **Can**:
  * Everything a Reader can do
  * Edit claims, evidence, and scenarios
@@ -55,7 +55,6 @@
  * Suggest improvements to AI-generated content
  * Participate in discussions
  * Earn reputation points for quality contributions
--
  **Reputation System**:
  * New contributors: Limited edit privileges
  * Established contributors (established reputation): Full edit access
@@ -62,17 +62,11 @@
  * Trusted contributors (substantial reputation): Can approve certain changes
  * Reputation earned through: Accepted edits, helpful flags, quality contributions
  * Reputation lost through: Reverted edits, invalid flags, abuse
--
  **Cannot**:
  * Delete or hide content (only moderators)
  * Override moderation decisions
--
--**User Needs served**: UN-13 (Cite and contribute)
--
  === 1.3 Moderator ===
--
  **Who**: Trusted community members with proven track record, appointed by governance board
--
  **Can**:
  * Review flagged content
  * Hide harmful or abusive content
@@ -80,26 +80,19 @@
  * Issue warnings or temporary bans
  * Make final decisions on content disputes
  * Access full audit logs
--
  **Cannot**:
  * Change governance rules
  * Permanently ban users without board approval
  * Override technical quality gates
--
  **Note**: Small team (3-5 initially), supported by automated moderation tools.
--
  === 1.4 Domain Trusted Contributors (Optional, Task-Specific) ===
--
  **Who**: Subject matter specialists invited for specific high-stakes disputes
--
  **Not a permanent role**: Contacted externally when needed for contested claims in their domain
--
  **When used**:
  * Medical claims with life/safety implications
  * Legal interpretations with significant impact
  * Scientific claims with high controversy
  * Technical claims requiring specialized knowledge
--
  **Process**:
  * Moderator identifies need for expert input
  * Contact expert externally (don't require them to be users)
@@ -106,24 +106,14 @@
  * Trusted Contributor provides written opinion with sources
  * Opinion added to claim record
  * Trusted Contributor acknowledged in claim
--
--**User Needs served**: UN-16 (Expert validation status)
--
  == 2. Content States ==
--
--**Fulfills**: UN-1 (Trust indicators), UN-16 (Review status transparency)
--
  FactHarbor uses two content states. Focus is on transparency and confidence scoring, not gatekeeping.
--
  === 2.1 Published ===
--
  **Status**: Visible to all users
--
  **Includes**:
  * AI-generated analyses (default state)
  * User-contributed content
  * Edited/improved content
--
  **Quality Indicators** (displayed with content):
  * **Confidence Score**: 0-100% (AI's confidence in analysis)
  * **Source Quality Score**: 0-100% (based on source track record)
@@ -131,20 +131,13 @@
  * **Completeness Score**: % of expected fields filled
  * **Last Updated**: Date of most recent change
  * **Edit Count**: Number of revisions
--* **Review Status**: AI-generated / Human-reviewed / Expert-validated
--
  **Automatic Warnings**:
  * Confidence < 60%: "Low confidence - use caution"
  * Source quality < 40%: "Sources may be unreliable"
  * High controversy: "Disputed - multiple interpretations exist"
  * Medical/Legal/Safety domain: "Seek professional advice"
--
--**User Needs served**: UN-1 (Trust score), UN-9 (Methodology transparency), UN-15 (Evolution timeline), UN-16 (Review status)
--
  === 2.2 Hidden ===
--
  **Status**: Not visible to regular users (only to moderators)
--
  **Reasons**:
  * Spam or advertising
  * Personal attacks or harassment
@@ -152,29 +152,21 @@
  * Privacy violations
  * Deliberate misinformation (verified)
  * Abuse or harmful content
--
  **Process**:
  * Automated detection flags for moderator review
  * Moderator confirms and hides
  * Original author notified with reason
  * Can appeal to board if disputes moderator decision
--
  **Note**: Content is hidden, not deleted (for audit trail)
--
  == 3. Contribution Rules ==
--
  === 3.1 All Contributors Must ===
--
  * Provide sources for factual claims
  * Use clear, neutral language in FactHarbor's own summaries
  * Respect others and maintain civil discourse
  * Accept community feedback constructively
  * Focus on improving quality, not protecting ego
--
  === 3.2 AKEL (AI System) ===
--
  **AKEL is the primary system**. Human contributions supplement and train AKEL.
--
  **AKEL Must**:
  * Mark all outputs as AI-generated
  * Display confidence scores prominently
@@ -182,74 +182,49 @@
  * Flag uncertainty clearly
  * Identify contradictions in evidence
  * Learn from human corrections
--
  **When AKEL Makes Errors**:
 . Capture the error pattern (what, why, how common)
 . Improve the system (better prompt, model, validation)
 . Re-process affected claims automatically
 . Measure improvement (did quality increase?)
--
  **Human Role**: Train AKEL through corrections, not replace AKEL
--
  === 3.3 Contributors Should ===
--
  * Improve clarity and structure
  * Add missing sources
  * Flag errors for system improvement
  * Suggest better ways to present information
  * Participate in quality discussions
--
  === 3.4 Moderators Must ===
--
  * Be impartial
  * Document moderation decisions
  * Respond to appeals promptly
  * Use automated tools to scale efforts
  * Focus on abuse/harm, not routine quality control
--
  == 4. Quality Standards ==
--
--**Fulfills**: UN-5 (Source reliability), UN-6 (Publisher track records), UN-7 (Evidence transparency), UN-9 (Methodology transparency)
--
  === 4.1 Source Requirements ===
--
  **Track Record Over Credentials**:
  * Sources evaluated by historical accuracy
  * Correction policy matters
  * Independence from conflicts of interest
  * Methodology transparency
--
  **Source Quality Database**:
  * Automated tracking of source accuracy
  * Correction frequency
  * Reliability score (updated continuously)
  * Users can see source track record
--
  **No automatic trust** for government, academia, or media - all evaluated by track record.
--
--**User Needs served**: UN-5 (Source provenance), UN-6 (Publisher reliability)
--
  === 4.2 Claim Requirements ===
--
  * Clear subject and assertion
  * Verifiable with available information
  * Sourced (or explicitly marked as needing sources)
  * Neutral language in FactHarbor summaries
  * Appropriate context provided
--
--**User Needs served**: UN-2 (Claim extraction and verification)
--
  === 4.3 Evidence Requirements ===
--
  * Publicly accessible (or explain why not)
  * Properly cited with attribution
  * Relevant to claim being evaluated
  * Original source preferred over secondary
--
--**User Needs served**: UN-7 (Evidence transparency)
--
  === 4.4 Confidence Scoring ===
--
  **Automated confidence calculation based on**:
  * Source quality scores
  * Evidence consistency
@@ -256,23 +256,14 @@
  * Contradiction detection
  * Completeness of analysis
  * Historical accuracy of similar claims
--
  **Thresholds**:
  * < 40%: Too low to publish (needs improvement)
  * 40-60%: Published with "Low confidence" warning
  * 60-80%: Published as standard
  * 80-100%: Published as "High confidence"
--
--**User Needs served**: UN-1 (Trust assessment), UN-9 (Methodology transparency)
--
  == 5. Automated Risk Scoring ==
--
--**Fulfills**: UN-10 (Manipulation detection), UN-16 (Appropriate review level)
--
  **Replace manual risk tiers with continuous automated scoring**.
--
  === 5.1 Risk Score Calculation ===
--
  **Factors** (weighted algorithm):
  * **Domain sensitivity**: Medical, legal, safety auto-flagged higher
  * **Potential impact**: Views, citations, spread
@@ -279,26 +279,16 @@
  * **Controversy level**: Flags, disputes, edit wars
  * **Uncertainty**: Low confidence, contradictory evidence
  * **Source reliability**: Track record of sources used
--
  **Score**: 0-100 (higher = more risk)
--
  === 5.2 Automated Actions ===
--
  * **Score > 80**: Flag for moderator review before publication
  * **Score 60-80**: Publish with prominent warnings
  * **Score 40-60**: Publish with standard warnings
  * **Score < 40**: Publish normally
--
  **Continuous monitoring**: Risk score recalculated as new information emerges
--
--**User Needs served**: UN-10 (Detect manipulation tactics), UN-16 (Review status)
--
  == 6. System Improvement Process ==
--
  **Core principle**: Fix the system, not just the data.
--
  === 6.1 Error Capture ===
--
  **When users flag errors or make corrections**:
 . What was wrong? (categorize)
 . What should it have been?
@@ -305,9 +305,7 @@
 . Why did the system fail? (root cause)
 . How common is this pattern?
 . Store in ErrorPattern table (improvement queue)
--
  === 6.2 Weekly Improvement Cycle ===
--
 . **Review**: Analyze top error patterns
 . **Develop**: Create fix (prompt, model, validation)
 . **Test**: Validate fix on sample claims
@@ -314,9 +314,7 @@
 . **Deploy**: Roll out if quality improves
 . **Re-process**: Automatically update affected claims
 . **Monitor**: Track quality metrics
--
  === 6.3 Quality Metrics Dashboard ===
--
  **Track continuously**:
  * Error rate by category
  * Source quality distribution
@@ -325,23 +325,16 @@
  * Correction acceptance rate
  * Re-work rate
  * Claims processed per hour
--
  **Goal**: 10% monthly improvement in error rate
--
  == 7. Automated Quality Monitoring ==
--
  **Replace manual audit sampling with automated monitoring**.
--
  === 7.1 Continuous Metrics ===
--
  * **Source quality**: Track record database
  * **Consistency**: Contradiction detection
  * **Clarity**: Readability scores
  * **Completeness**: Field validation
  * **Accuracy**: User corrections tracked
--
  === 7.2 Anomaly Detection ===
--
  **Automated alerts for**:
  * Sudden quality drops
  * Unusual patterns
@@ -348,218 +348,103 @@
  * Contradiction clusters
  * Source reliability changes
  * User behavior anomalies
--
  === 7.3 Targeted Review ===
--
  * Review only flagged items
  * Random sampling for calibration (not quotas)
  * Learn from corrections to improve automation
--
--== 8. Functional Requirements ==
--
--This section defines specific features that fulfill user needs.
--
--=== 8.1 Claim Intake & Normalization ===
--
--==== FR1 — Claim Intake ====
--
--**Fulfills**: UN-2 (Claim extraction), UN-4 (Quick fact-checking), UN-12 (Submit claims)
--
++== 8. Claim Intake & Normalization ==
++=== 8.1 FR1 – Claim Intake ===
  * Users submit claims via simple form or API
  * Claims can be text, URL, or image
  * Duplicate detection (semantic similarity)
  * Auto-categorization by domain
--
--==== FR2 — Claim Normalization ====
--
--**Fulfills**: UN-2 (Claim verification)
--
++=== 8.2 FR2 – Claim Normalization ===
  * Standardize to clear assertion format
  * Extract key entities (who, what, when, where)
  * Identify claim type (factual, predictive, evaluative)
  * Link to existing similar claims
--
--==== FR3 — Claim Classification ====
--
--**Fulfills**: UN-11 (Filtered research)
--
++=== 8.3 FR3 – Claim Classification ===
  * Domain: Politics, Science, Health, etc.
  * Type: Historical fact, current stat, prediction, etc.
  * Risk score: Automated calculation
  * Complexity: Simple, moderate, complex
--
--=== 8.2 Scenario System ===
--
--==== FR4 — Scenario Generation ====
--
--**Fulfills**: UN-2 (Context-dependent verification), UN-3 (Article summary with FactHarbor analysis summary), UN-8 (Understanding disagreement)
--
++== 9. Scenario System ==
++=== 9.1 FR4 – Scenario Generation ===
  **Automated scenario creation**:
--* AKEL analyzes claim and generates likely scenarios (use-cases and contexts)
--* Each scenario includes: assumptions, definitions, boundaries, evidence context
++* AKEL analyzes claim and generates likely scenarios
++* Each scenario includes: assumptions, evidence, conclusion
  * Users can flag incorrect scenarios
  * System learns from corrections
--
--**Key Concept**: Scenarios represent different interpretations or contexts (e.g., "Clinical trials with healthy adults" vs. "Real-world data with diverse populations")
--
--==== FR5 — Evidence Linking ====
--
--**Fulfills**: UN-5 (Source tracing), UN-7 (Evidence transparency)
--
++=== 9.2 FR5 – Evidence Linking ===
  * Automated evidence discovery from sources
  * Relevance scoring
  * Contradiction detection
  * Source quality assessment
--
--==== FR6 — Scenario Comparison ====
--
--**Fulfills**: UN-3 (Article summary with FactHarbor analysis summary), UN-8 (Understanding disagreement)
--
++=== 9.3 FR6 – Scenario Comparison ===
  * Side-by-side comparison interface
--* Highlight key differences between scenarios
--* Show evidence supporting each scenario
--* Display confidence scores per scenario
--
--=== 8.3 Verdicts & Analysis ===
--
--==== FR7 — Automated Verdicts ====
--
--**Fulfills**: UN-1 (Trust score), UN-2 (Verification verdicts), UN-3 (Article summary with FactHarbor analysis summary), UN-13 (Cite verdicts)
--
--* AKEL generates verdict based on evidence within each scenario
--* **Likelihood range** displayed (e.g., "0.70-0.85 (likely true)") - NOT binary true/false
--* **Uncertainty factors** explicitly listed (e.g., "Small sample sizes", "Long-term effects unknown")
++* Highlight key differences
++* Show evidence supporting each
++* Display confidence scores
++== 10. Verdicts & Analysis ==
++=== 10.1 FR7 – Automated Verdicts ===
++* AKEL generates verdict based on evidence
  * Confidence score displayed prominently
--* Source quality indicators shown
++* Source quality indicators
  * Contradictions noted
  * Uncertainty acknowledged
--
--**Key Innovation**: Detailed probabilistic verdicts with explicit uncertainty, not binary judgments
--
--==== FR8 — Time Evolution ====
--
--**Fulfills**: UN-15 (Verdict evolution timeline)
--
--* Claims and verdicts update as new evidence emerges
--* Version history maintained for all verdicts
++=== 10.2 FR8 – Time Evolution ===
++* Claims update as new evidence emerges
++* Version history maintained
  * Changes highlighted
  * Confidence score trends visible
--* Users can see "as of date X, what did we know?"
--
--=== 8.4 User Interface & Presentation ===
--
--==== FR12 — Two-Panel Summary View (Article Summary with FactHarbor Analysis Summary) ====
--
--**Fulfills**: UN-3 (Article Summary with FactHarbor Analysis Summary)
--
--**Purpose**: Provide side-by-side comparison of what a document claims vs. FactHarbor's complete analysis of its credibility
--
--**Left Panel: Article Summary**:
--* Document title, source, and claimed credibility
--* "The Big Picture" - main thesis or position change
--* "Key Findings" - structured summary of document's main claims
--* "Reasoning" - document's explanation for positions
--* "Conclusion" - document's bottom line
--
--**Right Panel: FactHarbor Analysis Summary**:
--* FactHarbor's independent source credibility assessment
--* Claim-by-claim verdicts with confidence scores
--* Methodology assessment (strengths, limitations)
--* Overall verdict on document quality
--* Analysis ID for reference
--
--**Design Principles**:
--* No scrolling required - both panels visible simultaneously
--* Visual distinction between "what they say" and "FactHarbor's analysis"
--* Color coding for verdicts (supported, uncertain, refuted)
--* Confidence percentages clearly visible
--* Mobile responsive (panels stack vertically on small screens)
--
--**Implementation Notes**:
--* Generated automatically by AKEL for every analyzed document
--* Updates when verdict evolves (maintains version history)
--* Exportable as standalone summary report
--* Shareable via permanent URL
--
--=== 8.5 Workflow & Moderation ===
--
--==== FR9 — Publication Workflow ====
--
--**Fulfills**: UN-1 (Fast access to verified content), UN-16 (Clear review status)
--
++== 11. Workflow & Moderation ==
++=== 11.1 FR9 – Publication Workflow ===
  **Simple flow**:
 . Claim submitted
 . AKEL processes (automated)
--3. If confidence > threshold: Publish (labeled as AI-generated)
++3. If confidence > threshold: Publish
 . If confidence < threshold: Flag for improvement
 . If risk score > threshold: Flag for moderator
--
  **No multi-stage approval process**
--
--==== FR10 — Moderation ====
--
++=== 11.2 FR10 – Moderation ===
  **Focus on abuse, not routine quality**:
  * Automated abuse detection
  * Moderators handle flags
  * Quick response to harmful content
  * Minimal involvement in routine content
--
--==== FR11 — Audit Trail ====
--
--**Fulfills**: UN-14 (API access to histories), UN-15 (Evolution tracking)
--
++=== 11.3 FR11 – Audit Trail ===
  * All edits logged
  * Version history public
  * Moderation decisions documented
  * System improvements tracked
--
--== 9. Non-Functional Requirements ==
--
--=== 9.1 NFR1 — Performance ===
--
--**Fulfills**: UN-4 (Fast fact-checking), UN-11 (Responsive filtering)
--
++== 12. Technical Requirements ==
++=== 12.1 NFR1 – Performance ===
  * Claim processing: < 30 seconds
  * Search response: < 2 seconds
  * Page load: < 3 seconds
  * 99% uptime
--
--=== 9.2 NFR2 — Scalability ===
--
--**Fulfills**: UN-14 (API access at scale)
--
++=== 12.2 NFR2 – Scalability ===
  * Handle 10,000 claims initially
  * Scale to 1M+ claims
  * Support 100K+ concurrent users
  * Automated processing scales linearly
--
--=== 9.3 NFR3 — Transparency ===
--
--**Fulfills**: UN-7 (Evidence transparency), UN-9 (Methodology transparency), UN-13 (Citable verdicts), UN-15 (Evolution visibility)
--
++=== 12.3 NFR3 – Transparency ===
  * All algorithms open source
  * All data exportable
  * All decisions documented
  * Quality metrics public
--
--=== 9.4 NFR4 — Security & Privacy ===
--
++=== 12.4 NFR4 – Security & Privacy ===
  * Follow [[Privacy Policy>>FactHarbor.Organisation.How-We-Work-Together.Privacy-Policy]]
  * Secure authentication
  * Data encryption
  * Regular security audits
--
--=== 9.5 NFR5 — Maintainability ===
--
++=== 12.5 NFR5 – Maintainability ===
  * Modular architecture
  * Automated testing
  * Continuous integration
  * Comprehensive documentation
--
--== 10. MVP Scope ==
--
++== 13. MVP Scope ==
  **Phase 1 (Months 1-3): Read-Only MVP**
--
  Build:
  * Automated claim analysis
  * Confidence scoring
@@ -566,72 +566,39 @@
  * Source evaluation
  * Browse/search interface
  * User flagging system
--
  **Goal**: Prove AI quality before adding user editing
--
--**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
--
  **Phase 2 (Months 4-6): User Contributions**
--
  Add only if needed:
  * Simple editing (Wikipedia-style)
  * Reputation system
  * Basic moderation
--
--**Additional User Needs fulfilled**: UN-13
--
  **Phase 3 (Months 7-12): Refinement**
--
  * Continuous quality improvement
  * Feature additions based on real usage
  * Scale infrastructure
--
--**Additional User Needs fulfilled**: UN-14 (API access), UN-15 (Full evolution tracking)
--
  **Deferred**:
  * Federation (until multiple successful instances exist)
  * Complex contribution workflows (focus on automation)
  * Extensive role hierarchy (keep simple)
--
--== 11. Success Metrics ==
--
++== 14. Success Metrics ==
  **System Quality** (track weekly):
  * Error rate by category (target: -10%/month)
  * Average confidence score (target: increase)
  * Source quality distribution (target: more high-quality)
  * Contradiction detection rate (target: increase)
--
  **Efficiency** (track monthly):
  * Claims processed per hour (target: increase)
  * Human hours per claim (target: decrease)
  * Automation coverage (target: >90%)
  * Re-work rate (target: <5%)
--
  **User Satisfaction** (track quarterly):
  * User flag rate (issues found)
  * Correction acceptance rate (flags valid)
  * Return user rate
  * Trust indicators (surveys)
--
--**User Needs Metrics** (track quarterly):
--* UN-1: % users who understand trust scores
--* UN-4: Time to verify social media claim (target: <30s)
--* UN-7: % users who access evidence details
--* UN-8: % users who view multiple scenarios
--* UN-15: % users who check evolution timeline
--
--== 12. Requirements Traceability ==
--
--For full traceability matrix showing which requirements fulfill which user needs, see:
--
--* [[User Needs>>FactHarbor.Specification.Requirements.User-Needs]] - Section 8 includes comprehensive mapping tables
--
--== 13. Related Pages ==
--
--* **[[User Needs>>FactHarbor.Specification.Requirements.User-Needs]]** - What users need (drives these requirements)
--* [[Architecture>>FactHarbor.Specification.Architecture.WebHome]] - How requirements are implemented
--* [[Data Model>>FactHarbor.Specification.Data Model.WebHome]] - Data structures supporting requirements
--* [[Workflows>>FactHarbor.Specification.Workflows.WebHome]] - User interaction workflows
--* [[AKEL>>FactHarbor.Specification.AI Knowledge Extraction Layer (AKEL).WebHome]] - AI system fulfilling automation requirements
++== 15. Related Pages ==
++* [[Architecture>>FactHarbor.Specification.Architecture.WebHome]]
++* [[Data Model>>FactHarbor.Specification.Data Model.WebHome]]
++* [[Workflows>>FactHarbor.Specification.Workflows.WebHome]]
  * [[Global Rules>>FactHarbor.Organisation.How-We-Work-Together.GlobalRules.WebHome]]
  * [[Privacy Policy>>FactHarbor.Organisation.How-We-Work-Together.Privacy-Policy]]

Changes for page Requirements

Summary

Details

Applications

Navigation

Need help?