Q-Topic-Finetuning

Fine-tune topic modeling outputs into consolidated, theory-driven topic frameworks for academic manuscripts.

Folder Structure

q-topic-finetuning/
├── SKILL.md                                  # This file
├── scripts/
│   ├── classify_outliers.py                  # Outlier reclassification via Gemini
│   ├── generate_implementation_plan.py       # Full plan generation
│   └── update_excel_with_labels.py           # Excel column updates
└── references/
    ├── esports_ugc_example.md                # Worked example
    └── SP_OUTLIER_TEMPLATE.txt               # Outlier classification prompt template

Script Directory

Agent execution instructions:

Determine this SKILL.md file's directory path as SKILL_DIR.
Script path = ${SKILL_DIR}/scripts/<script-name>.
Reference path = ${SKILL_DIR}/references/<ref-name>.

Resource	Purpose
`scripts/classify_outliers.py`	Outlier reclassification via Gemini
`scripts/generate_implementation_plan.py`	Full plan generation
`scripts/update_excel_with_labels.py`	Excel column updates
`references/esports_ugc_example.md`	Worked example
`references/SP_OUTLIER_TEMPLATE.txt`	Outlier classification prompt template

When to Use

Converting raw topic model outputs (BERTopic, LDA, NMF) into manuscript-ready categories
Applying theoretical frameworks (legitimacy, stakeholder theory, etc.) to topic clusters
Consolidating 50+ topics into 20-50 theoretically meaningful groups
Preserving domain-specific distinctions (by entity, event, geography, time)
Creating reproducible Excel outputs with classification labels

Workflow Overview

Source Data (Topic Model Excel) 
    |
    v
1. Load & Analyze Topics --> identify overlaps, unassigned
    |
    v
2. Define Final Topic Structure --> FINAL_TOPICS dictionary
    |
    v
3. Apply Theoretical Framework --> classify each topic
    |
    v
4. Generate Implementation Plan (MD)
    |
    v
5. Update Source Data with Labels (Excel)

Core Principles

Preservation Rules (Customize per Domain)

Identify what should NEVER be merged based on theoretical importance:

Entity-specific: Different companies, teams, people
Event-specific: Different conferences, tournaments, time periods
Geography-specific: Different countries, regions
Stakeholder-specific: Different actor perspectives

Theoretical Framework (Template)

Replace with your relevant framework:

Type	Description	Example Topics
Category A	Definition	Topics fitting A
Category B	Definition	Topics fitting B
Category C	Definition	Topics fitting C
Cross-cutting	Spans multiple	Topics by entity/domain

Example: Legitimacy Framework (Suchman, 1995)

Cognitive: Institutional recognition, taken-for-granted status
Pragmatic: Direct stakeholder benefits, practical interests
Moral: Normative evaluation, values alignment

Multi-Category Topics

Some topics belong to multiple categories:

Track explicitly in assignments dictionary
Calculate overlap for reconciliation
Display as semicolon-separated: "Category A; Cross-cutting"

Required Inputs

Topic model output (Excel/CSV)
- Columns: Topic ID, Count, Name/Label, Keywords, Representative_Docs (optional)
Merge recommendations (optional)
- Sheets: MERGE_GROUPS, INDEPENDENT_TOPICS
Document data (for label updates)
- Contains individual documents with Topic ID column

Key Code Patterns

Pattern 1: Final Topic Definition

FINAL_TOPICS = {
    'A1': {
        'label': 'Descriptive Label for Topic',
        'theme': 'Category-Subcategory',  # e.g., 'Pragmatic-Fan'
        'sources': [8, 12, 45]  # Original topic IDs to merge
    },
    'A2': {
        'label': 'Another Topic Label',
        'theme': 'Category-Subcategory',
        'sources': [3, 17, 33]
    },
    # Topics can appear in multiple final topics for multi-category
}

Pattern 2: Assignment Mapping

assignments = {}
for code, data in FINAL_TOPICS.items():
    for tid in data['sources']:
        if tid not in assignments:
            assignments[tid] = []
        assignments[tid].append((code, data['theme']))

# Find multi-category topics
multi_cat = {tid: assigns for tid, assigns in assignments.items() 
             if len(assigns) > 1}

Pattern 3: Overlap Calculation

total_overlap = sum(
    topics[tid]['count'] * (len(assigns) - 1)
    for tid, assigns in assignments.items()
    if len(assigns) > 1
)

# Verification: non_outlier_docs + total_overlap = table1_total

Pattern 4: Excel Label Update

TOPIC_MAPPING = {
    0: [('A1', 'Category')],
    1: [('A2', 'Category')],
    4: [('B1', 'Category A'), ('C1', 'Cross-cutting')],  # Multi-category
    # ... all topic IDs
}

def get_themes(topic_id):
    if topic_id in TOPIC_MAPPING:
        themes = list(set([m[1] for m in TOPIC_MAPPING[topic_id]]))
        return '; '.join(themes)
    return 'Unknown'

df['Final_Topic_Code'] = df['Topic'].apply(get_final_codes)
df['Final_Topic_Label'] = df['Topic'].apply(get_final_labels)
df['Category_Theme'] = df['Topic'].apply(get_themes)

Handling Common Requests

User Request	Action
"Preserve X separately"	Add as independent topic code
"Merge these topics"	Combine source IDs into single code
"Exact counts please"	Replace ~ approximations with computed totals
"Integrate into tables"	Remove standalone sections, embed in category tables
"Count mismatch?"	Explain multi-category overlap, show reconciliation
"Keep original style"	Preserve existing template structure when updating

Script Templates

See ${SKILL_DIR}/scripts/ for reference implementations:

generate_implementation_plan.py - Full plan generation
update_excel_with_labels.py - Excel column updates

Adapt these scripts by:

Updating FINAL_TOPICS with your topic structure
Replacing FINAL_LABELS with your labels
Modifying theme categories to match your framework

Verification Checklist

All non-outlier topics assigned to at least one category
Multi-category topics explicitly tracked
Overlap reconciliation verified
Domain-specific topics preserved separately
Category subtotals match grand total
Output file has new classification columns

Outlier Classification (Foundation Model)

For datasets with significant noise or unclustered documents (Topic = -1), use the classify_outliers.py script to reclassify them using a Gemini foundation model.

Workflow

Prepare Prompt: Create a system prompt listing all valid finalized topics + descriptions. See ${SKILL_DIR}/references/SP_OUTLIER_TEMPLATE.txt.
Configure Script: Update valid_topics and file paths in ${SKILL_DIR}/scripts/classify_outliers.py.

Run Classification:

# Default uses GEMINI_MODEL env var or standard Flash model
python "${SKILL_DIR}/scripts/classify_outliers.py"

# Or specify a model version
python "${SKILL_DIR}/scripts/classify_outliers.py" --model gemini-3-flash-preview

Uses Google Gemini Foundation Models (supports Flash, Pro, etc.)
Auto-retries invalid outputs
Updates Final_Topic_Label, classification_confidence, and key_phrases columns

When to Use

You have >10% outlier documents (Topic -1)
You have a stable final topic list (from Table 1)
You want to "clean up" the dataset for final analysis