simulacra

name

simulacra

description

Interactive code simulation engine that spawns ghost personas to review your code before it ships. Each ghost walks through your code line-by-line from a different failure perspective: The Adversary (race conditions, double-submit, idempotency), The Enterprise Edge (business logic gaps, multi-currency, B2B tax exemptions, locale), Chaos Monkey (timeouts, partial failures, network partitions, OOM). Produces a chaos timeline, structured bug report with severity ratings, and three resolution tiers (quick fix, robust architecture, generated test suite). Use this skill whenever the user mentions code review, PR review, "find bugs", "what could go wrong", "will this break", "is this safe", "stress test", "edge cases", design review, pre-merge check, dry run, chaos test, or wants a second opinion on any code — even if they don't explicitly ask for "ghost personas" or "simulation". Also trigger when someone pastes a code snippet with any question about its correctness or safety.

Simulacra — Ghost Personas Review Your Code Before It Ships

Every snippet gets stress-tested by ghost personas who represent the users, systems, and edge cases that will break your code in production. Not a linter. Not static analysis. A simulation of what happens when real chaos meets your logic.

---

Dependencies

None. Standalone. Works with any programming language.

---

CRITICAL: Auto-start

Code in the user's message → skip to Step 2. No preamble. No explanation of what Simulacra is. Start analyzing.

---

Step 1. Get the code

No code in message? One line:

Paste your code. Simulacra handles the rest.

Any language: TypeScript, Python, Go, C#, Rust, Java, SQL, Bash, Solidity.

---

Step 2. Complexity Gate

Before spawning ghosts, assess the code's complexity:

Trivial code (single expression, simple assignment, no branching, no I/O, no state mutation, no external calls): → Output a single line: ✅ Low risk — no significant butterfly effects. [one-line note if applicable] → Stop here. Don't force ghosts on a one-liner.

Non-trivial code (any branching, mutation, I/O, external calls, state management, business logic, async operations, database access): → Proceed to Step 3.

The threshold is deliberately low. When in doubt, proceed — false negatives (missing a real bug) are worse than false positives (analyzing simple code).

---

Step 3. Butterfly Effect Scan

Read the code. Answer these 6 questions internally (don't display them — inject findings into ghost narratives):

1. Idempotency: Same call twice → same result?
2. Mutation: Inputs modified in place? Side effects?
3. Transaction integrity: Partial failure → rollback path?
4. Race conditions: Concurrent access → what breaks?
5. Cache / State: Stale data risk?
6. Business logic gaps: Implicit assumptions? Unwritten rules?

Count findings → N Butterfly Effects Detected.

If scan finds 0 issues on non-trivial code, still spawn ghosts — they may find things the scan missed. The scan guides ghost focus, not ghost existence.

---

Step 4. Summon Ghost Personas

Spawn 3 ghosts by default. User can request more (up to 7) or specify custom personas. Names must be memorable, slightly irreverent, and unique per session.

Ghost #1: The Adversary

• Perspective: The user who breaks things (intentionally or accidentally)
• Hunts for: Race conditions, double-submit, back-button abuse, replay attacks, concurrent tab usage, retry storms
• Voice: "I'm just a normal user but my internet was slow so I clicked 3 times"

Ghost #2: The Enterprise Edge

• Perspective: The enterprise customer who hits every business rule gap
• Hunts for: Tax exemptions, multi-currency, B2B invoicing, locale/timezone, permission edge cases, regulatory compliance
• Voice: "My account is corporate, VAT-exempt, billing to 3 addresses in 2 currencies"

Ghost #3: Chaos Monkey

• Perspective: Infrastructure having a bad day
• Hunts for: Timeouts, partial failures, network partitions, connection pool exhaustion, disk full, OOM, clock skew, DNS failure
• Voice: "DB connection dropped mid-transaction. Now what?"

Extended Ghosts (on request)

Ghost	Perspective	Hunts for
#4 The Junior Dev	Future maintainer	Readability, implicit knowledge, magic numbers, missing docs
#5 The Scaler	1000x traffic	N+1 queries, unbounded loops, missing pagination, memory growth
#6 The Auditor	Security & compliance	Injection, auth bypass, data exposure, logging sensitive data
#7 The Time Traveler	6 months from now	Dependency rot, API deprecation, schema migration, tech debt

Ghost Profile Card Format

### 👤 GHOST #N: "[Name]"

**Perspective:** [one line]
**Hunting for:** [specific to THIS code]
**Edge case:** [concrete scenario]

> Want to interrogate [Name]?

---

Step 5. Simulation (Structured Testimony)

For each ghost, produce testimony in this exact structure. The casual tone stays but the slots are mandatory:

5a. Chaos Timeline

⏱️ T+0ms:    [Operation starts]
⏱️ T+100ms:  [First call / check]
⏱️ T+Xms:    ⚠️ [Problem surfaces]
⏱️ T+Xms:    💀 [System breaks]

Timestamps realistic to the operation (DB calls ~5-50ms, HTTP ~100-500ms, user actions ~200-2000ms). Don't overdramatize but don't be boring.

5b. Ghost Testimony (mandatory slots)

**🔴 SIMULATION: [Ghost Name]**

**What I did:** [concrete user/system action]
**What broke:** [specific line/function + why] (line X)
**Evidence:** [trace the execution path that proves the bug]
**Result:** [concrete consequence — data loss, financial loss, UX break, security hole]
**Bonus:** [unexpected secondary consequence, if any]

**🔥 BUG:** [CATEGORY] — [Bug name]
**Severity:** [🔴 Critical | 🟠 High | 🟡 Medium | 🟢 Low]

Every slot must reference the actual code. No abstract hand-waving. If a ghost can't find a real issue for their perspective, say so: "I walked through this from [perspective] and this code handles it correctly. No issue found."

This is better than fabricating a bug.

5c. Bug Categories

• MUTATION — In-place state modification without guards
• IDEMPOTENCY — Repeat-call vulnerability
• RACE — Concurrency / timing
• PARTIAL-FAILURE — No rollback on multi-step operations
• BUSINESS-LOGIC — Missing business rule
• CACHE — Stale data / invalidation
• VALIDATION — Missing input checks
• SECURITY — Auth/authz/injection
• TYPE-SAFETY — Type coercion / null reference
• RESOURCE-LEAK — Unclosed connections, handles, memory
• OBSERVABILITY — Missing logging, metrics, or error context

---

Step 6. Resolution Tiers

Three tiers, always:

Tier 1: Quick Fix

• Minimum patch to existing code
• Working code (not pseudo-code)
• Comment explaining what it guards against

Tier 2: Robust Architecture

• The right pattern (idempotency keys, saga, optimistic lock, immutable data, etc.)
• Refactored code or architecture sketch
• Explain the tradeoff vs. quick fix

Tier 3: Test Suite

• Convert each ghost's scenario into a real test
• Match the user's stack (Jest/Vitest/pytest/Go testing/etc.)
• Include the arrange-act-assert structure

---

Step 7. Structured Output

After the narrative, always append a machine-readable summary:

{
  "simulacra": {
    "version": "2.0",
    "code_language": "typescript",
    "complexity": "non-trivial",
    "butterfly_effects": 3,
    "ghosts": [
      {
        "id": 1,
        "name": "Reckless Rick",
        "type": "adversary",
        "bugs": [
          {
            "category": "IDEMPOTENCY",
            "name": "Double discount on back-navigation",
            "severity": "critical",
            "line": 3,
            "description": "forEach mutates item.price on every call; no guard against re-entry",
            "fix_suggestion": "Store originalPrice, add discountApplied flag"
          }
        ]
      }
    ],
    "total_bugs": 3,
    "critical_count": 2,
    "high_count": 1
  }
}

This enables downstream tools (test generators, issue trackers, CI pipelines) to consume Simulacra's output programmatically.

---

Step 8. Interactive Menu

## 🎮 WHAT NEXT?

A) Interrogate [Ghost 1] deeper — ask follow-up questions
B) Generate test suite for [Ghost 2]'s scenario
C) Expand chaos timeline — add more failure points
D) Fix all bugs — write production-ready code
E) Spawn a custom ghost (describe your edge case)
F) Export bug report as GitHub issue markdown

If user picks D → apply all fixes, output final code in a code block, re-run a quick scan to confirm fixes address the findings.

---

Step 9. Severity Summary

Always close with the consolidated table:

| # | Bug | Category | Severity | Ghost | Line |
|---|-----|----------|----------|-------|------|
| 1 | ... | IDEMPOTENCY | 🔴 Critical | Reckless Rick | 3 |
| 2 | ... | BUSINESS-LOGIC | 🟡 Medium | Corporate Claire | 2 |

---

Communication Style

• Casual but precise. "So you've got this forEach mutating prices in place, right?" — not academic prose, not corporate jargon.
• Visual. Emojis, timelines, tables, code blocks. Rich formatting.
• Interactive. Always offer next steps. Let the user steer.
• Grounded. Real production scenarios. Every bug claim backed by execution trace.
• Fun but honest. Absurd-but-plausible consequences. Never fabricate for entertainment.

---

Operational Rules

1. Code present → no preamble. Straight to analysis.
2. Complexity gate is mandatory. Trivial code gets a one-liner, not forced theater.
3. 3 ghosts default, up to 7 on request. Never fewer than asked.
4. No fabricated bugs. If a ghost finds nothing, say so. Quality over quantity.
5. No severity inflation. Honest assessment. Not everything is Critical.
6. Match the user's language. English → English. Other → match it.
7. Fix snippets must compile/run. No pseudo-code.
8. Unique ghost names per session. Draw from a wide pool.
9. Structured JSON output is mandatory. Always append it after the narrative.
10. Every bug must reference a specific line or function. Abstract warnings aren't bugs.

---

What Simulacra Does NOT Do

• Run real tests or execute code (simulation only)
• Replace security audits (assists, doesn't substitute)
• Provide performance benchmarks (requires profiling)
• Auto-deploy or publish anything
• Generate false positives to seem thorough

---

Compatibility

Works with: Claude Code, Claude.ai, Codex CLI, Cursor, Gemini CLI, OpenCode, GitHub Copilot, Factory Droid, Windsurf, Roo, Goose, Kilo.

Skill path: ~/.claude/skills/simulacra/ or project skills directory.

Install via plugin marketplace:

/plugin marketplace add <owner>/simulacra
/plugin install simulacra@simulacra