ontology-design

name	ontology-design
description	Design domain ontology for knowledge graph construction in Graph RAG projects. Use when user says "设计本体", "design ontology", "ontology", or after idea validation is complete.
argument-hint	["idea-reference-or-domain-description"]
allowed-tools	Bash(*), Read, Write, Grep, Glob, WebSearch, WebFetch, Agent

Skill-4: Ontology Design

Design a domain ontology for: $ARGUMENTS

Overview

This skill takes the validated idea from output/ideas/idea01.md and produces a complete domain ontology that defines the conceptual structure of the knowledge graph. The ontology determines what entities exist, how they relate, what data is needed, and how the graph will serve Graph RAG retrieval.

Outputs:

• output/ontology/ontology03.md — full ontology specification
• output/ontology/data_requirements03.md — concrete data acquisition plan mapped to ontology

Both are prerequisites for skill-3 (/research-planning) and SubAgent1/SubAgent2.

References

This skill includes reference materials in the references/ directory. Claude MUST read these before designing:

Reference	File	Purpose
Ontology Development Methodologies	references/methodologies_for_ontology_design.md	Formal methodologies (Methontology, NeOn, etc.) for systematic ontology engineering
Typhoon Disaster Case Study	references/typhoon_ontology_case_study.md	Complete worked example: 12 entity types, 13 relationships, chain rules, taxonomy design, dual-source data mapping

Before starting Phase 2, read all references to ground the design in established methods.

Adding Your Own References

Users can enhance ontology design quality by adding domain-specific references:

1. Place files in .claude/skills/ontology-design/references/
2. Supported formats: .md, .txt, .json, .csv
3. Recommended types:
   • Existing domain ontology schemas (OWL/RDF exports as text)
   • Prior ontology designs for the target domain
   • Domain glossaries or terminology dictionaries
   • Data field dictionaries from target data sources
   • Example knowledge graph outputs (node/edge samples)
4. After adding, update the reference table above in this SKILL.md

Workflow

Phase 1: Idea Intake & Domain Scoping

1. Read output/ideas/idea01.md to understand:

   • Target domain (risk/disaster/threat/event type)
   • Research question and innovation points
   • Proposed data sources
   • Graph RAG strategy outlined in the idea

2. Define ontology scope by answering:

   • What real-world domain does this ontology cover?
   • What questions must the Graph RAG system answer? (competency questions)
   • What data sources will populate the graph?
   • What level of granularity is needed?

3. Generate Competency Questions — 10-15 questions the ontology must answer. These drive the entire design. Example format:

   • CQ1: "What are the primary hazards caused by [event type]?"
   • CQ2: "What response measures exist for [hazard category]?"
   • CQ3: "Which organizations are responsible for [infrastructure type]?"

   Present to user for review. Wait for approval before proceeding.

Phase 2: Read References & Survey Existing Ontologies

1. Read all reference files in references/ directory
2. Extract applicable patterns:
   • Which ontology development methodology fits? (from methodologies reference)
   • What structural patterns can be reused? (from case study reference)
   • Entity layering, taxonomy anchoring, chain rules, provenance tracking
3. Search for existing domain ontologies using WebSearch:
   • "[domain] ontology" + OWL/RDF
   • "[domain] knowledge graph schema"
   • Domain standards (DOLCE, SSN, SWEET, etc.)
4. Document findings: what exists, what to reuse, what needs custom design

Phase 3: Entity Design

Design entities in a layered architecture:

Layer 1: Domain Event Entities

Core entities representing events, hazards, or problems.

• Define entity name, description, required + optional properties
• Each entity must have a clear real-world meaning

Layer 2: Taxonomy/Classification Entities

Fixed-category entities as stable classification anchors.

• Define predefined categories with clear scope
• Bridge between event data and solution data

Layer 3: Solution/Response Entities

Entities representing solutions, measures, methods from literature.

• MUST include provenance properties (paper DOI, source, date)
• Populated from academic paper data

Layer 4: Context Entities (if needed)

Supporting entities: Location, Organization, Sector, Time Period.

Each entity must be classified as Core or Extended:

Tier	Meaning	Rule
Core	Essential for the minimum viable KG and paper	Must have data available. If data cannot be found, the ontology has a problem.
Extended	Enriches the KG but not required	Nice-to-have. If data is unavailable, silently dropped — no impact on paper quality.

Guideline: Core should have 3-5 entity types and 5-8 relationships. This is enough for a solid Q1 paper. Extended can add more depth if data supports it.

For each entity specify:

Field	Description
Entity Name	PascalCase, clear domain term
Description	What this entity represents
Category	Event / Taxonomy / Solution / Context
Tier	Core / Extended
Required Properties	Properties every instance must have
Optional Properties	Properties that may or may not exist
Data Source	Where instances come from (news/paper/open data)
Expected Volume	Approximate count

Phase 4: Relationship Design

Define all relationships (also classified as Core/Extended):

Field	Description
Relationship Name	UPPER_SNAKE_CASE verb phrase
Source → Target	Direction
Description	Semantic meaning
Tier	Core / Extended
Cardinality	1:1, 1:N, N:M
Required/Optional	Must every source have this?

Relationship categories to consider:

• Causal: A causes/triggers B
• Classification: Entity belongs to taxonomy
• Spatial: Entity affects/located at Location
• Temporal: Entity before/after/during Entity
• Governance: Entity managed by Organization
• Provenance: Entity documented in / extracted from Source
• Mitigation: Solution mitigates Problem (core Graph RAG linkage)

Phase 5: Constraint Rules & Validation

Define integrity rules:

1. Chain rules: Which entities MUST have specific incoming/outgoing relationships?
2. Uniqueness constraints: Which properties must be unique?
3. Mandatory properties: Which properties can never be null?
4. Taxonomy constraints: Fixed or extensible categories?
5. Orphan prevention: Rules to prevent disconnected entities

Phase 6: Data Feasibility Probe

Before finalizing the ontology, verify that data actually exists for each entity and relationship.

This is a quick, lightweight check — NOT full data collection (that's SubAgent1's job). The goal is to catch infeasible entities early.

6.1 Probe Method

For each entity type (especially Core), run 2-3 WebSearch queries to check:

• Can this entity be extracted from publicly available news/papers/open data?
• Are there enough sources to meet the expected volume?
• Is the data in a format that LLM extraction can handle?

6.2 Feasibility Scoring

Score	Meaning	Action
HIGH	Multiple data sources found, clear extraction path	Keep as-is
MEDIUM	Some data available, may need creative sourcing	Keep, but note risk in data_requirements03.md
LOW	Very little or no data found via quick search	If Core → simplify or merge with another entity. If Extended → mark as optional, may be dropped.

6.3 Probe Report

Present to user:

## Data Feasibility Probe Results

| Entity | Tier | Feasibility | Sources Found | Notes |
|--------|------|-------------|--------------|-------|
| Hazard | Core | HIGH | Reuters, BBC, EM-DAT | Abundant news coverage |
| SecondaryHazard | Core | MEDIUM | Limited news, some papers | May merge with Hazard if data insufficient |
| Organization | Extended | LOW | Only in official reports | Mark optional, drop if no data |
| ... | ... | ... | ... | ... |

6.4 Simplification Actions

If Core entities score LOW:

1. Merge: Combine with a related Core entity (e.g., SecondaryHazard → Hazard with a is_secondary property)
2. Demote: Move from Core to Extended
3. Redesign: Change the entity to match available data (e.g., "Infrastructure" is too specific → "AffectedTarget" is more general)

If Extended entities score LOW:

• Simply mark as optional in ontology03.md. SubAgent1 will skip them if no data found.

After probe adjustments, re-check Graph RAG alignment (Phase 7) to ensure Core still answers all competency questions.

Phase 7: Data Mapping Overview

Map each entity to its data source type:

Entity	Source Type	Source Category	Extraction Method
[event entity]	News / Blog / Open data	Web crawling	LLM extraction
[solution entity]	Academic papers	Scholar/arXiv	Structured extraction

This is a high-level mapping. The detailed acquisition plan comes in Phase 9.

Phase 8: Graph RAG Alignment Check

Verify the ontology supports Graph RAG (re-check after probe adjustments):

1. Retrieval paths: Can the graph answer CQs via traversal?
2. Subgraph extraction: Are meaningful subgraphs extractable for LLM context?
3. Query mapping: Can natural language questions map to graph patterns?
4. Context richness: Do subgraphs provide enough context for generation?

If gaps found, iterate entity/relationship design.

Phase 9: Present to User & Refine

Present the complete ontology (with Core/Extended tiers and feasibility results):

• Entity summary table
• Relationship diagram (Mermaid)
• Constraint rules
• Data source mapping
• Graph RAG alignment assessment

Wait for user feedback. Iterate until approved.

Phase 10: Output — Write ontology03.md and data_requirements03.md

After user approval, write two files:

File 1: output/ontology/ontology03.md

# Ontology Design: [Title]

**Generated**: [date]
**Domain**: [domain]
**Based on**: idea01.md
**Methodology**: [methodology followed]

## 1. Scope & Competency Questions
### 1.1 Ontology Scope
[Coverage and boundaries]
### 1.2 Competency Questions
| # | Question | Answered By (entity/relationship pattern) |

## 2. Entity Design
### 2.1 Entity Summary
| Entity | Tier | Category | Description | Properties | Source Type | Feasibility | Volume |
### 2.2 Detailed Entity Definitions
[Full spec per entity with all properties]

## 3. Taxonomy Design
### 3.1 [Taxonomy Name 1]
| # | Category | Description | Examples |
### 3.2 [Taxonomy Name 2]

## 4. Relationship Design
### 4.1 Relationship Summary
| Relationship | Source → Target | Tier | Type | Cardinality |
### 4.2 Relationship Diagram
[Mermaid diagram]

## 5. Constraint Rules
| Rule | Entity | Constraint | Enforcement |

## 6. Graph RAG Alignment
### 6.1 Retrieval Path Analysis
### 6.2 Subgraph Extraction Strategy
### 6.3 Query Mapping Examples
[3-5 example queries with corresponding graph traversal patterns]

## 7. Design Rationale
[Why these choices, methodology followed, references consulted]

## 8. Design Log
| Date | Decision | Rationale |

File 2: output/ontology/data_requirements03.md

This is a concrete data acquisition plan specifying exactly what data to collect, from where, in what format, and how it maps to the ontology. All sources must be publicly accessible: news, blogs, open data, academic papers.

# Data Requirements Document

**Generated**: [date]
**Based on**: ontology03.md
**Purpose**: Guide SubAgent1 (data collection) with exact specifications

## 1. Data Source Overview

| # | Source Name | Type | URL/Platform | Target Entities | Format | Est. Volume |
|---|------------|------|-------------|-----------------|--------|-------------|
| 1 | [e.g., Reuters Disaster News] | News | [URL] | [Event entities] | HTML→text | ~200 articles |
| 2 | [e.g., Semantic Scholar] | Paper | api.semanticscholar.org | [Solution entities] | JSON/PDF | ~50 papers |
| 3 | [e.g., EM-DAT] | Open Data | emdat.be | [Event/Impact entities] | CSV | ~500 records |
| ... | ... | ... | ... | ... | ... | ... |

## 2. News & Blog Data Specification

For each news/blog source:

### 2.1 Source: [Source Name]
- **URL / Search Strategy**: [how to find relevant articles]
- **Target Period**: [date range]
- **Language**: [language]
- **Collection Method**: WebSearch / Apify / RSS
- **Target Entities to Extract**:

| Entity | Properties to Extract | Extraction Method |
|--------|----------------------|-------------------|
| [e.g., Hazard] | name, hazard_type, intensity, location | LLM extraction from article text |
| [e.g., Impact] | impact_type, affected_target, severity | LLM extraction from article text |

- **Expected Fields per Record**:

| Field | Type | Required | Example |
|-------|------|----------|---------|
| article_title | string | Yes | "Hurricane X causes flooding in..." |
| article_url | string | Yes | https://... |
| publish_date | date | Yes | 2024-01-15 |
| article_text | string | Yes | [full text] |
| source_name | string | Yes | Reuters |

- **Output Format**: CSV with columns above
- **Output Path**: `output/data/news/[source_name].csv`

### 2.2 Source: [Next Source]
[Same structure]

## 3. Academic Paper Data Specification

For each paper source:

### 3.1 Source: [e.g., Semantic Scholar API]
- **Search Queries**: [exact query strings to use]
- **Filters**: year ≥ [year], fields of study, venue
- **Collection Method**: API call / WebSearch + WebFetch
- **Target Volume**: [N] papers
- **Target Entities to Extract**:

| Entity | Properties to Extract | Extraction Method |
|--------|----------------------|-------------------|
| [e.g., ResponseMeasure] | name, measure_text, category | LLM extraction from abstract/full text |

- **Expected Fields per Paper Record**:

| Field | Type | Required | Example |
|-------|------|----------|---------|
| paper_title | string | Yes | "A framework for..." |
| doi | string | Yes | 10.1016/j... |
| authors | string | Yes | "Zhang et al." |
| journal_name | string | Yes | "Advanced Engineering Informatics" |
| publication_date | date | Yes | 2023-06-01 |
| abstract | string | Yes | [abstract text] |
| extracted_measures | list | Yes | [{name, text, category}] |

- **Output Format**: CSV with columns above
- **Output Path**: `output/data/papers/[source_name].csv`

### 3.2 Source: [Next Source]
[Same structure]

## 4. Open Data Specification

For each open dataset:

### 4.1 Source: [e.g., EM-DAT International Disaster Database]
- **URL**: [direct download or API endpoint]
- **Access Method**: Direct download / API / WebFetch
- **Target Entities to Extract**:

| Entity | Properties to Extract | Field Mapping |
|--------|----------------------|---------------|
| [e.g., Typhoon] | name, date, grade | column_A → name, column_B → date |

- **Raw Data Fields Available**:

| Field | Type | Maps to Entity.Property |
|-------|------|------------------------|
| [raw field name] | [type] | [Entity.property] |

- **Preprocessing Required**: [cleaning steps, filtering, normalization]
- **Output Format**: CSV
- **Output Path**: `output/data/opendata/[source_name].csv`

## 5. Entity-to-Source Traceability Matrix

| Entity | News Sources | Paper Sources | Open Data Sources | Primary Source |
|--------|-------------|---------------|-------------------|----------------|
| [Entity1] | ✓ Source A | | ✓ Source C | News |
| [Entity2] | | ✓ Source B | | Papers |
| ... | ... | ... | ... | ... |

## 6. Data Collection Priority

| Priority | Data | Reason | Blocking |
|----------|------|--------|----------|
| P0 (must have) | [data] | [required for core entities] | Blocks KG construction |
| P1 (important) | [data] | [enriches graph] | Blocks full evaluation |
| P2 (nice to have) | [data] | [adds context] | Non-blocking |

## 7. Data Quality Requirements

| Requirement | Standard |
|-------------|----------|
| Deduplication | No duplicate articles/papers by URL/DOI |
| Completeness | All required fields must be non-null |
| Recency | News within [N] years, papers within [N] years |
| Language | [Languages accepted] |
| Encoding | UTF-8 |

Key Rules

1. Read references first: Always read all files in references/ before designing.
2. Competency questions drive design: Every entity and relationship must serve at least one CQ.
3. No orphan entities: Every entity type must connect to at least one other.
4. Provenance is mandatory: Solution entities must carry source attribution.
5. Taxonomy as anchor: Use fixed taxonomy nodes to bridge event and solution data.
6. User approval at two checkpoints: After CQs (Phase 1) and after full design (Phase 8).
7. Data sources limited to: news, blogs, open data, academic papers — no proprietary or paywalled sources.
8. Data requirements must be concrete: Specific URLs, field names, formats, volumes — not vague descriptions.

Composing with Other Skills

/idea-checking            → idea01.md
/research-planning        → plan04.md (high-level, includes Phase O for ontology)
/ontology-design          → Phase O in plan04.md → ontology03.md + data_requirements03.md  ← YOU ARE HERE
                            → triggers plan04.md refinement (task O.7: Phase A gets data specs)
SubAgent1                 → executes Phase A (data collection per data_requirements03.md)
SubAgent2                 → executes Phase B-D (implements ontology03.md as KG schema)

After completing: Update plan04.md tasks O.1-O.6 to [✓], which unblocks Phase A tasks.