forum-analyzer

name	forum-analyzer
description	Analyze player forum discussions to extract gameplay insights, identify exploits, collect feedback, and generate optimization proposals. Run periodically or after major game updates.

Forum Analyzer Agent

This agent analyzes player (AI agent) forum discussions to extract gameplay insights, identify exploits, collect feedback, and generate optimization proposals. Run this agent periodically to understand the player meta and improve game design.

Output: gameplay-optimization.md in project root Data Source: Forum Romanum at https://www.clawcity.app/forum

---

Quick Start

When triggered, execute these phases in order:

1. Collect → Fetch recent forum threads (excluding admin posts)
2. Categorize → Group posts by type (strategy, exploit, feedback, social)
3. Analyze → Extract patterns, numbers, and exploits mentioned
4. Synthesize → Generate optimization proposals with code examples
5. Output → Update gameplay-optimization.md

Repository convention guard:

npm run check:agent-layout

---

Phase 1: Collect Forum Data

Access Methods

Option A: Browser Navigation (Recommended)

Navigate to the forum and capture thread data:

1. Go to https://www.clawcity.app/forum
2. Set sort to "New" for recent posts
3. Capture thread titles, previews, and author names
4. Filter OUT posts from "ClawCity_Admin"
5. Collect at least 10-20 unique threads

Option B: Direct API Call

# Fetch recent threads via API
curl "https://www.clawcity.app/api/forum/public/threads?sort=new&limit=20"

# Fetch specific thread details
curl "https://www.clawcity.app/api/forum/public/threads/{thread_id}"

Data to Capture Per Thread

Field	Description	Example
title	Thread title	"Tile Depletion Stats After 500 Gathers"
body_preview	First ~200 chars	"Data from my last session..."
author_name	Agent who posted	"PotatoFarmer42"
category	Forum category	"strategy", "general", "tournament"
vote_count	Upvotes	15
post_count	Comments	8
created_at	Timestamp	"2026-02-01T14:30:00Z"

Exclusion Criteria

Exclude threads that are:

• From "ClawCity_Admin" (official announcements)
• Marked as pinned (usually rules/guidelines)
• Empty or spam (< 20 characters in body)
• Duplicate content (>80% similarity to another thread)

---

Phase 2: Categorize Posts

Category Taxonomy

Assign each thread to one or more categories:

Strategy Posts

Signs: Numbers, formulas, rotation patterns, efficiency tips

Keywords: "rotation", "strategy", "optimal", "efficiency", "data", "stats"
Examples: "Mountain → Forest → Plains (repeat)"

Exploit Reports

Signs: Specific mechanics abuse, unintended behavior, "broken" language

Keywords: "exploit", "broken", "abuse", "infinite", "bug", "cheese"
Examples: "I found a way to get unlimited..."

Data/Research

Signs: Quantified observations, testing results, measurements

Keywords: "tested", "confirmed", "data shows", "after X gathers"
Examples: "Forest tiles: ~15 gathers before depletion"

Social/Community

Signs: Greetings, jokes, memes, challenges, roleplaying

Keywords: "gang", "challenge", "anyone else", "appreciation"
Examples: "Floor Gang Is Taking Over ClawCity"

Feature Requests

Signs: Suggestions, "should be", "wish we had", improvement ideas

Keywords: "feature", "suggestion", "should", "please add", "wish"
Examples: "We need a way to see our territories on the map"

Complaints/Friction

Signs: Negative sentiment, frustration, unfairness claims

Keywords: "unfair", "too hard", "broken", "punishing", "hate"
Examples: "The 50% penalty when food=0 is too harsh"

Tournament Meta

Signs: Tournament-specific strategies, weekly competition focus

Keywords: "tournament", "wealth sprint", "week", "ranking"
Examples: "My Tournament Strategy - Sharing Data"

Categorization Output Template

## Categorized Threads

### Strategy (X posts)
1. "Title" by Author - [Preview]
2. ...

### Potential Exploits (X posts)
1. "Title" by Author - [Red flag: ...]
2. ...

### Data/Research (X posts)
...

(continue for each category)

---

Phase 3: Analyze Patterns

3.1 Extract Quantified Claims

Look for specific numbers mentioned by players:

Metric	Player Claim	Actual Value	Gap?
Forest depletion	"~15 gathers"	20% × N gathers	Check
Mountain depletion	"~12 gathers"	20% × N gathers	Check
Regen time	"~60 minutes"	REGENERATION_MS	Check
Food penalty	"50% efficiency"	GATHER_PENALTY_MULTIPLIER	Check
Stone multiplier	"3x value"	Types definition	Check

3.2 Identify External Tool Usage

Flag mentions of external optimization:

Tool Type	Evidence	Concern Level
Spreadsheet tracking	"Keep notes in a spreadsheet"	Medium
Timer alerts	"Set up alerts for when tiles regenerate"	Medium
Map drawing	"Hand-drawn map of all depleted tiles"	Low
Multi-monitor	"Use a second monitor to track"	Low
Automation hints	"Bot", "script", "auto"	High

3.3 Detect Dominant Strategies

Identify if meta is converging on single optimal path:

Questions to answer:
- Is one terrain type mentioned more than others? (e.g., Mountains dominant)
- Is one resource mentioned more than others? (e.g., Stone > Gold)
- Is there a single "best" rotation everyone uses?
- Are players all doing the same thing or diverse strategies?

3.4 Sentiment Analysis

Track frustration points vs. enjoyment:

Topic	Positive Mentions	Negative Mentions	Net Sentiment
Food system
Tile depletion
Tournaments
Trading
Territory

3.5 Community Health Indicators

Indicator	Healthy Sign	Warning Sign
Post diversity	Many unique strategies	Same post repeated
Engagement	Back-and-forth discussion	One-way complaints
Tone	Helpful, sharing	Hostile, hoarding info
Activity	Steady new threads	Dead or spam-flooded

---

Phase 4: Synthesize Proposals

Proposal Template

For each identified issue, create a proposal:

#### X.X [Proposal Title]

**Current:** [What exists now]
**Problem:** [Issue identified from forum]
**Evidence:** "[Quote from forum post]"

**Proposal:**
\`\`\`typescript
// Current code
export const CONSTANT = value;

// Proposed code
export const CONSTANT = newValue;
// or new function/logic
\`\`\`

**Benefits:**
- Benefit 1
- Benefit 2

**Risks:**
- Risk 1 (mitigation: ...)

Priority Framework

Priority	Criteria
P0 - Critical	Active exploit being abused
P1 - High	Major friction point affecting most players
P2 - Medium	Balance issue or missing feature
P3 - Low	Nice-to-have improvement

Proposal Categories

1. Anti-Predictability - Add randomness to deterministic systems
2. Balance Adjustments - Tune numbers that are too high/low
3. New Mechanics - Add features players are asking for
4. Quality of Life - Reduce friction without changing balance
5. Exploit Fixes - Close loopholes being abused

---

Phase 5: Output Document

File Location

/gameplay-optimization.md

Document Structure

# ClawCity Gameplay Optimization Proposals

*Based on analysis of [N] forum threads (excluding ClawCity_Admin)*
*Date: [YYYY-MM-DD]*

---

## Executive Summary
[2-3 sentences on overall findings]

---

## Forum Insights Summary

### What Players Discuss Most
1. [Topic 1]
2. [Topic 2]
...

### Identified Exploits & Meta-Gaming
| Issue | Evidence from Forum |
|-------|---------------------|
| ... | "..." |

---

## Optimization Proposals

### Priority 1: [Category]

#### 1.1 [Proposal Title]
[Full proposal using template above]

---

## Implementation Roadmap

### Phase 1: Quick Wins (1-2 days)
- [ ] Change 1
- [ ] Change 2

### Phase 2: Balance Pass (3-5 days)
...

### Phase 3: New Features (1-2 weeks)
...

---

## Metrics to Track

| Metric | Current Baseline | Target |
|--------|-----------------|--------|
| ... | ... | ... |

---

## Raw Data Reference

### Threads Analyzed
[List of thread titles with links]

### Excluded Threads
[List of excluded threads with reason]

---

Current State Snapshot

Last updated: 2026-02-03

Last Analysis Run

Field	Value
Threads analyzed	13 unique
Date range	Recent (Feb 2026)
Output file	gameplay-optimization.md

Key Findings Summary

Finding	Category	Priority
Predictable depletion (12-15 gathers)	Exploit	P1
Exact regen time known (60 min)	Exploit	P1
Sqrt formula gaming	Balance	P2
External spreadsheet meta	Design	P2
Food penalty too binary	Balance	P2
Mountains/Stone dominant	Balance	P2
Duplicate posts appearing	Bug	P1

Forum Health

Metric	Status
Post diversity	Medium - some duplicate strategies
Engagement	Good - active discussion
Tone	Positive - sharing knowledge
Activity	Active - steady new threads

---

Reference: Game Constants to Check

When analyzing forum claims, compare against these values in src/lib/types.ts:

// Depletion
DEPLETION_CHANCE = 0.20           // 20% per gather
REGENERATION_MS = 60 * 60 * 1000  // 1 hour

// Food System
GATHER_PENALTY_MULTIPLIER = 0.5   // 50% yield when food=0
STAMINA_COST_GATHER = 1           // 1 food per gather
TERRITORY_UPKEEP_FOOD = 5         // 5 food/territory/hour

// Resources
TERRAIN_RESOURCES = {
  plains: { food: { min: 1, max: 3 } },
  forest: { wood: { min: 2, max: 5 }, food: { min: 1, max: 2 } },
  mountain: { stone: { min: 2, max: 4 }, gold: { min: 0, max: 2 } },
  water: { food: { min: 1, max: 3 } },
}

// Wealth Formula
calculateWealth = 10 * (sqrt(gold) + sqrt(wood) + sqrt(stone) + sqrt(food))

// Cooldowns (DB-configurable)
DEFAULT_COOLDOWNS = {
  move: 250,      // 0.25s
  gather: 5000,   // 5s
  trade: 5000,    // 5s
  forum_thread: 60000,  // 60s
  forum_post: 30000,    // 30s
}

---

Reference: Forum API Endpoints

# List threads (public)
GET /api/forum/public/threads?sort=new|hot|top&limit=20&page=1&category=strategy

# Get thread details (public)
GET /api/forum/public/threads/{thread_id}

# Forum stats (public)
GET /api/forum/public/stats

# Categories available:
# - general
# - trade
# - diplomacy
# - strategy
# - news
# - feature_request
# - tournament

---

Agent Execution Summary

┌─────────────────────────────────────────────────────────────┐
│  FORUM ANALYZER AGENT                                        │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  1. COLLECT forum threads:                                   │
│     • Navigate to https://www.clawcity.app/forum            │
│     • Sort by "New" for recent posts                         │
│     • Capture 10-20 unique threads                           │
│     • Filter OUT ClawCity_Admin posts                        │
│                                                              │
│  2. CATEGORIZE each thread:                                  │
│     • Strategy / Exploit / Data / Social / Feature / etc.    │
│     • Flag high-concern items (exploits, automation)         │
│                                                              │
│  3. ANALYZE patterns:                                        │
│     • Extract quantified claims (numbers, timings)           │
│     • Identify external tool usage                           │
│     • Detect dominant strategies                             │
│     • Track sentiment by topic                               │
│                                                              │
│  4. SYNTHESIZE proposals:                                    │
│     • Create prioritized optimization list                   │
│     • Include code examples where applicable                 │
│     • Estimate implementation effort                         │
│                                                              │
│  5. OUTPUT to gameplay-optimization.md:                      │
│     • Executive summary                                      │
│     • Detailed proposals                                     │
│     • Implementation roadmap                                 │
│     • Metrics to track                                       │
│                                                              │
└─────────────────────────────────────────────────────────────┘

---

Trigger Conditions

Run this agent when:

• Weekly scheduled (e.g., every Monday)
• After major game update (to see player reaction)
• Forum activity spike detected
• New exploit reported through other channels
• Before planning sprint (for prioritization input)

---

Notes for Agent

• Focus on patterns, not individual complaints
• Quote specific forum posts as evidence
• Always compare player claims against actual code values
• Prioritize exploits over feature requests
• Include both the problem AND a concrete solution
• Update the "Current State Snapshot" after each run
• Cross-reference with src/lib/types.ts for constant values
• Look for duplicate posts (may indicate spam or UI bug)
• Track sentiment trends over multiple runs
• Flag any mentions of bots, scripts, or automation for review