mindforge-cc 10.0.2 → 10.7.0

package/.mindforge/skills/llm-cost-optimization/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: llm-cost-optimization
+version: 1.0.0
+min_mindforge_version: 0.1.0
+status: stable
+compose: cost-aware-routing
+triggers: llm cost optimization, prompt compression, semantic caching, model cascading, batch api, token estimation, cost per query, model routing optimization, output token reduction, prompt deduplication, cache hit rate, cost monitoring
+---
+
+# Skill — LLM Cost Optimization
+
+## When this skill activates
+Any task involving LLM API cost reduction, prompt compression, semantic caching,
+model cascading/routing, batch API usage, or token budget management.
+
+## Mandatory actions when this skill is active
+
+### Before writing any code
+1. Establish baseline costs (cost per query, daily/monthly spend, cost by feature).
+2. Identify the biggest cost drivers (which prompts, which models, which features).
+3. Set cost reduction targets with quality guardrails.
+
+### During implementation
+- Implement semantic caching for repeated/similar queries.
+- Use model cascading (start cheap, escalate only when needed).
+- Add token estimation before API calls (pre-flight cost check).
+
+### After implementation
+- Monitor cost per query, cache hit rate, and cascade escalation rate.
+- Set up cost anomaly alerts (spike detection).
+- Document cost optimization decisions in ARCHITECTURE.md.
+
+## Prompt Compression
+
+### System Prompt Optimization
+- Remove redundant instructions (LLMs don't need repetition like humans).
+- Use abbreviations and compact formatting in system prompts.
+- Reference items by ID rather than including full content.
+- Cache static system prompts (most providers support this).
+
+### Context Window Efficiency
+- Include only relevant context (not entire documents).
+- Summarize long documents before including in prompt.
+- Use structured formats (JSON/YAML) over verbose prose for data.
+- Remove examples from system prompt once model demonstrates understanding.
+
+### Token Reduction Techniques
+| Technique | Savings | Quality Impact |
+|-----------|---------|---------------|
+| Remove redundant instructions | 10-30% | None |
+| Abbreviate system prompt | 15-25% | Minimal |
+| Summarize context | 40-60% | Low-moderate |
+| Reference by ID | 50-70% | None (if lookup available) |
+| Fewer few-shot examples | 30-50% | Low (if model is capable) |
+
+## Semantic Caching
+
+### Concept
+- Hash similar queries → return cached response if semantically equivalent.
+- Not exact-match caching — uses embedding similarity.
+- Threshold: if query embedding distance < 0.05, serve cached response.
+
+### Implementation
+```
+1. Embed incoming query
+2. Search cache for similar queries (cosine similarity > 0.95)
+3. If hit: return cached response (cost = ~$0)
+4. If miss: call LLM, store response in cache with query embedding
+```
+
+### Cache Invalidation
+- TTL-based: expire after N hours (for time-sensitive data).
+- Event-based: invalidate when underlying data changes.
+- Version-based: invalidate when prompt/model version changes.
+
+### Expected Performance
+- Cache hit rate: 20-60% for typical applications.
+- Cost reduction: proportional to hit rate.
+- Latency improvement: 10-100x faster on cache hits.
+
+## Model Cascading
+
+### Pattern
+```
+Query → Haiku/Small Model → Quality Check → Pass? → Return
+                                                → Fail? → Sonnet/Large Model → Return
+```
+
+### Implementation Rules
+- Start with cheapest model capable of the task.
+- Define quality gate (confidence score, format validation, length check).
+- Escalate to more expensive model only when quality gate fails.
+- Track escalation rate (target: < 20% of queries escalate).
+
+### Model Tier Pricing (Approximate)
+| Tier | Model Examples | Cost (per 1M tokens) | Use For |
+|------|---------------|----------------------|---------|
+| Cheap | Haiku, GPT-4o-mini | $0.25-1.00 | Simple tasks, classification, extraction |
+| Medium | Sonnet, GPT-4o | $3.00-15.00 | Most generation, reasoning |
+| Expensive | Opus, o1 | $15.00-75.00 | Complex reasoning, critical decisions |
+
+### Routing Heuristics
+- Classification/extraction → always use cheap model.
+- Code generation → medium model (escalate if syntax errors).
+- Complex reasoning → start medium, escalate if confidence low.
+- Safety-critical → always use expensive model (no cascading).
+
+## Batch API Usage
+
+### When to Use
+- Non-real-time workloads (background processing, ETL, reports).
+- Large volume of similar requests.
+- Typical discount: 50% cheaper than synchronous API.
+
+### Batch-Eligible Workloads
+- Document summarization pipelines.
+- Nightly content generation.
+- Bulk classification/tagging.
+- Training data generation.
+- Automated evaluations.
+
+### Implementation
+- Queue requests during the day.
+- Submit batch job during off-peak (overnight).
+- Process results next morning.
+- Set up retry for failed items in batch.
+
+## Token Estimation
+
+### Pre-Flight Cost Check
+```python
+estimated_tokens = count_tokens(system_prompt + context + query)
+estimated_cost = estimated_tokens * price_per_token
+if estimated_cost > budget_threshold:
+    compress_context()  # or reject query
+```
+
+### Token Counting
+- Use tiktoken (OpenAI) or provider-specific tokenizer.
+- Count BEFORE sending to API (not after).
+- Include expected output tokens in estimate.
+- Set max_tokens to limit output cost.
+
+### Budget Controls
+- Per-query budget: reject or compress if estimated cost too high.
+- Per-user budget: track cumulative cost, throttle when approaching limit.
+- Per-feature budget: allocate cost budgets to product features.
+
+## Output Token Reduction
+
+### Techniques
+- Set `max_tokens` to reasonable limit for the task.
+- Instruct model to be concise: "Answer in 2-3 sentences."
+- Use structured output (JSON) to prevent verbose prose.
+- Ask for key information only, not explanations (when appropriate).
+
+### Output Cost Impact
+| Approach | Typical Output Reduction | Quality Impact |
+|----------|------------------------|---------------|
+| max_tokens cap | Varies | May truncate if too aggressive |
+| Conciseness instruction | 30-50% | Usually none for factual tasks |
+| JSON/structured output | 40-60% | None (often improves) |
+| Enumerate, don't explain | 50-70% | Low for extraction tasks |
+
+## Cost Monitoring
+
+### Key Metrics
+| Metric | Alert Threshold | Description |
+|--------|----------------|-------------|
+| Daily cost | > 2x rolling average | Anomaly detection |
+| Cost per query | > budget ceiling | Individual query cost |
+| Cache hit rate | < 30% (if caching enabled) | Cache effectiveness |
+| Escalation rate | > 30% | Cascade efficiency |
+| Token waste ratio | > 20% unused max_tokens | Over-allocated budgets |
+
+### Dashboard Requirements
+- Cost breakdown by: feature, model, endpoint, user tier.
+- Trend lines: daily, weekly, monthly.
+- Forecast: projected monthly cost at current rate.
+- Anomaly alerts: immediate notification on cost spikes.
+
+### Optimization Feedback Loop
+```
+Monitor costs → Identify top cost drivers → Apply optimization →
+Measure improvement → Adjust thresholds → Repeat monthly
+```
+
+## Self-check before task completion
+
+Before marking a task done when this skill was active:
+
+- [ ] Did I read the full SKILL.md before starting? (Not just the triggers)
+- [ ] Is semantic caching implemented for repeated queries?
+- [ ] Is model cascading configured (cheap first, escalate on failure)?
+- [ ] Are token budgets estimated before API calls?
+- [ ] Is cost monitoring in place with anomaly alerts?
+- [ ] Are batch APIs used for non-real-time workloads?
+- [ ] Is prompt compression applied to system prompts?

package/.mindforge/skills/llm-orchestration/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: llm-orchestration
+version: 1.0.0
+min_mindforge_version: 10.5.0
+status: stable
+triggers: LLM orchestration system, chain-of-thought routing, model cascading strategy, LLM fallback design, LLM context window optimization, LLM router design, model selection pipeline, LLM chain composition, prompt chaining, LLM gateway architecture, multi-model routing, LLM request planning
+compose:
+  - agent-orchestration-patterns
+---
+
+# LLM Orchestration & Routing
+
+## When this skill activates
+
+This skill activates when building systems that route requests across multiple LLMs, cascade from cheap to expensive models, implement fallback strategies, or manage context window limits. It applies to production AI systems where cost, latency, and reliability must be optimized across a fleet of models.
+
+## Mandatory actions when this skill is active
+
+### Before writing any code
+
+1. **Map task to model capabilities** — Identify which tasks require which model capabilities: reasoning (Opus/GPT-4), speed (Haiku/GPT-3.5), cost-efficiency (Haiku/GPT-3.5), context length (Claude 200K, GPT-4 128K), multimodal (GPT-4V, Claude Sonnet with vision). Not all tasks need the most expensive model.
+2. **Design cascading strategy** — Define fallback chain: start with fastest/cheapest model, escalate to more capable models if quality is insufficient. Example: Haiku → Sonnet → Opus. Measure escalation rate (% of requests that cascade) and optimize to minimize unnecessary escalations.
+3. **Establish routing rules** — Define deterministic rules for model selection: route by task type (classification → Haiku, creative writing → Opus), by complexity (short prompts → small models, long prompts → large models), or by user tier (free users → Haiku, paid users → Sonnet). Document routing logic explicitly.
+4. **Plan for context window management** — Measure typical prompt lengths and output lengths. If prompts exceed model limits, implement truncation (drop least important context), summarization (compress with smaller model), or chunking (split into multiple requests). Test that truncated prompts still produce useful outputs.
+
+### During implementation
+
+- **Implement request routing layer** — Build a central router that examines each request (task type, complexity, user tier, priority) and selects the appropriate model. Router must be fast (<10ms overhead) and deterministic (same input always routes to same model for consistency).
+- **Add quality-based cascading** — After receiving a response from a cheap model, run a lightweight quality check (confidence score, length validation, keyword presence). If quality is below threshold, retry with a more expensive model. Log all escalations for analysis.
+- **Design stateful prompt chaining** — When chaining multiple LLM calls (research → draft → critique → revision), maintain conversation state explicitly. Use structured context: {task: ..., previous_output: ..., next_instruction: ...}. Avoid relying on model memory (models are stateless between API calls).
+- **Implement prompt compression** — For long contexts, compress aggressively: remove filler words, use abbreviations, reference external documents by ID instead of embedding full text. Test that compressed prompts produce equivalent outputs. Measure compression ratio (original tokens / compressed tokens).
+- **Handle rate limits gracefully** — Implement exponential backoff and retry logic for rate limit errors. If one model is rate-limited, fail over to an alternative model (even if more expensive). Never return errors to users due to transient rate limits.
+- **Track cost and latency per model** — Log every request: model used, input tokens, output tokens, latency, cost. Aggregate metrics by model and task type. Identify opportunities to downgrade expensive models to cheaper alternatives without quality loss.
+
+### After implementation
+
+- **Validate routing accuracy** — Test that requests route to the expected model based on your rules. Measure routing accuracy (% of requests routed correctly). Incorrect routing wastes cost (cheap task routed to expensive model) or produces poor quality (complex task routed to weak model).
+- **Measure cascade efficiency** — Track escalation rate: % of requests that start with a cheap model but cascade to expensive models. Target: <10% escalation rate. Higher rates indicate routing rules are too aggressive (route to cheaper models upfront).
+- **Benchmark end-to-end latency** — Measure latency including routing overhead, model inference, and cascading retries. Compare to single-model baseline. Orchestration should add <50ms overhead. If higher, optimize routing logic or reduce cascade depth.
+- **Test fallback behavior** — Simulate model failures (rate limits, API downtime, timeouts) and validate that fallback logic activates. Ensure degraded mode still returns useful responses (even if lower quality or higher latency).
+
+## Self-check before task completion
+
+- [ ] Task-to-model mapping is documented with capability requirements (reasoning, speed, cost, context)
+- [ ] Cascading strategy is defined with explicit escalation rules and thresholds
+- [ ] Routing rules are deterministic and documented (by task type, complexity, user tier)
+- [ ] Context window limits are handled via truncation, summarization, or chunking strategies
+- [ ] Request router is implemented with <10ms overhead and deterministic behavior
+- [ ] Quality-based cascading retries with more expensive models if quality is below threshold
+- [ ] Prompt chaining maintains stateful context explicitly across LLM calls
+- [ ] Prompt compression is implemented and tested for equivalence with uncompressed prompts
+- [ ] Rate limit handling implements exponential backoff and model failover
+- [ ] Cost and latency per model are logged and aggregated for optimization analysis
+- [ ] Routing accuracy is validated (requests route to expected models)
+- [ ] Escalation rate is measured and optimized to <10% of requests
+- [ ] Fallback behavior is tested under simulated model failures (rate limits, downtime)

package/.mindforge/skills/load-testing/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: load-testing
+version: 1.0.0
+min_mindforge_version: 10.0.8
+status: stable
+triggers: load testing, k6 script, locust test, artillery config, load profile, ramp up test, spike test, soak test, stress test, SLA validation, throughput test, concurrent users
+compose: performance
+---
+
+# Load Testing
+
+## When this skill activates
+
+This skill activates when designing, writing, or analyzing performance tests that simulate user load against a system. It applies to any scenario involving throughput measurement, latency profiling under load, capacity planning, or SLA validation.
+
+## Mandatory actions when this skill is active
+
+### Before
+
+1. Define the SLA targets (p95 latency < X ms, error rate < Y%, throughput > Z rps).
+2. Identify the critical user journeys to simulate (login flow, checkout, search).
+3. Determine the load profile type needed (load, stress, spike, or soak).
+4. Confirm test environment is production-like (same infra, realistic data volume).
+5. Establish baseline metrics from current production (if available).
+6. Ensure monitoring is active during tests (APM, infra metrics, logs).
+
+### During
+
+**Test Types and When to Use:**
+- **Load test**: Expected traffic. Validates system meets SLA under normal conditions.
+- **Stress test**: Beyond capacity. Finds the breaking point and degradation behavior.
+- **Spike test**: Sudden burst (0 to max instantly). Tests auto-scaling and recovery.
+- **Soak test**: Sustained load for hours. Detects memory leaks, connection pool exhaustion, log disk fill.
+
+**Load Profile Design:**
+- **Ramp**: Gradually increase (0 → target over 5 minutes). Standard for load tests.
+- **Spike**: Instant jump to peak. Use for flash sale / viral event scenarios.
+- **Step**: Increase in discrete steps (50 → 100 → 150). Good for finding thresholds.
+- **Soak**: Steady state for 2-8 hours. Target = expected average load.
+
+**Tool Selection:**
+- **k6** (Go-based): Developer-friendly, JS scripting, excellent CI integration, checks/thresholds built-in.
+- **Locust** (Python): Python scripting, distributed mode, real-time web UI, event-driven.
+- **Artillery** (Node): YAML config, scenario-based, good for quick setups, plugin ecosystem.
+
+**Metrics to Capture:**
+- **Latency**: p50, p95, p99 (p95 is your SLA target, p99 catches tail latency).
+- **Throughput**: Requests per second (rps) sustained at target.
+- **Error rate**: Percentage of non-2xx responses under load.
+- **Saturation**: CPU, memory, connection pool usage, thread count.
+- **Apdex**: Application Performance Index score.
+
+**Environment Considerations:**
+- NEVER run load tests against production without explicit approval and safeguards.
+- Use dedicated load-test environment with production-equivalent resources.
+- Populate with realistic data volume (empty DB gives false confidence).
+- Disable rate limiters and WAF rules that would mask real limits (or test with them separately).
+- Coordinate with infrastructure team to avoid impacting shared services.
+
+**Result Analysis:**
+- Compare against SLA targets: PASS if all thresholds met under target load.
+- Identify the saturation point (where latency inflects upward).
+- Check for error rate correlation with load increase.
+- Look for resource bottlenecks (CPU-bound vs IO-bound vs network-bound).
+- Document capacity ceiling: "System handles X concurrent users before degradation."
+
+### After
+
+1. Record results with full context (date, environment, data volume, test config).
+2. Compare against previous runs to detect regressions.
+3. File tickets for any SLA violations with root cause analysis.
+4. Update capacity planning docs with new findings.
+5. Archive test scripts and results in version control.
+
+## Self-check before task completion
+
+- [ ] SLA targets are explicitly defined and measurable.
+- [ ] Load profile matches a realistic usage pattern (not arbitrary numbers).
+- [ ] Test runs long enough to surface time-dependent issues (minimum 5 minutes for load, 2+ hours for soak).
+- [ ] Results include p50, p95, p99 latency plus error rate and throughput.
+- [ ] Test environment is documented (instance types, replicas, data volume).
+- [ ] Bottleneck identified and categorized (CPU / memory / IO / network / external dependency).
+- [ ] Results compared against baseline or SLA with clear PASS/FAIL verdict.
+- [ ] No tests were accidentally run against production without safeguards.

package/.mindforge/skills/logistics-optimization/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: logistics-optimization
+version: 1.0.0
+min_mindforge_version: 10.2.0
+status: stable
+triggers: logistics optimization, route planning algorithm, fleet management system, warehouse management, last-mile delivery, supply chain visibility, shipment tracking, delivery optimization, logistics platform, transportation management, inventory routing, fulfillment optimization
+---
+
+# Skill — Logistics Optimization
+
+## When this skill activates
+This skill activates when building route planning algorithms, fleet management systems, warehouse management platforms, last-mile delivery optimization, supply chain visibility tools, shipment tracking, transportation management systems, or fulfillment optimization engines.
+
+## Mandatory actions when this skill is active
+
+### Before writing any code
+1. Design route optimization algorithm: model as Vehicle Routing Problem with Time Windows (VRPTW), constraints (vehicle capacity, driver shift hours, customer time windows, priority deliveries), objective function (minimize total distance, balance workload across drivers, maximize on-time delivery %), solution methods (heuristic: nearest neighbor with 2-opt improvement, metaheuristic: simulated annealing, genetic algorithm, or exact: mixed-integer programming for <100 stops)
+2. Model warehouse operations workflow: receiving (unload truck, quality check, barcode scan, put-away to optimal bin location) → storage (zone by velocity: fast-movers near packing, slow-movers in bulk) → picking (batch pick orders, wave pick by zone, pick-to-light system) → packing (right-sized box selection, void fill, label printing) → shipping (load truck, scan manifests, dispatch)
+3. Map shipment lifecycle with visibility: order placed → warehouse allocated (nearest to destination with stock) → picked → packed → labeled → handed to carrier → in-transit (tracking events: picked up, at hub, out for delivery) → delivered (signature capture, photo proof) → exceptions handled (delivery failed, address incorrect, damaged)
+
+### During implementation
+- Implement route planning with real-time constraints: integrate maps API (Google Maps, Mapbox) for distance matrix (travel time between all location pairs), consider traffic patterns (historical data + real-time updates), vehicle constraints (capacity in cubic meters + weight, refrigeration for perishables), driver constraints (shift hours, break requirements, certifications for hazmat), time windows (hard: must deliver 2-4pm, soft: preferred 2-4pm with penalty)
+- Build fleet management with telematics: integrate GPS devices (track vehicle location every 30s), monitor vehicle health (fuel level, engine diagnostics, tire pressure), driver behavior scoring (harsh braking, speeding, idle time), geofencing (alert when vehicle enters/exits depot or customer site), maintenance scheduling (oil change every 5000 miles, tire rotation every 10K miles)
+- Design warehouse management system (WMS): inventory stored by SKU with bin location (aisle-rack-shelf), implement slotting optimization (place high-velocity items near packing, co-locate frequently ordered-together items), track lot numbers and expiry dates (FIFO/FEFO picking), support cycle counting (daily counts of A-items, weekly B-items, monthly C-items), integrate barcode scanners for all transactions
+- Implement last-mile delivery optimization: cluster orders by geographic proximity (k-means clustering), assign to delivery vehicles (bin packing problem: maximize utilization), sequence stops (traveling salesman problem: minimize route distance), provide driver mobile app (turn-by-turn navigation, delivery instructions, photo capture, signature collection, real-time status updates)
+- Build shipment tracking with carrier integration: integrate with carrier APIs (FedEx, UPS, USPS for tracking updates), parse webhooks (shipment picked up, in transit, out for delivery, delivered, exception), store tracking history (timestamp, location, status, notes), expose customer tracking page (order number lookup, map visualization, estimated delivery time), send proactive notifications (SMS/email at key events)
+
+### After implementation
+- Validate route optimization quality: measure total distance vs greedy baseline (should be 10-20% improvement), on-time delivery rate (>95%), vehicle utilization (>80% capacity filled), driver satisfaction (balanced workload, no overtime unless necessary), test with historical order data (replay last month's orders with optimized routes)
+- Test warehouse efficiency metrics: measure pick rate (items per hour, target: 100 for standard, 200 for pick-to-light), packing time (minutes per order, target: <3 min), accuracy rate (>99.5% correct items, correct quantities), inventory accuracy (cycle count variance <1%), space utilization (>80% of racking filled)
+- Execute delivery performance analysis: track key metrics (on-time delivery rate >95%, first-attempt delivery rate >90%, customer satisfaction score >4.5/5), identify failure modes (address incorrect, customer not home, access issues), measure exception resolution time (redelivery scheduled within 24 hours)
+
+## Self-check before task completion
+- [ ] Route optimization functional: VRPTW solver with constraints (capacity, time windows, driver shifts), objective function (minimize distance, balance workload)
+- [ ] Fleet management integrated: GPS tracking (30s updates), telematics (vehicle health, driver behavior), geofencing (depot/customer alerts), maintenance scheduling
+- [ ] Warehouse operations optimized: inventory slotting (velocity-based placement), picking strategies (batch, wave, pick-to-light), barcode scanning at all touchpoints
+- [ ] Last-mile delivery optimized: geographic clustering, bin packing assignment, TSP sequencing, driver mobile app (navigation, photo/signature, status updates)
+- [ ] Shipment tracking real-time: carrier API integration (FedEx/UPS/USPS), webhook parsing, tracking history storage, customer tracking page, proactive notifications
+- [ ] Performance metrics tracked: route distance improvement (10-20% vs baseline), on-time delivery >95%, pick rate 100+ items/hr, inventory accuracy >99.5%
+- [ ] Exception handling robust: delivery failures (address incorrect, not home), redelivery scheduling (within 24h), customer notifications (SMS/email)

package/.mindforge/skills/market-researcher/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: market-researcher
+version: 1.0.0
+min_mindforge_version: 10.0.6
+status: stable
+triggers: market research, competitor analysis, TAM SAM SOM, market sizing, opportunity scoring, positioning strategy, SWOT analysis, competitive landscape, market opportunity, Porter forces, market entry, competitive advantage
+---
+
+# Skill — Market Researcher
+
+## When this skill activates
+Any task involving market sizing, competitive analysis, positioning strategy, opportunity
+assessment, market entry evaluation, or strategic intelligence gathering.
+
+## Mandatory actions when this skill is active
+
+### Before
+
+1. **Define market boundary** — Geographic scope, customer segment, product category. Ambiguous boundaries produce useless analysis.
+2. **State the decision** — Market research serves a decision (enter, price, position, prioritize). Name it.
+3. **Identify data sources** — Primary (interviews, surveys) and secondary (reports, filings). Note confidence per source.
+
+### During
+
+#### TAM/SAM/SOM sizing
+```
+Top-down (industry reports):
+  TAM = total market revenue at 100% share (analyst reports, govt data)
+  SAM = TAM * geographic_filter * segment_filter * product_fit_filter
+  SOM = SAM * realistic_capture_rate (3-5yr, benchmarked)
+
+Bottom-up (unit economics):
+  SOM = reachable_customers * win_rate * average_ACV
+
+Cross-validate: top-down and bottom-up within 2x. If divergent, re-examine assumptions.
+```
+
+#### Competitor analysis framework
+Per competitor document: overview (founded, HQ, size, funding, revenue estimate), product analysis (features, pricing model, integrations, UX), strengths (with evidence), weaknesses (with evidence), positioning (tagline, claimed differentiator, market perception), signals to monitor (hiring, changelog velocity, pricing moves).
+
+#### SWOT analysis
+```
+Strengths (internal, current) | Weaknesses (internal, current)
+Opportunities (external, future) | Threats (external, future)
+
+Action matrix:
+  S+O = INVEST (leverage strengths to capture opportunities)
+  S+T = DEFEND (use strengths to mitigate threats)
+  W+O = IMPROVE (fix weaknesses to unlock opportunities)
+  W+T = URGENT (weaknesses that amplify threats — fix first)
+```
+
+#### Porter's Five Forces
+1. Threat of New Entrants — barriers: capital, network effects, switching costs, regulation
+2. Supplier Power — concentration, switching costs, substitute inputs
+3. Buyer Power — concentration, price sensitivity, switching costs
+4. Threat of Substitutes — alternative solutions, price-performance ratio
+5. Competitive Rivalry — number of players, growth rate, differentiation, exit barriers
+
+Rate each High/Medium/Low with specific evidence. Conclude overall industry attractiveness.
+
+#### Opportunity scoring matrix
+```
+Score = 0.3*MarketSize + 0.3*Fit + 0.2*(6-Effort) + 0.2*(6-Competition)
+All dimensions rated 1-5. Show weights and math transparently.
+Rank opportunities by score. Top 2-3 become strategic focus.
+```
+
+#### Positioning strategy (2x2 maps)
+- Axes: choose two dimensions that matter to buyers (price vs breadth, ease vs power)
+- Plot competitors and self on the map
+- Identify white space (underserved quadrants)
+- Craft positioning statement: "For [segment] who [need], [Product] is the [category] that [differentiator], unlike [alternative] which [limitation]."
+
+#### Market entry timing
+```
+Market readiness: budget exists, pain is acute, category awareness present
+Competitive window: no dominant incumbent, slow innovators, tech shift creates opening
+Internal readiness: domain expertise, MVP <6 months, GTM channel identified, unit economics work
+
+All green = GO | 1-2 yellow = GO with mitigation | Red in market readiness = WAIT
+```
+
+### After
+
+1. **Cross-validate** — Triangulate from 3+ sources. Single-source = hypothesis, not finding.
+2. **Label confidence** — High (3+ sources), Medium (2 sources), Low (single/inference).
+3. **Connect to decision** — Every insight maps to the stated decision. Remove interesting-but-unactionable analysis.
+4. **Set refresh cadence** — Competitors: quarterly. Market sizing: annually.
+
+## Self-check before task completion
+- [ ] Market boundary clearly defined (geography, segment, category)
+- [ ] TAM/SAM/SOM calculated top-down AND bottom-up, cross-validated
+- [ ] Competitor profiles cover product, pricing, strengths, weaknesses
+- [ ] SWOT has action matrix (S+O, S+T, W+O, W+T strategies)
+- [ ] Porter's Five Forces assessed with evidence per force
+- [ ] Positioning map identifies white space and adjacent moves
+- [ ] Opportunity scoring uses weighted criteria with transparent math
+- [ ] Confidence level labeled on every finding

package/.mindforge/skills/marketplace-trust/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: marketplace-trust
+version: 1.0.0
+min_mindforge_version: 10.2.0
+status: stable
+triggers: marketplace trust system, reputation scoring, fraud detection marketplace, dispute resolution workflow, escrow payment pattern, trust and safety, content moderation marketplace, seller verification, buyer protection, platform integrity, transaction dispute, marketplace fraud prevention
+---
+
+# Skill — Marketplace Trust
+
+## When this skill activates
+This skill activates when building reputation systems, fraud detection, dispute resolution workflows, escrow payment patterns, trust and safety mechanisms, content moderation, seller verification, buyer protection, or platform integrity features for marketplaces.
+
+## Mandatory actions when this skill is active
+
+### Before writing any code
+1. Design reputation scoring system: aggregate trust signals (completion rate, average rating, response time, dispute rate, tenure, transaction volume), weight recent activity higher (exponential decay: last 30 days = 50%, 30-90 days = 30%, 90+ days = 20%), normalize to 0-100 scale, segment by buyer/seller roles (separate scores)
+2. Model dispute resolution workflow: buyer opens dispute (order not received, item not as described, damaged) → seller responds within 48 hours → platform mediator reviews evidence (messages, photos, tracking) → decision rendered (refund, partial refund, favor seller) → appeal window (7 days) → final resolution → reputation impact recorded
+3. Map escrow payment flow: buyer pays platform (funds held) → seller notified (order confirmed) → seller ships item → buyer receives and inspects (3-7 day review period) → buyer approves (funds released to seller) OR buyer disputes (funds held until resolution) → platform fee deducted (10-20%) → seller payout (ACH, wire, PayPal)
+
+### During implementation
+- Implement fraud detection with multi-signal analysis: velocity checks (too many orders in 1 hour, new account with high-value purchase), device fingerprinting (IP geolocation mismatch with shipping address, VPN detection), behavioral anomalies (first order is expensive electronics), content analysis (listing description contains phishing keywords), ML scoring (ensemble model: random forest + gradient boosting, threshold tuning for precision/recall)
+- Build reputation system with decay and recovery: store transaction outcomes (completed, disputed, refunded), calculate rolling metrics (30-day completion rate, 90-day avg rating), apply penalty for disputes (temporary score reduction, recovers over 6 months with good behavior), prevent review manipulation (verified purchase only, rate limiting 1 review per transaction, detect suspicious patterns like coordinated 5-star reviews from new accounts)
+- Design dispute resolution dashboard: queue disputes by age (SLA: respond within 24 hours), display conversation history with timestamps, attach evidence (photos, tracking numbers, payment receipts), automated suggestions (refund amount calculator based on depreciation, precedent from similar disputes), escalation to human moderator for complex cases, decision audit trail (who decided, when, rationale)
+- Implement content moderation pipeline: user-generated content (listings, reviews, messages) → automated filters (profanity, prohibited items like weapons/drugs, spam detection via regex and ML) → flagged content queued for human review → moderator approves/rejects with reason → user notification (content removed, account warning, suspension on repeat violations) → appeal process
+- Build seller verification with identity proofing: phone verification (SMS OTP), email verification (link click), government ID upload (passport, driver's license → OCR extraction, face matching via liveness check), business registration documents (tax ID, incorporation certificate → third-party verification API), bank account linking (micro-deposit verification)
+
+### After implementation
+- Validate reputation accuracy: measure correlation with actual outcomes (high-rated sellers have <2% dispute rate, low-rated >10%), test decay mechanism (old bad reviews eventually expire), verify manipulation resistance (fake review rings detected and removed), ensure fairness (new sellers can build reputation within 30 days with 10+ successful transactions)
+- Test fraud detection effectiveness: simulate known fraud patterns (account takeover, credit card fraud, fake listings), measure detection rate (>95% of known fraud blocked), false positive rate (<1% of legit transactions flagged), detection latency (<1 second at transaction time), monitor feedback loop (fraud analysts label misses, retrain model monthly)
+- Execute dispute resolution fairness audit: measure resolution time (median <72 hours), appeal rate (<5% of decisions), appeal overturn rate (10-15% indicates healthy calibration), sentiment analysis of user feedback (post-resolution satisfaction), detect bias (outcomes should not correlate with user demographics)
+
+## Self-check before task completion
+- [ ] Reputation scoring functional: aggregates trust signals (completion rate, rating, disputes), weights recent activity higher (exponential decay), normalized 0-100 score
+- [ ] Fraud detection multi-signal: velocity checks, device fingerprinting, behavioral anomalies, content analysis, ML scoring with tuned threshold
+- [ ] Dispute resolution workflow: buyer opens, seller responds (48h SLA), evidence review, decision rendered, appeal window (7 days), reputation impact
+- [ ] Escrow payment implemented: funds held by platform, released on buyer approval or dispute resolution, seller payout with fee deduction
+- [ ] Content moderation active: automated filters (profanity, prohibited items), human review queue, moderator actions (approve/reject/suspend), appeal process
+- [ ] Seller verification robust: phone/email verification, government ID with OCR + liveness, business documents, bank account linking
+- [ ] Fairness metrics tracked: resolution time <72h, appeal rate <5%, no bias in outcomes, new sellers can build reputation within 30 days