Changes for page Requirements

Summary

• Page properties (2 modified, 0 added, 0 removed)

Details

Page properties

Parent

...	...	@@ -1,1 +1,1 @@
1		-FactHarbor.Specification.WebHome
	1	+Archive.FactHarbor V0\.9\.50 Plus (Prev Rel).Specification.WebHome

Content

...	...	@@ -1,22 +1,57 @@
1	1	= Requirements =
2		-This page defines **Roles**, **Content States**, **Rules**, and **System Principles** for FactHarbor.
	2	+
	3	+**This page defines Roles, Content States, Rules, and System Requirements for FactHarbor.**
	4	+
3	3	**Core Philosophy:** Invest in system improvement, not manual data correction. When AI makes errors, improve the algorithm and re-process automatically.
	6	+
	7	+== Navigation ==
	8	+
	9	+* **[[User Needs>>FactHarbor.Specification.Requirements.User Needs.WebHome]]** - What users need from FactHarbor (drives these requirements)
	10	+* **This page** - How we fulfill those needs through system design
	11	+
	12	+(% class="box infomessage" %)
	13	+(((
	14	+**How to read this page:**
	15	+
	16	+1. **User Needs drive Requirements**: See [[User Needs>>FactHarbor.Specification.Requirements.User Needs.WebHome]] for what users need
	17	+2. **Requirements define implementation**: This page shows how we fulfill those needs
	18	+3. **Functional Requirements (FR)**: Specific features and capabilities
	19	+4. **Non-Functional Requirements (NFR)**: Quality attributes (performance, security, etc.)
	20	+
	21	+Each requirement references which User Needs it fulfills.
	22	+)))
	23	+
4	4	== 1. Roles ==
	25	+
	26	+**Fulfills**: UN-12 (Submit claims), UN-13 (Cite verdicts), UN-14 (API access)
	27	+
5	5	FactHarbor uses three simple roles plus a reputation system.
	29	+
6	6	=== 1.1 Reader ===
	31	+
7	7	**Who**: Anyone (no login required)
	33	+
8	8	**Can**:
	35	+
9	9	* Browse and search claims
10	10	* View scenarios, evidence, verdicts, and confidence scores
11	11	* Flag issues or errors
12	12	* Use filters, search, and visualization tools
13	13	* Submit claims automatically (new claims added if not duplicates)
	41	+
14	14	**Cannot**:
	43	+
15	15	* Modify content
16	16	* Access edit history details
	46	+
	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)
	48	+
17	17	=== 1.2 Contributor ===
	50	+
18	18	**Who**: Registered users (earns reputation through contributions)
	52	+
19	19	**Can**:
	54	+
20	20	* Everything a Reader can do
21	21	* Edit claims, evidence, and scenarios
22	22	* Add sources and citations
...	...	@@ -23,18 +23,28 @@
23	23	* Suggest improvements to AI-generated content
24	24	* Participate in discussions
25	25	* Earn reputation points for quality contributions
	61	+
26	26	**Reputation System**:
	63	+
27	27	* New contributors: Limited edit privileges
28	28	* Established contributors (established reputation): Full edit access
29	29	* Trusted contributors (substantial reputation): Can approve certain changes
30	30	* Reputation earned through: Accepted edits, helpful flags, quality contributions
31	31	* Reputation lost through: Reverted edits, invalid flags, abuse
	69	+
32	32	**Cannot**:
	71	+
33	33	* Delete or hide content (only moderators)
34	34	* Override moderation decisions
	74	+
	75	+**User Needs served**: UN-13 (Cite and contribute)
	76	+
35	35	=== 1.3 Moderator ===
	78	+
36	36	**Who**: Trusted community members with proven track record, appointed by governance board
	80	+
37	37	**Can**:
	82	+
38	38	* Review flagged content
39	39	* Hide harmful or abusive content
40	40	* Resolve disputes between contributors
...	...	@@ -41,34 +41,56 @@
41	41	* Issue warnings or temporary bans
42	42	* Make final decisions on content disputes
43	43	* Access full audit logs
	89	+
44	44	**Cannot**:
	91	+
45	45	* Change governance rules
46	46	* Permanently ban users without board approval
47	47	* Override technical quality gates
	95	+
48	48	**Note**: Small team (3-5 initially), supported by automated moderation tools.
	97	+
49	49	=== 1.4 Domain Trusted Contributors (Optional, Task-Specific) ===
	99	+
50	50	**Who**: Subject matter specialists invited for specific high-stakes disputes
	101	+
51	51	**Not a permanent role**: Contacted externally when needed for contested claims in their domain
	103	+
52	52	**When used**:
	105	+
53	53	* Medical claims with life/safety implications
54	54	* Legal interpretations with significant impact
55	55	* Scientific claims with high controversy
56	56	* Technical claims requiring specialized knowledge
	110	+
57	57	**Process**:
	112	+
58	58	* Moderator identifies need for expert input
59	59	* Contact expert externally (don't require them to be users)
60	60	* Trusted Contributor provides written opinion with sources
61	61	* Opinion added to claim record
62	62	* Trusted Contributor acknowledged in claim
	118	+
	119	+**User Needs served**: UN-16 (Expert validation status)
	120	+
63	63	== 2. Content States ==
	122	+
	123	+**Fulfills**: UN-1 (Trust indicators), UN-16 (Review status transparency)
	124	+
64	64	FactHarbor uses two content states. Focus is on transparency and confidence scoring, not gatekeeping.
	126	+
65	65	=== 2.1 Published ===
	128	+
66	66	**Status**: Visible to all users
	130	+
67	67	**Includes**:
	132	+
68	68	* AI-generated analyses (default state)
69	69	* User-contributed content
70	70	* Edited/improved content
	136	+
71	71	**Quality Indicators** (displayed with content):
	138	+
72	72	* **Confidence Score**: 0-100% (AI's confidence in analysis)
73	73	* **Source Quality Score**: 0-100% (based on source track record)
74	74	* **Controversy Flag**: If high dispute/edit activity
...	...	@@ -75,14 +75,23 @@
75	75	* **Completeness Score**: % of expected fields filled
76	76	* **Last Updated**: Date of most recent change
77	77	* **Edit Count**: Number of revisions
	145	+* **Review Status**: AI-generated / Human-reviewed / Expert-validated
	146	+
78	78	**Automatic Warnings**:
	148	+
79	79	* Confidence < 60%: "Low confidence - use caution"
80	80	* Source quality < 40%: "Sources may be unreliable"
81	81	* High controversy: "Disputed - multiple interpretations exist"
82	82	* Medical/Legal/Safety domain: "Seek professional advice"
	153	+
	154	+**User Needs served**: UN-1 (Trust score), UN-9 (Methodology transparency), UN-15 (Evolution timeline), UN-16 (Review status)
	155	+
83	83	=== 2.2 Hidden ===
	157	+
84	84	**Status**: Not visible to regular users (only to moderators)
	159	+
85	85	**Reasons**:
	161	+
86	86	* Spam or advertising
87	87	* Personal attacks or harassment
88	88	* Illegal content
...	...	@@ -89,22 +89,32 @@
89	89	* Privacy violations
90	90	* Deliberate misinformation (verified)
91	91	* Abuse or harmful content
	168	+
92	92	**Process**:
	170	+
93	93	* Automated detection flags for moderator review
94	94	* Moderator confirms and hides
95	95	* Original author notified with reason
96	96	* Can appeal to board if disputes moderator decision
	175	+
97	97	**Note**: Content is hidden, not deleted (for audit trail)
	177	+
98	98	== 3. Contribution Rules ==
	179	+
99	99	=== 3.1 All Contributors Must ===
	181	+
100	100	* Provide sources for factual claims
101	101	* Use clear, neutral language in FactHarbor's own summaries
102	102	* Respect others and maintain civil discourse
103	103	* Accept community feedback constructively
104	104	* Focus on improving quality, not protecting ego
	187	+
105	105	=== 3.2 AKEL (AI System) ===
	189	+
106	106	**AKEL is the primary system**. Human contributions supplement and train AKEL.
	191	+
107	107	**AKEL Must**:
	193	+
108	108	* Mark all outputs as AI-generated
109	109	* Display confidence scores prominently
110	110	* Provide source citations
...	...	@@ -111,86 +111,139 @@
111	111	* Flag uncertainty clearly
112	112	* Identify contradictions in evidence
113	113	* Learn from human corrections
	200	+
114	114	**When AKEL Makes Errors**:
	202	+
115	115	1. Capture the error pattern (what, why, how common)
116	116	2. Improve the system (better prompt, model, validation)
117	117	3. Re-process affected claims automatically
118	118	4. Measure improvement (did quality increase?)
	207	+
119	119	**Human Role**: Train AKEL through corrections, not replace AKEL
	209	+
120	120	=== 3.3 Contributors Should ===
	211	+
121	121	* Improve clarity and structure
122	122	* Add missing sources
123	123	* Flag errors for system improvement
124	124	* Suggest better ways to present information
125	125	* Participate in quality discussions
	217	+
126	126	=== 3.4 Moderators Must ===
	219	+
127	127	* Be impartial
128	128	* Document moderation decisions
129	129	* Respond to appeals promptly
130	130	* Use automated tools to scale efforts
131	131	* Focus on abuse/harm, not routine quality control
	225	+
132	132	== 4. Quality Standards ==
	227	+
	228	+**Fulfills**: UN-5 (Source reliability), UN-6 (Publisher track records), UN-7 (Evidence transparency), UN-9 (Methodology transparency)
	229	+
133	133	=== 4.1 Source Requirements ===
	231	+
134	134	**Track Record Over Credentials**:
	233	+
135	135	* Sources evaluated by historical accuracy
136	136	* Correction policy matters
137	137	* Independence from conflicts of interest
138	138	* Methodology transparency
	238	+
139	139	**Source Quality Database**:
	240	+
140	140	* Automated tracking of source accuracy
141	141	* Correction frequency
142	142	* Reliability score (updated continuously)
143	143	* Users can see source track record
	245	+
144	144	**No automatic trust** for government, academia, or media - all evaluated by track record.
	247	+
	248	+**User Needs served**: UN-5 (Source provenance), UN-6 (Publisher reliability)
	249	+
145	145	=== 4.2 Claim Requirements ===
	251	+
146	146	* Clear subject and assertion
147	147	* Verifiable with available information
148	148	* Sourced (or explicitly marked as needing sources)
149	149	* Neutral language in FactHarbor summaries
150	150	* Appropriate context provided
	257	+
	258	+**User Needs served**: UN-2 (Claim extraction and verification)
	259	+
151	151	=== 4.3 Evidence Requirements ===
	261	+
152	152	* Publicly accessible (or explain why not)
153	153	* Properly cited with attribution
154	154	* Relevant to claim being evaluated
155	155	* Original source preferred over secondary
	266	+
	267	+**User Needs served**: UN-7 (Evidence transparency)
	268	+
156	156	=== 4.4 Confidence Scoring ===
	270	+
157	157	**Automated confidence calculation based on**:
	272	+
158	158	* Source quality scores
159	159	* Evidence consistency
160	160	* Contradiction detection
161	161	* Completeness of analysis
162	162	* Historical accuracy of similar claims
	278	+
163	163	**Thresholds**:
	280	+
164	164	* < 40%: Too low to publish (needs improvement)
165	165	* 40-60%: Published with "Low confidence" warning
166	166	* 60-80%: Published as standard
167	167	* 80-100%: Published as "High confidence"
	285	+
	286	+**User Needs served**: UN-1 (Trust assessment), UN-9 (Methodology transparency)
	287	+
168	168	== 5. Automated Risk Scoring ==
	289	+
	290	+**Fulfills**: UN-10 (Manipulation detection), UN-16 (Appropriate review level)
	291	+
169	169	**Replace manual risk tiers with continuous automated scoring**.
	293	+
170	170	=== 5.1 Risk Score Calculation ===
	295	+
171	171	**Factors** (weighted algorithm):
	297	+
172	172	* **Domain sensitivity**: Medical, legal, safety auto-flagged higher
173	173	* **Potential impact**: Views, citations, spread
174	174	* **Controversy level**: Flags, disputes, edit wars
175	175	* **Uncertainty**: Low confidence, contradictory evidence
176	176	* **Source reliability**: Track record of sources used
	303	+
177	177	**Score**: 0-100 (higher = more risk)
	305	+
178	178	=== 5.2 Automated Actions ===
	307	+
179	179	* **Score > 80**: Flag for moderator review before publication
180	180	* **Score 60-80**: Publish with prominent warnings
181	181	* **Score 40-60**: Publish with standard warnings
182	182	* **Score < 40**: Publish normally
	312	+
183	183	**Continuous monitoring**: Risk score recalculated as new information emerges
	314	+
	315	+**User Needs served**: UN-10 (Detect manipulation tactics), UN-16 (Review status)
	316	+
184	184	== 6. System Improvement Process ==
	318	+
185	185	**Core principle**: Fix the system, not just the data.
	320	+
186	186	=== 6.1 Error Capture ===
	322	+
187	187	**When users flag errors or make corrections**:
	324	+
188	188	1. What was wrong? (categorize)
189	189	2. What should it have been?
190	190	3. Why did the system fail? (root cause)
191	191	4. How common is this pattern?
192	192	5. Store in ErrorPattern table (improvement queue)
	330	+
193	193	=== 6.2 Weekly Improvement Cycle ===
	332	+
194	194	1. **Review**: Analyze top error patterns
195	195	2. **Develop**: Create fix (prompt, model, validation)
196	196	3. **Test**: Validate fix on sample claims
...	...	@@ -197,8 +197,11 @@
197	197	4. **Deploy**: Roll out if quality improves
198	198	5. **Re-process**: Automatically update affected claims
199	199	6. **Monitor**: Track quality metrics
	339	+
200	200	=== 6.3 Quality Metrics Dashboard ===
	341	+
201	201	**Track continuously**:
	343	+
202	202	* Error rate by category
203	203	* Source quality distribution
204	204	* Confidence score trends
...	...	@@ -206,158 +206,518 @@
206	206	* Correction acceptance rate
207	207	* Re-work rate
208	208	* Claims processed per hour
	351	+
209	209	**Goal**: 10% monthly improvement in error rate
	353	+
210	210	== 7. Automated Quality Monitoring ==
	355	+
211	211	**Replace manual audit sampling with automated monitoring**.
	357	+
212	212	=== 7.1 Continuous Metrics ===
	359	+
213	213	* **Source quality**: Track record database
214	214	* **Consistency**: Contradiction detection
215	215	* **Clarity**: Readability scores
216	216	* **Completeness**: Field validation
217	217	* **Accuracy**: User corrections tracked
	365	+
218	218	=== 7.2 Anomaly Detection ===
	367	+
219	219	**Automated alerts for**:
	369	+
220	220	* Sudden quality drops
221	221	* Unusual patterns
222	222	* Contradiction clusters
223	223	* Source reliability changes
224	224	* User behavior anomalies
	375	+
225	225	=== 7.3 Targeted Review ===
	377	+
226	226	* Review only flagged items
227	227	* Random sampling for calibration (not quotas)
228	228	* Learn from corrections to improve automation
229		-== 8. Claim Intake & Normalization ==
230		-=== 8.1 FR1 – Claim Intake ===
	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	+
231	231	* Users submit claims via simple form or API
232	232	* Claims can be text, URL, or image
233	233	* Duplicate detection (semantic similarity)
234	234	* Auto-categorization by domain
235		-=== 8.2 FR2 – Claim Normalization ===
	396	+
	397	+==== FR2 — Claim Normalization ====
	398	+
	399	+**Fulfills**: UN-2 (Claim verification)
	400	+
236	236	* Standardize to clear assertion format
237	237	* Extract key entities (who, what, when, where)
238	238	* Identify claim type (factual, predictive, evaluative)
239	239	* Link to existing similar claims
240		-=== 8.3 FR3 – Claim Classification ===
	405	+
	406	+==== FR3 — Claim Classification ====
	407	+
	408	+**Fulfills**: UN-11 (Filtered research)
	409	+
241	241	* Domain: Politics, Science, Health, etc.
242	242	* Type: Historical fact, current stat, prediction, etc.
243	243	* Risk score: Automated calculation
244	244	* Complexity: Simple, moderate, complex
245		-== 9. Scenario System ==
246		-=== 9.1 FR4 – Scenario Generation ===
	414	+
	415	+=== 8.2 Scenario System ===
	416	+
	417	+==== FR4 — Scenario Generation ====
	418	+
	419	+**Fulfills**: UN-2 (Context-dependent verification), UN-3 (Article summary with FactHarbor analysis summary), UN-8 (Understanding disagreement)
	420	+
247	247	**Automated scenario creation**:
248		-* AKEL analyzes claim and generates likely scenarios
249		-* Each scenario includes: assumptions, evidence, conclusion
	422	+
	423	+* AKEL analyzes claim and generates likely scenarios (use-cases and contexts)
	424	+* Each scenario includes: assumptions, definitions, boundaries, evidence context
250	250	* Users can flag incorrect scenarios
251	251	* System learns from corrections
252		-=== 9.2 FR5 – Evidence Linking ===
	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	+
253	253	* Automated evidence discovery from sources
254	254	* Relevance scoring
255	255	* Contradiction detection
256	256	* Source quality assessment
257		-=== 9.3 FR6 – Scenario Comparison ===
	438	+
	439	+==== FR6 — Scenario Comparison ====
	440	+
	441	+**Fulfills**: UN-3 (Article summary with FactHarbor analysis summary), UN-8 (Understanding disagreement)
	442	+
258	258	* Side-by-side comparison interface
259		-* Highlight key differences
260		-* Show evidence supporting each
261		-* Display confidence scores
262		-== 10. Verdicts & Analysis ==
263		-=== 10.1 FR7 – Automated Verdicts ===
264		-* AKEL generates verdict based on evidence
	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	+
	452	+**Fulfills**: UN-1 (Trust score), UN-2 (Verification verdicts), UN-3 (Article summary with FactHarbor analysis summary), UN-13 (Cite verdicts)
	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")
265	265	* Confidence score displayed prominently
266		-* Source quality indicators
	458	+* Source quality indicators shown
267	267	* Contradictions noted
268	268	* Uncertainty acknowledged
269		-=== 10.2 FR8 – Time Evolution ===
270		-* Claims update as new evidence emerges
271		-* Version history maintained
	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
272	272	* Changes highlighted
273	273	* Confidence score trends visible
274		-== 11. Workflow & Moderation ==
275		-=== 11.1 FR9 – Publication Workflow ===
	472	+* Users can see "as of date X, what did we know?"
	473	+
	474	+=== 8.4 User Interface & Presentation ===
	475	+
	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**:
	483	+
	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**:
	491	+
	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**:
	499	+
	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**:
	507	+
	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	+
	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	+
	521	+(% class="box" %)
	522	+(((
	523	+**Article: "New Study Shows Benefits of Mediterranean Diet"**
	524	+
	525	+A recent study published in the Journal of Nutrition has revealed new findings about the Mediterranean diet.
	526	+
	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 →]]
	534	+
	535	+
	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 →]]
	548	+
	549	+
	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 →]]
	562	+
	563	+
	564	+)))
	565	+
	566	+Participants also reported feeling more energetic and experiencing better sleep quality, though these were secondary measures.
	567	+)))
	568	+
	569	+**Legend:**
	570	+
	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	+
	576	+==== Tooltip on Hover/Click ====
	577	+
	578	+(% class="box infomessage" %)
	579	+(((
	580	+**FactHarbor Analysis**
	581	+
	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:**
	589	+
	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:**
	595	+
	596	+* Exact percentage varies by study (20-30% range)
	597	+
	598	+[[View Full Analysis →]]
	599	+)))
	600	+
	601	+**Color-Coding System**:
	602	+
	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	+
	608	+==== Interactive Highlighting Example (Detailed View) ====
	609	+
	610	+(% style="width:100%; border-collapse:collapse;" %)
	611	+|=**Article Text**|=**Status**|=**Analysis**
	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**|(((
	618	+**87% confidence**
	619	+
	620	+Meta-analysis of 12 RCTs confirms 23-28% risk reduction
	621	+
	622	+[[View Full Analysis]]
	623	+)))
	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**|(((
	630	+**45% confidence**
	631	+
	632	+Overstated - evidence shows risk reduction, not prevention
	633	+
	634	+[[View Details]]
	635	+)))
	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**|(((
	642	+**15% confidence**
	643	+
	644	+Claim not supported by study; correlation ≠ causation
	645	+
	646	+[[View Counter-Evidence]]
	647	+)))
	648	+
	649	+**Design Notes:**
	650	+
	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	+
	656	+**User Actions**:
	657	+
	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**:
	664	+
	665	+* Hover/click on highlighted claim → Show tooltip with:
	666	+* Claim text
	667	+* Verdict (e.g., "WELL SUPPORTED")
	668	+* Confidence score (e.g., "85%")
	669	+* Brief evidence summary
	670	+* Link to detailed analysis
	671	+* Toggle highlighting on/off (user preference)
	672	+* Adjustable color intensity for accessibility
	673	+
	674	+**Technical Requirements**:
	675	+
	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**:
	683	+
	684	+* Highlighting renders within 500ms of page load
	685	+* No perceptible delay in reading experience
	686	+* Efficient DOM manipulation (avoid reflows)
	687	+
	688	+**Accessibility**:
	689	+
	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**:
	695	+
	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	+
	701	+=== 8.5 Workflow & Moderation ===
	702	+
	703	+==== FR9 — Publication Workflow ====
	704	+
	705	+**Fulfills**: UN-1 (Fast access to verified content), UN-16 (Clear review status)
	706	+
276	276	**Simple flow**:
	708	+
277	277	1. Claim submitted
278	278	2. AKEL processes (automated)
279		-3. If confidence > threshold: Publish
	711	+3. If confidence > threshold: Publish (labeled as AI-generated)
280	280	4. If confidence < threshold: Flag for improvement
281	281	5. If risk score > threshold: Flag for moderator
	714	+
282	282	**No multi-stage approval process**
283		-=== 11.2 FR10 – Moderation ===
	716	+
	717	+==== FR10 — Moderation ====
	718	+
284	284	**Focus on abuse, not routine quality**:
	720	+
285	285	* Automated abuse detection
286	286	* Moderators handle flags
287	287	* Quick response to harmful content
288	288	* Minimal involvement in routine content
289		-=== 11.3 FR11 – Audit Trail ===
	725	+
	726	+==== FR11 — Audit Trail ====
	727	+
	728	+**Fulfills**: UN-14 (API access to histories), UN-15 (Evolution tracking)
	729	+
290	290	* All edits logged
291	291	* Version history public
292	292	* Moderation decisions documented
293	293	* System improvements tracked
294		-== 12. Technical Requirements ==
295		-=== 12.1 NFR1 – Performance ===
	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	+
296	296	* Claim processing: < 30 seconds
297	297	* Search response: < 2 seconds
298	298	* Page load: < 3 seconds
299	299	* 99% uptime
300		-=== 12.2 NFR2 – Scalability ===
	745	+
	746	+=== 9.2 NFR2 — Scalability ===
	747	+
	748	+**Fulfills**: UN-14 (API access at scale)
	749	+
301	301	* Handle 10,000 claims initially
302	302	* Scale to 1M+ claims
303	303	* Support 100K+ concurrent users
304	304	* Automated processing scales linearly
305		-=== 12.3 NFR3 – Transparency ===
	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	+
306	306	* All algorithms open source
307	307	* All data exportable
308	308	* All decisions documented
309	309	* Quality metrics public
310		-=== 12.4 NFR4 – Security & Privacy ===
	763	+
	764	+=== 9.4 NFR4 — Security & Privacy ===
	765	+
311	311	* Follow [[Privacy Policy>>FactHarbor.Organisation.How-We-Work-Together.Privacy-Policy]]
312	312	* Secure authentication
313	313	* Data encryption
314	314	* Regular security audits
315		-=== 12.5 NFR5 – Maintainability ===
	770	+
	771	+=== 9.5 NFR5 — Maintainability ===
	772	+
316	316	* Modular architecture
317	317	* Automated testing
318	318	* Continuous integration
319	319	* Comprehensive documentation
320		-== 13. MVP Scope ==
	777	+
	778	+== 10. MVP Scope ==
	779	+
321	321	**Phase 1 (Months 1-3): Read-Only MVP**
	781	+
322	322	Build:
	783	+
323	323	* Automated claim analysis
324	324	* Confidence scoring
325	325	* Source evaluation
326	326	* Browse/search interface
327	327	* User flagging system
	789	+
328	328	**Goal**: Prove AI quality before adding user editing
	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	+
329	329	**Phase 2 (Months 4-6): User Contributions**
	795	+
330	330	Add only if needed:
	797	+
331	331	* Simple editing (Wikipedia-style)
332	332	* Reputation system
333	333	* Basic moderation
	801	+* In-article claim highlighting (FR13)
	802	+
	803	+**Additional User Needs fulfilled**: UN-13, UN-17
	804	+
334	334	**Phase 3 (Months 7-12): Refinement**
	806	+
335	335	* Continuous quality improvement
336	336	* Feature additions based on real usage
337	337	* Scale infrastructure
	810	+
	811	+**Additional User Needs fulfilled**: UN-14 (API access), UN-15 (Full evolution tracking)
	812	+
338	338	**Deferred**:
	814	+
339	339	* Federation (until multiple successful instances exist)
340	340	* Complex contribution workflows (focus on automation)
341	341	* Extensive role hierarchy (keep simple)
342		-== 14. Success Metrics ==
	818	+
	819	+== 11. Success Metrics ==
	820	+
343	343	**System Quality** (track weekly):
	822	+
344	344	* Error rate by category (target: -10%/month)
345	345	* Average confidence score (target: increase)
346	346	* Source quality distribution (target: more high-quality)
347	347	* Contradiction detection rate (target: increase)
	827	+
348	348	**Efficiency** (track monthly):
	829	+
349	349	* Claims processed per hour (target: increase)
350	350	* Human hours per claim (target: decrease)
351	351	* Automation coverage (target: >90%)
352	352	* Re-work rate (target: <5%)
	834	+
353	353	**User Satisfaction** (track quarterly):
	836	+
354	354	* User flag rate (issues found)
355	355	* Correction acceptance rate (flags valid)
356	356	* Return user rate
357	357	* Trust indicators (surveys)
358		-== 15. Related Pages ==
359		-* [[Architecture>>FactHarbor.Specification.Architecture.WebHome]]
360		-* [[Data Model>>FactHarbor.Specification.Data Model.WebHome]]
361		-* [[Workflows>>FactHarbor.Specification.Workflows.WebHome]]
362		-* [[Global Rules>>FactHarbor.Organisation.How-We-Work-Together.GlobalRules.WebHome]]
	841	+
	842	+**User Needs Metrics** (track quarterly):
	843	+
	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
	849	+* UN-17: % users who enable in-article highlighting; avg. time spent on highlighted vs. non-highlighted articles
	850	+
	851	+== 12. Requirements Traceability ==
	852	+
	853	+For full traceability matrix showing which requirements fulfill which user needs, see:
	854	+
	855	+* [[User Needs>>FactHarbor.Specification.Requirements.User Needs.WebHome]] - Section 8 includes comprehensive mapping tables
	856	+
	857	+== 13. Related Pages ==
	858	+
	859	+* **[[User Needs>>FactHarbor.Specification.Requirements.User Needs.WebHome]]** - What users need (drives these requirements)
	860	+* [[Architecture>>Archive.FactHarbor.Specification.Architecture.WebHome]] - How requirements are implemented
	861	+* [[Data Model>>FactHarbor.Specification.Data Model.WebHome]] - Data structures supporting requirements
	862	+* [[Workflows>>FactHarbor.Specification.Workflows.WebHome]] - User interaction workflows
	863	+* [[AKEL>>Archive.FactHarbor.Specification.AI Knowledge Extraction Layer (AKEL).WebHome]] - AI system fulfilling automation requirements
	864	+* [[Global Rules>>Archive.FactHarbor.Organisation.How-We-Work-Together.GlobalRules.WebHome]]
363	363	* [[Privacy Policy>>FactHarbor.Organisation.How-We-Work-Together.Privacy-Policy]]