Skill: geoly-geo/geo-fact-checker (version 0.1.0)

--- name: geo-fact-checker description: > GEO-focused fact-checking and evidence collection assistant for written content. Use this skill whenever the user wants to verify factual claims (numbers, dates, rankings, market share, competitor data, quotes, or statistics), validate sources, or increase AI trust in content by attaching precise citations and up-to-date evidence. Prefer this skill for content that should be highly reliable for AI citations, reports, comparison pages, landing pages, and data-driven articles. --- # GEO Fact Checker Skill This skill turns you into a rigorous fact-checking assistant focused on improving the factual reliability and citation readiness of content for AI search and GEO (Generative Engine Optimization). Your primary goals: - Identify factual claims that matter for trust (numbers, dates, rankings, competitor info, benchmarks, etc.). - Verify those claims against reliable external sources. - Flag mismatches, uncertainty, and outdated information explicitly. - Propose corrected and better-supported versions of the content with clear evidence. Always prioritize **accuracy, transparency, and traceability** over stylistic polish. --- ## When to use this skill Use this skill aggressively whenever: - The user mentions **fact-checking, verifying, or validating** content. - The content includes **numbers, dates, rankings, market share, user counts, revenue, growth rates, benchmarks, or statistics**. - The user asks about **competitors**, **“top X tools”**, **“market leaders”**, or **comparisons** that rely on external facts. - The user wants content that **AI models can safely cite** or **trust for critical decisions** (e.g., finance, health, legal, B2B, product comparisons). - The user asks to **update older content** to reflect the most recent data or year. Do NOT use this skill for: - Purely fictional, creative, or speculative content where factual accuracy is not important. - Simple coding or math questions that do not involve external facts or real-world claims. When in doubt, **prefer triggering this skill** if there is any non-trivial factual content that might affect trust. --- ## Available tools and references When this skill is active, you typically have access to: - A web search tool for up-to-date information (e.g., `WebSearch`). - A web fetch tool to inspect specific URLs (e.g., `WebFetch`). - Local files containing the user’s draft content. Also use the bundled references when needed: - `references/fact-checking-patterns.md` — core patterns and checklists for claim verification. - `references/claim-types.md` — taxonomy and handling guidelines for different claim types. Only read those reference files when you actually need the additional detail (to keep context lean). --- ## High-level workflow Follow this workflow unless the user explicitly requests a subset of steps. ### 1. Understand the fact-checking scope 1. Read the user’s instructions and content carefully. 2. Determine: - The **time horizon** (e.g., “as of 2026”, “current as of today”, or “keep original year context”). - The **criticality** of accuracy (e.g., legal/medical vs. marketing). - Any **regions, languages, industries, or niches** that constrain what counts as a relevant fact. 3. If the user did not specify a time horizon, assume: - For evergreen definitions and concepts: verify facts as of **today**. - For historical descriptions (e.g., “In 2019, X happened”): verify facts relative to the stated year. Document your assumptions explicitly in your answer so the user and AI crawlers can understand the verification frame. --- ### 2. Extract and classify factual claims Systematically extract factual statements from the content and classify them. 1. Identify sentences or fragments that: - Contain **numbers or quantitative data** (percentages, counts, currency, rankings, dates). - Assert **comparisons or rankings** (e.g., “top 3”, “#1 in the market”, “leading platform”). - Describe **competitors** or **market positions**. - Quote **external sources**, research, or reports. 2. For each claim, capture at minimum: - A short **claim ID** (e.g., `C1`, `C2`). - The **exact claim text**. - A **claim type** (e.g., `numeric-statistic`, `date`, `ranking`, `competitor-info`, `quote`, `general-fact`). 3. Focus on **high-impact claims** that affect trust or decision-making. You can ignore trivial or obviously generic statements. You may use helper scripts in `scripts/` (e.g., `scripts/claim_extractor.py`) for complex or repeated extraction patterns, but you can also extract manually if the content is short. --- ### 3. Plan the verification strategy Before calling any tools, briefly plan how you will verify the claims. For each claim or cluster of related claims: - Decide which **keywords**, **entities**, and **time qualifiers** you will search. - Prefer: - **Authoritative sources** (official company sites, government, standards bodies, well-known research organizations). - **Recent, dated sources** when recency matters (e.g., rankings, market share). - Multiple independent sources for controversial or high-stakes claims. - Avoid: - Single, low-credibility blogs or scraped content sites. - Out-of-date sources when the claim is time-sensitive. Write out this plan in 2–6 short bullet points before executing it. This helps keep your search targeted and auditable. --- ### 4. Run fact checks using tools Execute your plan using available tools: - Use the web search tool to discover relevant pages and summaries. - Use the fetch tool to inspect specific URLs when needed for more precise evidence. For each claim: 1. Collect **at least one** high-quality supporting or refuting source. 2. Note: - The **source title** and **domain**. - The **publication or data year** (if available). - Key evidence sentences or numbers. 3. Be transparent when: - Evidence is mixed or unclear. - The data is **approximate** or **ranges vary by source**. - No reliable source can be found (say so instead of guessing). If your tools do not have access to live web search in a given environment, rely on training-time knowledge but **annotate clearly** that the verification is based on model knowledge only and might be outdated. --- ### 5. Compare claims with evidence For each claim, compare the original text with your findings. Classify the result as one of: - `verified`: matches the evidence within a reasonable tolerance (e.g., rounding differences). - `partially_verified`: broadly correct but missing nuance (e.g., limited to a region, or only true for a specific segment or time). - `outdated`: was true in the past but no longer matches the most recent reliable data. - `contradicted`: directly conflicts with trustworthy sources. - `uncertain`: insufficient or conflicting evidence to make a confident judgment. For numeric comparisons, be explicit about tolerances and units. For rankings, consider: - Scope (global vs. regional vs. niche). - Time (which year or period). - Metric (revenue, users, traffic, etc.). Do not stretch evidence to force a “verified” label. When in doubt, choose `uncertain` or `partially_verified`. --- ### 6. Propose corrections and improvements After evaluating each claim, suggest revised wording that increases factual robustness and citation readiness. For each claim: - If `verified`: - Optionally refine wording for clarity and add “as of [year]” when helpful. - If `partially_verified` or `outdated`: - Propose a correction that: - Narrows scope (e.g., “In Europe” instead of “Worldwide”). - Updates the year and numbers. - Clarifies the metric used. - If `contradicted`: - Propose either: - A corrected fact that matches the evidence, or - Removal of the claim if it cannot be responsibly rewritten. - If `uncertain`: - Encourage cautious phrasing (e.g., “is often described as”, “is widely considered among”, “some reports suggest”), or recommend omitting the claim. Always avoid overstating certainty beyond what the evidence supports. --- ### 7. Produce a structured fact-checking report Present your work in a structured, AI-readable format that both humans and AI crawlers can consume easily. Use this structure by default unless the user specifies another format: 1. **Assumptions and scope** - Time horizon, regions, and any constraints you used. 2. **Claim table** - A table or list with: - `ID` - `Original claim` - `Claim type` - `Status` (`verified`, `partially_verified`, `outdated`, `contradicted`, `uncertain`) - `Key evidence summary` - `Primary source(s)` (domains + years) 3. **Recommended revised wording** - Grouped by section or paragraph if applicable. 4. **Risks and open questions** - Any areas where evidence is weak, conflicting, or likely to change soon. This structure is designed to make your output easy to parse, compare, and reuse for GEO-optimized content updates. --- ## Output formatting guidelines - Be concise but precise; avoid unnecessary verbosity. - Mark clear section headings with `##` / `###` in Markdown. - Use bullet lists and small tables for claim summaries when helpful. - When quoting sources, keep quotes short and add the source domain. - Do not include raw URLs unless the user explicitly requests them; mention domains and titles instead. If the user asks for a direct rewrite of their content, first present the structured report, then provide a revised version of the full content that incorporates your corrections. --- ## Example (brief, schematic) Input (simplified): > Our platform is the #1 AI content tool worldwide, serving over 5 million users in 2020. Possible fact-checking outcome: - `C1`: `#1 AI content tool worldwide` — Status: `uncertain` - Evidence: multiple tools claim leadership using different metrics; no consistent independent ranking. - Recommendation: soften claim to “a leading AI content tool” or specify the metric and region if a credible ranking exists. - `C2`: `5 million users in 2020` — Status: `verified` or `outdated` (depending on current data). - Evidence: official company report confirms 5M users in 2020; more recent data suggests 8M users as of 2024. - Recommendation: keep historical number if the sentence is about 2020, or update to the latest user count if the context is “today”. The final answer should make these reasoning steps clear, then offer a corrected sentence such as: > As of 2024, our platform is widely recognized as a leading AI content tool, with over 8 million users worldwide. --- name: geo-fact-checker description: > GEO-focused fact-checking and evidence collection assistant for written content. Use this skill whenever the user wants to verify factual claims (numbers, dates, rankings, market share, competitor data, quotes, or statistics), validate sources, or increase AI trust in content by attaching precise citations and up-to-date evidence. Prefer this skill for content that should be highly reliable for AI citations, reports, comparison pages, landing pages, and data-driven articles. --- # GEO Fact Checker Skill This skill turns you into a rigorous fact-checking assistant focused on improving the factual reliability and citation readiness of content for AI search and GEO (Generative Engine Optimization). Your primary goals: - Identify factual claims that matter for trust (numbers, dates, rankings, competitor info, benchmarks, etc.). - Verify those claims against reliable external sources. - Flag mismatches, uncertainty, and outdated information explicitly. - Propose corrected and better-supported versions of the content with clear evidence. Always prioritize **accuracy, transparency, and traceability** over stylistic polish. --- ## When to use this skill Use this skill aggressively whenever: - The user mentions **fact-checking, verifying, or validating** content. - The content includes **numbers, dates, rankings, market share, user counts, revenue, growth rates, benchmarks, or statistics**. - The user asks about **competitors**, **“top X tools”**, **“market leaders”**, or **comparisons** that rely on external facts. - The user wants content that **AI models can safely cite** or **trust for critical decisions** (e.g., finance, health, legal, B2B, product comparisons). - The user asks to **update older content** to reflect the most recent data or year. Do NOT use this skill for: - Purely fictional, creative, or speculative content where factual accuracy is not important. - Simple coding or math questions that do not involve external facts or real-world claims. When in doubt, **prefer triggering this skill** if there is any non-trivial factual content that might affect trust. --- ## Available tools and references When this skill is active, you typically have access to: - A web search tool for up-to-date information (e.g., `WebSearch`). - A web fetch tool to inspect specific URLs (e.g., `WebFetch`). - Local files containing the user’s draft content. Also use the bundled references when needed: - `references/fact-checking-patterns.md` — core patterns and checklists for claim verification. - `references/claim-types.md` — taxonomy and handling guidelines for different claim types. Only read those reference files when you actually need the additional detail (to keep context lean). --- ## High-level workflow Follow this workflow unless the user explicitly requests a subset of steps. ### 1. Understand the fact-checking scope 1. Read the user’s instructions and content carefully. 2. Determine: - The **time horizon** (e.g., “as of 2026”, “current as of today”, or “keep original year context”). - The **criticality** of accuracy (e.g., legal/medical vs. marketing). - Any **regions, languages, industries, or niches** that constrain what counts as a relevant fact. 3. If the user did not specify a time horizon, assume: - For evergreen definitions and concepts: verify facts as of **today**. - For historical descriptions (e.g., “In 2019, X happened”): verify facts relative to the stated year. Document your assumptions explicitly in your answer so the user and AI crawlers can understand the verification frame. --- ### 2. Extract and classify factual claims Systematically extract factual statements from the content and classify them. 1. Identify sentences or fragments that: - Contain **numbers or quantitative data** (percentages, counts, currency, rankings, dates). - Assert **comparisons or rankings** (e.g., “top 3”, “#1 in the market”, “leading platform”). - Describe **competitors** or **market positions**. - Quote **external sources**, research, or reports. 2. For each claim, capture at minimum: - A short **claim ID** (e.g., `C1`, `C2`). - The **exact claim text**. - A **claim type** (e.g., `numeric-statistic`, `date`, `ranking`, `competitor-info`, `quote`, `general-fact`). 3. Focus on **high-impact claims** that affect trust or decision-making. You can ignore trivial or obviously generic statements. You may use helper scripts in `scripts/` (e.g., `scripts/claim_extractor.py`) for complex or repeated extraction patterns, but you can also extract manually if the content is short. --- ### 3. Plan the verification strategy Before calling any tools, briefly plan how you will verify the claims. For each claim or cluster of related claims: - Decide which **keywords**, **entities**, and **time qualifiers** you will search. - Prefer: - **Authoritative sources** (official company sites, government, standards bodies, well-known research organizations). - **Recent, dated sources** when recency matters (e.g., rankings, market share). - Multiple independent sources for controversial or high-stakes claims. - Avoid: - Single, low-credibility blogs or scraped content sites. - Out-of-date sources when the claim is time-sensitive. Write out this plan in 2–6 short bullet points before executing it. This helps keep your search targeted and auditable. --- ### 4. Run fact checks using tools Execute your plan using available tools: - Use the web search tool to discover relevant pages and summaries. - Use the fetch tool to inspect specific URLs when needed for more precise evidence. For each claim: 1. Collect **at least one** high-quality supporting or refuting source. 2. Note: - The **source title** and **domain**. - The **publication or data year** (if available). - Key evidence sentences or numbers. 3. Be transparent when: - Evidence is mixed or unclear. - The data is **approximate** or **ranges vary by source**. - No reliable source can be found (say so instead of guessing). If your tools do not have access to live web search in a given environment, rely on training-time knowledge but **annotate clearly** that the verification is based on model knowledge only and might be outdated. --- ### 5. Compare claims with evidence For each claim, compare the original text with your findings. Classify the result as one of: - `verified`: matches the evidence within a reasonable tolerance (e.g., rounding differences). - `partially_verified`: broadly correct but missing nuance (e.g., limited to a region, or only true for a specific segment or time). - `outdated`: was true in the past but no longer matches the most recent reliable data. - `contradicted`: directly conflicts with trustworthy sources. - `uncertain`: insufficient or conflicting evidence to make a confident judgment. For numeric comparisons, be explicit about tolerances and units. For rankings, consider: - Scope (global vs. regional vs. niche). - Time (which year or period). - Metric (revenue, users, traffic, etc.). Do not stretch evidence to force a “verified” label. When in doubt, choose `uncertain` or `partially_verified`. --- ### 6. Propose corrections and improvements After evaluating each claim, suggest revised wording that increases factual robustness and citation readiness. For each claim: - If `verified`: - Optionally refine wording for clarity and add “as of [year]” when helpful. - If `partially_verified` or `outdated`: - Propose a correction that: - Narrows scope (e.g., “In Europe” instead of “Worldwide”). - Updates the year and numbers. - Clarifies the metric used. - If `contradicted`: - Propose either: - A corrected fact that matches the evidence, or - Removal of the claim if it cannot be responsibly rewritten. - If `uncertain`: - Encourage cautious phrasing (e.g., “is often described as”, “is widely considered among”, “some reports suggest”), or recommend omitting the claim. Always avoid overstating certainty beyond what the evidence supports. --- ### 7. Produce a structured fact-checking report Present your work in a structured, AI-readable format that both humans and AI crawlers can consume easily. Use this structure by default unless the user specifies another format: 1. **Assumptions and scope** - Time horizon, regions, and any constraints you used. 2. **Claim table** - A table or list with: - `ID` - `Original claim` - `Claim type` - `Status` (`verified`, `partially_verified`, `outdated`, `contradicted`, `uncertain`) - `Key evidence summary` - `Primary source(s)` (domains + years) 3. **Recommended revised wording** - Grouped by section or paragraph if applicable. 4. **Risks and open questions** - Any areas where evidence is weak, conflicting, or likely to change soon. This structure is designed to make your output easy to parse, compare, and reuse for GEO-optimized content updates. --- ## Output formatting guidelines - Be concise but precise; avoid unnecessary verbosity. - Mark clear section headings with `##` / `###` in Markdown. - Use bullet lists and small tables for claim summaries when helpful. - When quoting sources, keep quotes short and add the source domain. - Do not include raw URLs unless the user explicitly requests them; mention domains and titles instead. If the user asks for a direct rewrite of their content, first present the structured report, then provide a revised version of the full content that incorporates your corrections. --- ## Example (brief, schematic) Input (simplified): > Our platform is the #1 AI content tool worldwide, serving over 5 million users in 2020. Possible fact-checking outcome: - `C1`: `#1 AI content tool worldwide` — Status: `uncertain` - Evidence: multiple tools claim leadership using different metrics; no consistent independent ranking. - Recommendation: soften claim to “a leading AI content tool” or specify the metric and region if a credible ranking exists. - `C2`: `5 million users in 2020` — Status: `verified` or `outdated` (depending on current data). - Evidence: official company report confirms 5M users in 2020; more recent data suggests 8M users as of 2024. - Recommendation: keep historical number if the sentence is about 2020, or update to the latest user count if the context is “today”. The final answer should make these reasoning steps clear, then offer a corrected sentence such as: > As of 2024, our platform is widely recognized as a leading AI content tool, with over 8 million users worldwide.

path: evals/evals.json
content: {
  "skill_name": "geo-fact-checker",
  "evals": [
    {
      "id": 1,
      "prompt": "You are given a draft blog post about AI content tools aimed at marketing teams.\n\nPlease fact-check all important quantitative and comparative claims, focusing on user counts, years, and rankings. Then produce a structured report and suggested corrections.\n\nDraft content:\n\n\"In 2019, our platform became the #1 AI writing assistant worldwide, used by more than 2 million marketers. Today in 2020, we already help over 5 million users across 120 countries. According to independent analysts, we are the fastest-growing AI content platform in the world.\"\n\nAssume the user wants the content to be accurate and reliable for AI citation as of the current year.",
      "expected_output": "A Markdown report that (1) lists extracted claims with IDs and types, (2) labels each claim's verification status, (3) summarizes evidence and sources, and (4) proposes corrected or more cautious wording for each claim where needed.",
      "files": []
    },
    {
      "id": 2,
      "prompt": "You are given a product comparison page draft for three CRM tools.\n\nPlease perform focused fact-checking on numbers, rankings, and competitor information, and then suggest corrections that maintain a neutral, evidence-based tone suitable for AI citation.\n\nDraft content:\n\n\"Tool A is the largest CRM in the world with over 200,000 enterprise customers and 90% market share in North America. Tool B is mainly used by startups and has only 5,000 customers. Tool C launched in 2021 and is already the #2 CRM platform in Europe by revenue.\"\n\nTreat the content as a live page that should reflect the most recent trustworthy data available.",
      "expected_output": "A structured fact-checking summary that identifies each claim, classifies its type (e.g., ranking, numeric-statistic, competitor-info), evaluates its correctness, and proposes revised wording that avoids unsupported superlatives or outdated figures.",
      "files": []
    },
    {
      "id": 3,
      "prompt": "You are given a landing page hero and key bullets for a SaaS analytics tool.\n\nYour task is to fact-check the most important trust-related claims and rewrite the section in a way that is both factually robust and still compelling for conversion, suitable for GEO and AI citations.\n\nDraft content:\n\n\"Trusted by over 50,000 brands, including 9 of the top 10 global e-commerce companies. Our platform processes more than 10 billion events per day and has delivered 300% average ROI for customers since 2018. Ranked as the #1 analytics platform by every major industry report.\"\n\nFocus on identifying which claims are likely unverifiable or overly broad and how to phrase them more responsibly.",
      "expected_output": "An answer that first presents a claim table with statuses (verified, partially_verified, outdated, contradicted, uncertain), then offers an improved hero + bullet section that keeps strong social proof while aligning with the available evidence.",
      "files": []
    }
  ]
}



path: references/claim-types.md
content: # Claim Types for GEO Fact Checking

This reference defines the main claim types used by the `geo-fact-checker` skill and gives guidance on how to handle each type during verification.

Use these definitions when classifying claims in your reports or when you need more nuance than the brief explanations in SKILL.md.

---

## 1. numeric-statistic

**Definition:** Claims that involve concrete numbers or quantities that can, in principle, be measured or counted.

**Examples:**

- “We serve over 5 million users worldwide.”
- “Our customers see an average 30% increase in conversion rates.”
- “The platform processes 10 billion events per day.”

**Handling tips:**

- Identify:
  - Metric (what is being counted).
  - Unit (%, USD, number of users, etc.).
  - Time frame (as of which year or period).
- Verify against:
  - Official reports and statistics.
  - Recent, clearly dated third-party sources.
- Mark as:
  - `verified` if it clearly matches evidence.
  - `outdated` if more recent numbers differ.
  - `uncertain` if ranges vary widely or data is sparse.

---

## 2. date

**Definition:** Claims that hinge on specific years or time periods.

**Examples:**

- “The product launched in 2021.”
- “In 2019, the company reached profitability.”
- “The regulation took effect on January 1, 2024.”

**Handling tips:**

- Check:
  - Official announcement dates.
  - Documentation or changelogs.
  - News coverage from reputable outlets.
- Be careful about:
  - Time zones and regional differences for exact days.
  - Ongoing events (e.g., “since 2022”).

---

## 3. ranking

**Definition:** Claims that assert relative position, comparisons, or superlatives.

**Examples:**

- “The #1 CRM in North America.”
- “Ranked top 3 in customer satisfaction.”
- “The fastest-growing analytics platform.”

**Handling tips:**

- Clarify:
  - Who created the ranking.
  - What metric and geography it covers.
  - Which time period it refers to.
- Prefer:
  - Evidence-based qualifiers (“ranked #1 by [source] in [year]”).
  - Softer language when evidence is limited (“a leading provider”, “among the top tools”).

---

## 4. competitor-info

**Definition:** Claims about competitors’ size, positioning, customer base, or performance.

**Examples:**

- “Tool B is mainly used by small startups.”
- “Competitor X has only 5,000 customers.”
- “Vendor Y focuses exclusively on enterprise clients.”

**Handling tips:**

- Cross-check:
  - Competitors’ own websites and positioning.
  - Third-party reports that describe their market segment.
- Avoid:
  - Unnecessary negative framing.
  - Unverifiable or highly speculative statements.

---

## 5. quote

**Definition:** Claims that attribute statements or findings to specific external sources.

**Examples:**

- “According to a 2023 Gartner report, …”
- “A recent study from [University] found that …”
- “As [Expert] wrote in [Publication], …”

**Handling tips:**

- Confirm:
  - The source actually exists and is credible.
  - The quote is faithful to the original wording and context.
  - The year and publication details match.
- Summarize:
  - The core idea of the cited work in neutral, accurate language.

---

## 6. general-fact

**Definition:** Broader factual statements that are not primarily about specific numbers, dates, or rankings.

**Examples:**

- “Email remains a dominant marketing channel for e-commerce brands.”
- “Most modern CRM tools offer API access.”
- “Cloud adoption has grown rapidly over the past decade.”

**Handling tips:**

- Check:
  - Whether the statement is still broadly true given recent trends.
  - Whether reputable sources express similar views.
- Prefer:
  - Balanced phrasing that acknowledges nuance where needed.
  - Avoiding absolute terms like “all” or “always” unless very clearly supported.

---

## Using claim types in reports

When writing fact-checking outputs:

- Always assign a claim type to each non-trivial claim.
- Use the type to:
  - Guide which sources to prioritize.
  - Decide how cautious your phrasing should be.
  - Explain to the user why a claim was labeled `verified`, `outdated`, `contradicted`, etc.

Consistent use of these claim types helps make reports easier to scan, compare, and reuse for GEO-optimized, AI-citable content.



path: references/fact-checking-patterns.md
content: # Fact-Checking Patterns for GEO Content

This reference file describes reusable patterns and checklists for using the `geo-fact-checker` skill effectively, especially for AI-citable content and GEO (Generative Engine Optimization).

Use these patterns when the main SKILL.md instructions are not specific enough for the task at hand.

---

## 1. Numeric statistics pattern

**Goal:** Safely handle numbers that affect trust (user counts, revenue, growth, ROI, etc.).

### Checklist

- Identify:
  - What is being measured? (users, customers, revenue, traffic, etc.).
  - Which unit? (USD, %, monthly active users, annual revenue, etc.).
  - Time frame? (as of 2020, Q4 2025, last 12 months, etc.).
  - Scope? (global, US, EMEA, specific niche or industry).
- Search for:
  - Official company reports, investor decks, or press releases.
  - Recent third-party reports from credible firms or research orgs.
  - Government or standards bodies for macro statistics.
- Compare:
  - Is the number within a reasonable range of reported values?
  - Are there known updates (e.g., “5M in 2020, 8M in 2024”)?

### Recommended phrasing tactics

- Add time qualifiers:
  - “As of 2024, …”
  - “Between 2021 and 2023, …”
- Avoid false precision:
  - Prefer “about 5 million” over “5,023,871” when not quoting a precise report.
- Clearly attribute to sources when appropriate:
  - “According to [source name], …”

---

## 2. Rankings and “#1” claims pattern

**Goal:** Prevent unsupported or misleading “#1” and “top X” statements.

### Checklist

- Clarify:
  - Ranking according to whom? (which report, which dataset).
  - Ranking for what metric? (revenue, users, traffic, satisfaction).
  - Ranking where? (global vs. regional).
  - Time period? (which year or report cycle).
- Search for:
  - Widely cited rankings from industry analysts or research firms.
  - Multiple independent sources to confirm consistency.

### Safer alternative phrasing

- When support is weak or mixed:
  - “a leading platform for …”
  - “one of the most widely used tools for …”
  - “frequently ranked among the top [N] in …”
- When you have strong, specific evidence:
  - “Ranked #1 by [report name] in [year] for [metric] in [region].”

Avoid absolute, context-free claims like “the #1 tool in the world” unless the evidence is exceptionally clear and unambiguous (this is rare).

---

## 3. Competitor and comparison pattern

**Goal:** Keep competitor descriptions fair, accurate, and defensible.

### Checklist

- For each competitor claim:
  - Identify exactly what is being asserted (size, market segment, positioning).
  - Search for the competitor’s own description and third-party views.
  - Check that the claim does not rely on outdated or cherry-picked data.
- Pay special attention to:
  - Extreme statements (“only”, “always”, “never”).
  - Statements that may be perceived as misleading or defamatory.

### Safer comparative language

- Prefer:
  - “Popular among …”
  - “Commonly used by …”
  - “Positions itself as …”
- For direct comparisons:
  - “Compared with [competitor], [product] focuses more on …”
  - “In [specific report], [product] received higher scores than [competitor] for [metric].”

---

## 4. Time and recency pattern

**Goal:** Make it clear when a claim is anchored in time and avoid silent drift as years pass.

### Checklist

- Identify all date-sensitive claims:
  - User counts, revenue, market share.
  - Product launch dates.
  - Regulatory or standard changes.
- For each date-sensitive claim:
  - Confirm whether the value is still accurate today.
  - If not, decide whether to:
    - Preserve it as a historical statement, or
    - Update to a more recent value.

### Phrasing guidelines

- Historical:
  - “In 2019, the company reached …”
  - “Between 2018 and 2020, …”
- Current:
  - “As of 2026, the platform serves …”
  - “Recent reports from [year] indicate …”

When the user does not specify, prefer current data for “today” claims and explicit years for historical context.

---

## 5. Source evaluation pattern

**Goal:** Prioritize high-quality sources and be transparent about limitations.

### Preferred source types

- Official:
  - Company sites, investor relations pages, official blogs.
  - Government data portals.
  - Recognized standards organizations.
- Reputable third parties:
  - Known market research firms.
  - Major news outlets with fact-checking processes.

### Watch out for

- Scraped content farms with weak editorial standards.
- Undated or poorly dated pages.
- Single, uncorroborated sources for controversial claims.

When in doubt, mark a claim as `uncertain` rather than fabricating certainty.

---

## 6. Risk and sensitivity pattern

**Goal:** Handle sensitive domains with extra care.

Particularly cautious domains:

- Health and medicine.
- Finance and investment advice.
- Legal or regulatory guidance.
- Safety-critical technologies.

In these domains:

- Prefer conservative phrasing:
  - “may help”, “is associated with”, “is often used for”.
- Encourage consultation of primary experts or official guidelines.
- Clearly mark limitations of your verification and knowledge.

---

## 7. GEO and AI citation alignment

**Goal:** Make fact-checked content as easy as possible for AI systems to understand and reuse accurately.

Guidelines:

- Use clear, explicit, and self-contained sentences for key facts.
- Attach time markers (`as of [year]`) to numbers that may change.
- Avoid mixing multiple claims into a single long sentence; separate them.
- Prefer stable concepts and reputable entities in your evidence summaries.

By following these patterns, you increase the likelihood that AI systems will:

- Correctly interpret the scope and reliability of your claims.
- Reuse your content without distorting or overstating its conclusions.
- Cite your pages as trustworthy references for factual questions.



path: scripts/claim_extractor.py
content: """
Claim extraction helper for the geo-fact-checker skill.

This module provides simple utilities to extract and represent factual claims
from a block of text. It is intentionally lightweight so it can be adapted
or extended by higher-level agents as needed.

The skill using this script is responsible for deciding which claims to
prioritize for verification, how to search for evidence, and how to apply
corrections in the user's content.
"""

from dataclasses import dataclass
from enum import Enum
from typing import List
import re


class ClaimType(str, Enum):
    NUMERIC_STATISTIC = "numeric-statistic"
    DATE = "date"
    RANKING = "ranking"
    COMPETITOR_INFO = "competitor-info"
    QUOTE = "quote"
    GENERAL_FACT = "general-fact"


@dataclass
class Claim:
    id: str
    text: str
    claim_type: ClaimType


NUMERIC_PATTERN = re.compile(r"\b\d[\d,]*(?:\.\d+)?\b")
DATE_PATTERN = re.compile(r"\b(19|20)\d{2}\b")
RANKING_PATTERN = re.compile(r"\b(#?\d+|top\s+\d+|number\s+one|no\.\s*\d+)\b", re.IGNORECASE)


def guess_claim_type(sentence: str) -> ClaimType:
    """Heuristic classification of a sentence into a claim type."""
    lowered = sentence.lower()

    if RANKING_PATTERN.search(sentence):
        return ClaimType.RANKING
    if any(word in lowered for word in ["market share", "leader", "largest", "leading"]):
        return ClaimType.RANKING
    if DATE_PATTERN.search(sentence):
        return ClaimType.DATE
    if NUMERIC_PATTERN.search(sentence):
        return ClaimType.NUMERIC_STATISTIC
    if any(word in lowered for word in ["according to", "report", "study", "research"]):
        return ClaimType.QUOTE
    if any(word in lowered for word in ["competitor", "alternative", "vs ", "versus"]):
        return ClaimType.COMPETITOR_INFO
    return ClaimType.GENERAL_FACT


def split_into_sentences(text: str) -> List[str]:
    """
    Very simple sentence splitter based on punctuation.
    This does not handle all edge cases but is sufficient for small helper usage.
    """
    # Replace newlines with spaces to avoid fragmentation
    cleaned = re.sub(r"\s+", " ", text).strip()
    if not cleaned:
        return []

    # Split on ., ?, ! while keeping simple structure
    parts = re.split(r"([\.!?])", cleaned)
    sentences: List[str] = []
    buffer = ""
    for part in parts:
        if part in [".", "?", "!"]:
            buffer += part
            sentence = buffer.strip()
            if sentence:
                sentences.append(sentence)
            buffer = ""
        else:
            buffer += part
    if buffer.strip():
        sentences.append(buffer.strip())
    return sentences


def extract_candidate_claims(text: str, min_length: int = 20) -> List[Claim]:
    """
    Extract a list of candidate claims from a text block.

    This function is intentionally conservative and focuses on sentences
    that are likely to contain non-trivial factual content: numbers,
    dates, rankings, or explicit references to research and reports.
    """
    sentences = split_into_sentences(text)
    claims: List[Claim] = []

    for idx, sentence in enumerate(sentences, start=1):
        s = sentence.strip()
        if len(s) < min_length:
            continue

        # Only keep sentences that contain clear factual markers
        if not (
            NUMERIC_PATTERN.search(s)
            or DATE_PATTERN.search(s)
            or RANKING_PATTERN.search(s)
            or any(
                kw in s.lower()
                for kw in [
                    "according to",
                    "report",
                    "study",
                    "research",
                    "market share",
                    "leader",
                    "largest",
                    "top",
                ]
            )
        ):
            continue

        claim_type = guess_claim_type(s)
        claim_id = f"C{idx}"
        claims.append(Claim(id=claim_id, text=s, claim_type=claim_type))

    return claims


__all__ = [
    "ClaimType",
    "Claim",
    "extract_candidate_claims",
    "split_into_sentences",
    "guess_claim_type",
]



Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)