@complexthings/superpowers-agent 9.2.0 → 10.0.0

package/skills/meta/writing-prompts/SKILL.md

@@ -1,122 +0,0 @@
----
-name: writing-prompts
-description: Use when creating a reusable AI command, slash command, prompt file, or skill for Claude Code, GitHub Copilot, or Cursor, when you catch yourself repeating the same instructions 2+ times, or when a prompt keeps producing unreliable results. Guides prompt-engineering craft — leading with the goal, defining verifiable success criteria, keeping the prompt minimal — plus current platform formats (all three platforms now converge on SKILL.md). Use even when the user just says "make this reusable," "save this as a command," or "why does this prompt keep failing."
----
-
-# Writing Prompts
-
-A reusable command is a prompt you've decided to keep. Its quality is the quality of the prompt inside it — so most of this skill is about writing a prompt that works, and a smaller part is about where each platform wants the file to live.
-
-**Core principle:** A good prompt reads like a brief to a sharp new colleague who lacks your context. State the goal, give the context they're missing, and define how they'll know they're done. If a teammate would be confused by it, the model will be too.
-
-## When to turn a prompt into a command
-
-Create a reusable command when you've run the same instructions 2+ times, when you want a workflow to be consistent across a team, or when a multi-step process keeps drifting. The second time you paste the same prompt is the signal — capture it then, while you still remember the edge cases, rather than "later."
-
-Skip it for genuine one-offs and for trivial queries that don't benefit from a saved template. A command that's too broad ("help with testing") is worse than none — it can't give the model enough to act on.
-
-## How to write the prompt
-
-This is the part that determines whether the command is worth keeping. The ordering below roughly tracks impact.
-
-### 1. Lead with the goal
-
-Open with one sentence stating what success looks like. The model orients everything else around it. "Generate a React component with typed props and a passing test" beats a prompt that buries the objective under setup.
-
-### 2. Give the context the model is missing
-
-The model is capable but has no memory of your situation. Supply the specifics it can't infer — file paths, the framework in use, conventions, constraints — and say *why* when the reason isn't obvious. Explaining motivation ("we exclude test accounts because they skew the metrics") lets the model generalize to cases your instructions didn't anticipate, instead of following a rule blindly.
-
-Reason from facts you actually have. Don't invent paths, ticket IDs, or constraints to fill a gap — name the gap instead.
-
-When the command will run repeatedly, wire in the inputs it needs rather than expecting them pasted each time — have it read the file, run the diff, or fetch the data itself (platforms.md covers the per-platform syntax for this). A command that gathers its own context is the difference between a saved note and a tool.
-
-### 3. Define verifiable success criteria
-
-This is the highest-leverage habit. Translate vague asks into outcomes the model can check itself:
-
-- "Add validation" → "Write tests for the invalid inputs, then make them pass"
-- "Fix the bug" → "Write a failing test that reproduces it, then make it pass"
-- "Refactor X" → "Tests pass before and after; behavior unchanged"
-
-For multi-step work, attach a check to each step and state an explicit stop condition, so the command can loop on its own instead of pausing for clarification:
-
-```
-1. <step> → verify: <check>
-2. <step> → verify: <check>
-```
-
-Weak criteria ("make it work") force the model to come back and ask. Strong, checkable criteria let it run to completion. Default to strong.
-
-### 4. Keep it minimal
-
-Write the shortest prompt that gets the job done. Every extra instruction competes for attention and invites the model to overbuild. Cut speculative sections, preemptive caveats for failures that can't happen, and "flexibility" nobody asked for. If a draft is 30 lines and could be 10, rewrite it. The senior-engineer test: "Is this overcomplicated?" If yes, cut.
-
-Trust the model with what it already knows. You don't need to explain what a PDF is or how a for-loop works — only what's specific to your task.
-
-### 5. Show an example when format matters
-
-When output shape, tone, or structure matters, one or two concrete input→output examples steer the result more reliably than describing it in prose. Make examples relevant and varied; if you wrap them in clear delimiters the model won't mistake them for instructions to follow literally.
-
-### 6. Structure for the model to parse
-
-- Put long reference material (documents, data, logs) near the **top**, and the actual instruction or question near the **bottom**. Trailing instructions measurably improve responses on long inputs.
-- Separate distinct kinds of content with delimiters or tags (e.g. `<context>`, `<task>`, `<example>`) so the model can tell the brief from the data. Use the same tag names consistently.
-- Reach for explicit sections (context / task / constraints / success criteria) only when the prompt is big enough to need them. On a short prompt, sections are padding — prose is fine.
-
-### 7. Write direct, positive instructions
-
-Tell the model what to do, not what to avoid: "Respond in flowing prose paragraphs" works better than "Don't use bullet points." Be explicit about scope, because current models read prompts literally and won't widen scope on their own — "apply this to every section, not just the first" leaves nothing to guess.
-
-Resist the urge to shout. Modern models over-react to `CRITICAL:` / `YOU MUST` / `NEVER` and aggressive capitals — it makes them rigid and anxious, not more careful. "Use this tool when handling PDFs" lands better than "CRITICAL: You MUST ALWAYS use this tool." Save emphasis for the rare instruction that genuinely overrides a strong default, and explain *why* it matters rather than how loudly.
-
-### 8. Keep edits surgical
-
-When refining an existing prompt, change only what isn't working. Don't reword lines that already do their job or reorder sections for the sake of it. Match the author's voice — if they'd phrase something differently than you would, theirs wins. Every change should trace to a concrete gain in clarity, completeness, or executability; if it doesn't, revert it.
-
-## Worked example
-
-A raw, repeated instruction:
-
-> "make me a command that reviews code for security stuff"
-
-Refined into a prompt worth saving:
-
-```markdown
-Review the staged diff for security vulnerabilities.
-
-Focus on the OWASP categories most relevant to this stack: injection,
-broken access control, secrets in code, and unsafe deserialization.
-
-For each finding, report: file:line, the risk, and a concrete fix.
-End with a one-line verdict: SAFE TO MERGE or CHANGES REQUESTED.
-
-If there are no findings, say so explicitly — don't invent issues to seem thorough.
-```
-
-What changed: a single clear goal, the missing context (which risks to weight), an explicit output shape, and a stop condition that prevents the model from padding the report. No CAPS, no nagging — just a brief a colleague could act on.
-
-## Platform formats
-
-The three major platforms have converged: **a reusable command is increasingly just a `SKILL.md` file.** Claude Code merged custom commands into skills; Cursor (2.4+) promotes Skills as the successor to commands; GitHub Copilot uses prompt files alongside `AGENTS.md`. Older formats still work, but new work should prefer skills where the platform supports them.
-
-Pick the file location and frontmatter for your target platform from **[references/platforms.md](references/platforms.md)** — it has the exact directories, extensions, frontmatter fields, and argument syntax for Claude Code, GitHub Copilot, and Cursor, with the legacy formats noted. Read it when you're ready to save the file; using the wrong directory or argument token is the one mistake the model can't reason its way out of after the fact.
-
-## Before you ship it
-
-Read the draft once more as if you didn't write it, through three quick lenses:
-
-- **What's sloppy?** Redundant lines, assumptions stated as fact, speculative sections.
-- **What's missing?** Anything that would make it fail on the first run — an undefined success criterion, missing context, an ambiguous scope.
-- **What am I hiding behind structure?** Headings and ceremony that dress up a thin prompt. Cut to the prompt that actually does the work.
-
-Then confirm the goal is in the first sentence, success is checkable, and the file is in the right place for its platform.
-
-## Common pitfalls
-
-- **Vague scope** — "review the code" gives the model nothing to optimize. Name what to look for and what "done" means.
-- **No success criterion** — without a checkable outcome the command can't finish on its own; it stalls and asks.
-- **Over-prompting** — CAPS, `MUST`, and stacked caveats make models rigid. Explain why instead of shouting.
-- **Padding** — speculative sections and impossible-failure handling. Ship the minimum that works.
-- **Wrong platform format** — frontmatter or argument tokens from the wrong tool silently break the command. Verify against references/platforms.md.
-- **Deferring** — "I'll make it reusable later" after the 2nd repeat. Capture it now, while the edge cases are fresh.

package/skills/meta/writing-prompts/references/platforms.md

@@ -1,114 +0,0 @@
-# Platform formats
-
-Exact locations, file formats, frontmatter, and argument syntax for reusable commands on each platform. Read the section for your target platform when saving the file.
-
-## Contents
-- The convergence on SKILL.md
-- Claude Code (skills + legacy commands)
-- GitHub Copilot (prompt files + custom instructions)
-- Cursor (commands + rules + skills)
-- Quick pick
-
-## The convergence on SKILL.md
-
-All three platforms are moving the same direction: a reusable command is becoming a skill — a directory containing a `SKILL.md` file with YAML frontmatter. Claude Code states custom commands "have been merged into skills"; Cursor 2.4 promotes Skills as the successor to commands and ships a `/migrate-to-skills` flow; GitHub Copilot reads `AGENTS.md` and a skills-style layout. Legacy formats still work everywhere, but prefer skills for new work where the platform supports them.
-
-A minimal skill, identical in shape across platforms:
-
-```
-my-command/
-└── SKILL.md
-```
-
-```markdown
----
-name: my-command
-description: What it does and when to use it.
----
-
-# My Command
-
-<the prompt body>
-```
-
-## Claude Code
-
-**Skills (recommended).**
-- Project: `.claude/skills/<name>/SKILL.md` (commit to git to share)
-- Personal: `~/.claude/skills/<name>/SKILL.md` (all your projects)
-- The command name comes from the **directory name** → `/my-command`. Frontmatter `name` only sets the display label.
-- Precedence: enterprise > personal > project. If a skill and a legacy command share a name, the skill wins.
-
-**Legacy commands (still supported).**
-- `.claude/commands/<name>.md` or `~/.claude/commands/<name>.md` → `/name` (from the file name).
-- Support the same frontmatter as skills.
-
-**Frontmatter (all optional; `description` is the one that matters for triggering):**
-`name`, `description`, `when_to_use`, `argument-hint` (e.g. `[issue-number]`), `arguments` (named positional args), `disable-model-invocation` (default `false` — set `true` to make it manual-only, i.e. a pure slash command the model won't auto-run), `user-invocable` (default `true`), `allowed-tools` / `disallowed-tools`, `model` (or `inherit`), `effort` (`low`/`medium`/`high`/`xhigh`/`max`), `context` (`fork`), `agent`, `hooks`, `paths` (glob auto-activation), `shell` (`bash`/`powershell`).
-
-**Arguments (0-based — note this differs from the old `$1`-is-first convention):**
-- `$ARGUMENTS` — all arguments as one string. If the file contains none, the args are appended as `ARGUMENTS: <value>`.
-- `$ARGUMENTS[0]` — first argument; `$ARGUMENTS[1]` second, etc.
-- `$0`, `$1` — shorthand; **`$0` is the first argument.**
-- `$name` — a named argument declared in `arguments:` frontmatter, bound by position.
-- Also available: `${CLAUDE_SESSION_ID}`, `${CLAUDE_EFFORT}`, `${CLAUDE_SKILL_DIR}`.
-
-**Bash injection in the body:**
-- Inline: `` !`<command>` `` (only at line start or after whitespace).
-- Block: a fenced ` ```! ` code block.
-- Runs as preprocessing before the model sees the body; requires a matching `allowed-tools` grant such as `Bash(gh *)`.
-
-**Skill vs command vs subagent:**
-- Reference-style content (knowledge the model pulls in when relevant) → a normal skill.
-- Action you invoke explicitly → a skill with `disable-model-invocation: true`, or a legacy command.
-- Delegated, isolated-context work → a subagent in `.claude/agents/<name>.md` (frontmatter `name`, `description`, `tools`, `model`), or a skill run with `context: fork` + `agent:`.
-
-## GitHub Copilot
-
-**Prompt files** (VS Code, Visual Studio, JetBrains):
-- Location: `.github/prompts/`
-- Naming: `<name>.prompt.md` (e.g. `explain-code.prompt.md`)
-- Frontmatter documented by GitHub: `agent:` (value `'agent'`) and `description:`. (`model` and `tools` exist in VS Code's own prompt-file format but are **not** part of GitHub's documented spec — don't rely on them for portability.)
-- Invoke: type `/<name>` (no extension) in Copilot Chat → `/explain-code`.
-
-```markdown
----
-agent: 'agent'
-description: 'Generate a clear code explanation with examples'
----
-
-Explain the selected code. Cover what it does, the non-obvious parts, and one example call.
-```
-
-**Repository custom instructions** (always-on context, not invoked):
-- Repo-wide: `.github/copilot-instructions.md` — plain Markdown, no frontmatter.
-- Path-specific: `.github/instructions/<name>.instructions.md` — frontmatter `applyTo:` (glob, e.g. `applyTo: "app/models/**/*.rb"` or `applyTo: "**"`) and optional `excludeAgent:` (`"code-review"` / `"cloud-agent"`).
-- Copilot code review reads only the first 4,000 characters of an instruction file (other features are unaffected). Keep them tight.
-- `AGENTS.md`, `CLAUDE.md`, and `GEMINI.md` are also recognized.
-
-**Variables documented by GitHub:** input variables only — `${input:name}` and `${input:name:placeholder}` (e.g. `${input:code:Paste your code here}`). The `${selection}`, `${file}`, and `${workspaceFolder}` tokens come from VS Code's editor, not GitHub's spec — fine in VS Code, not portable.
-
-## Cursor
-
-**Commands** (lightly documented; Cursor now steers users toward Skills):
-- Location: `.cursor/commands/<name>.md` (project). A user-level form exists but Cursor doesn't publish the exact global path — don't quote one.
-- No documented frontmatter; commands are described simply as reusable prompts.
-- No documented argument/parameter passing.
-- Invoke: type `/` in the Agent input and pick the command.
-
-**Skills (preferred going forward):** `SKILL.md`-based, same shape as the convergence example above. Cursor ships `/migrate-to-skills` to convert commands.
-
-**Rules** (passive context, auto-injected — not invoked like commands):
-- Location: `.cursor/rules/` as `.md` or `.mdc`. Use `.mdc` for frontmatter.
-- Frontmatter: `description` (string), `globs` (file pattern), `alwaysApply` (boolean).
-- Types: **Always** (`alwaysApply: true`), **Agent Requested** (description, no globs — pulled in when relevant), **Auto Attached** (matches `globs`), **Manual** (only via `@`-mention).
-
-## Quick pick
-
-| You want… | Claude Code | GitHub Copilot | Cursor |
-|---|---|---|---|
-| Invoke a saved prompt by name | `.claude/skills/<name>/SKILL.md` → `/name` | `.github/prompts/<name>.prompt.md` → `/name` | `.cursor/commands/<name>.md` → `/name` |
-| Always-on project context | `.claude/skills/` (auto-invoked) or `CLAUDE.md` | `.github/copilot-instructions.md` | `.cursor/rules/*.mdc` |
-| Path-scoped context | `paths:` frontmatter | `.github/instructions/*.instructions.md` (`applyTo`) | `.cursor/rules/*.mdc` (`globs`) |
-
-When in doubt, write a `SKILL.md` — it's the format all three are converging on.

package/skills/meta/writing-prompts/skill.json

@@ -1,9 +0,0 @@
-{
-    "version": "1.0.0",
-    "name": "superpowers:meta/writing-prompts",
-    "title": "writing-prompts",
-    "aliases": [
-        "writing-prompts",
-        "meta/writing-prompts"
-    ]
-}

package/skills/problem-solving/ABOUT.md

@@ -1,40 +0,0 @@
-# Problem-Solving Skills - Attribution
-
-These skills were derived from agent patterns in the [Amplifier](https://github.com/microsoft/amplifier) project.
-
-**Source Repository:**
-- Name: Amplifier
-- URL: https://github.com/microsoft/amplifier
-- Commit: 2adb63f858e7d760e188197c8e8d4c1ef721e2a6
-- Date: 2025-10-10
-
-## Skills Derived from Amplifier Agents
-
-**From insight-synthesizer agent:**
-- simplification-cascades - Finding insights that eliminate multiple components
-- collision-zone-thinking - Forcing unrelated concepts together for breakthroughs
-- meta-pattern-recognition - Spotting patterns across 3+ domains
-- inversion-exercise - Flipping assumptions to reveal alternatives
-- scale-game - Testing at extremes to expose fundamental truths
-
-**From ambiguity-guardian agent:**
-- (architecture) preserving-productive-tensions - Preserving multiple valid approaches
-
-**From knowledge-archaeologist agent:**
-- (research) tracing-knowledge-lineages - Understanding how ideas evolved
-
-**Dispatch pattern:**
-- when-stuck - Maps stuck-symptoms to appropriate technique
-
-## What Was Adapted
-
-The amplifier agents are specialized long-lived agents with structured JSON output. These skills extract the core problem-solving techniques and adapt them as:
-
-- Scannable quick-reference guides (~60 lines each)
-- Symptom-based discovery via when_to_use
-- Immediate application without special tooling
-- Composable through dispatch pattern
-
-## Core Insight
-
-Agent capabilities are domain-agnostic patterns. Whether packaged as "amplifier agent" or "superpowers skill", the underlying technique is the same. We extracted the techniques and made them portable.

package/skills/problem-solving/collision-zone-thinking/SKILL.md

@@ -1,188 +0,0 @@
----
-name: collision-zone-thinking
-description: Force unrelated concepts together to discover emergent properties — "What if we treated X like Y?" Use this skill whenever someone says they're stuck, need a breakthrough idea, want to think outside the box, feel like they've exhausted options in their domain, or need innovation rather than optimization. Also use it when a user asks how a well-known software pattern (circuit breakers, MapReduce, reactive programming, event sourcing) was originally invented — these are all cross-domain collisions. Trigger any time someone needs a novel angle on a hard problem.
----
-
-# Collision-Zone Thinking
-
-## Overview
-
-Revolutionary insights come from forcing unrelated concepts to collide. The cognitive science behind this is real: **bisociation** (Koestler), **conceptual blending** (Fauconnier & Turner), and TRIZ's cross-domain patent analysis all confirm the same mechanism — breakthrough thinking requires connecting two previously separate frames of thought, not finding better answers within a single frame.
-
-**Core principle:** Import the *mechanism*, not the metaphor. You're not renaming things. You're borrowing how a different system solves the same structural problem.
-
-> For historical evidence that this technique produces real results — Bloom filters, MapReduce, the Actor model, circuit breakers, consistent hashing, event sourcing — see `references/historical-examples.md`.
-
----
-
-## Quick Reference: High-Yield Domain Pairs
-
-| Problem Type | Source Domain | Key Mechanisms to Import |
-|-------------|---------------|--------------------------|
-| Distributed failures | Electrical circuits | Circuit breakers, grounding, load balancing |
-| Service discovery | Ant colonies | Stigmergy, pheromone trails, positive feedback |
-| Caching / memory | Immune system | Memory cells, tolerance, autoimmunity as bugs |
-| Load shedding | Emergency triage | Priority queues, do-not-resuscitate patterns |
-| Code evolution | Natural selection | Fitness landscape, punctuated equilibrium, drift |
-| API design | Linguistics | Syntax vs. semantics, pragmatics, ambiguity |
-| Security / access | Epidemiology | Vectors, quarantine, herd immunity, patient zero |
-| Team structure | Ecology / niches | Keystone species, competitive exclusion, succession |
-| Rate limiting | Fluid dynamics | Backpressure, throttle valves, laminar vs. turbulent |
-| Technical debt | Financial debt | Compound interest, default, debt restructuring |
-| Observability | Neuroscience | Proprioception, signal vs. noise, nociception |
-| Consensus | Democracy / voting | Quorum, veto power, majority vs. supermajority |
-| Data pipelines | Manufacturing | Bottlenecks, WIP limits, buffer overflow, just-in-time |
-| Optimization | Evolution / genetics | Fitness function, mutation, selection pressure |
-
----
-
-## Process
-
-### 1. Escape the Problem's Frame
-- State the problem in plain language
-- Identify its structural type: optimization? coordination? failure prevention? scaling? discovery?
-- Strip domain-specific vocabulary — find the structural bones
-- Ask: *"What is this problem really about?"*
-
-### 2. Select and Enter the Source Domain
-- Choose a domain that solves the same **structural problem type** (not the same surface domain)
-- Go deep enough to articulate **at least 5 mechanisms** — don't just name the domain, explain how it works
-- Ask: *"How does this system solve this type of problem?"*
-
-**Good source domains:** biology, ecology, electrical engineering, fluid dynamics, economics, military strategy, immunology, linguistics, thermodynamics, accounting.
-
-**Avoid:** adjacent tech domains (too similar), domains you barely understand (too shallow).
-
-### 3. Collide
-- Force the combination: *"What if we treated [A] like [B]?"*
-- Run it as a simulation — elaborate it forward, don't just state it
-- For each mechanism you listed, ask: *"What would the equivalent be in my domain?"*
-- Note **emergent properties** — things the blend implies that weren't in either input
-
-### 4. Test the Breakdown
-- Find where the metaphor breaks — it always does
-- Ask: *"What does the source domain have that my domain lacks?"* (potential to add)
-- Ask: *"What does my domain have that the source domain lacks?"* (constraints to respect)
-- **Treat the breakdown as signal, not failure.** Where the metaphor stops fitting reveals what's genuinely unique about your domain — and often points to the most important design decision.
-
-### 5. Extract
-- Name the concrete mechanisms you're borrowing
-- Generate at least one testable hypothesis or design change
-- Document breakdown points — they define the insight's scope
-
----
-
-## Evaluating the Collision
-
-| Question | What It Checks |
-|----------|---------------|
-| **Does the structural relationship map, or only the surface?** | Borrowing names is decoration; borrowing mechanisms is insight |
-| **Does the source domain reveal *why*, not just *what*?** | Causal mechanisms are what you're actually importing |
-| **Does the breakdown point reveal something useful?** | Productive breaks expose hidden constraints or design decisions |
-
-**Signs a collision is productive:** Emergent properties appear. You discover constraints you hadn't named. The source suggests experiments you wouldn't have thought of. The breakdown reveals a gap worth engineering around.
-
-**Signs a collision is superficial:** You're borrowing vocabulary, not mechanisms. You could have had the same insight without the analogy. No emergent structure appears — the blend is flat.
-
----
-
-## Worked Example 1: Circuit Breakers
-
-**Problem:** Complex distributed system with cascading failures
-
-**Escape:** This is a *failure propagation* problem — how to prevent one failing component from overloading others.
-
-**Source domain activated:** Electrical circuits
-- Mechanism 1: Circuit breakers disconnect on overload
-- Mechanism 2: Fuses provide one-time, non-recoverable protection
-- Mechanism 3: Grounding routes dangerous current safely away
-- Mechanism 4: Load balancing distributes current across paths
-- Mechanism 5: Isolation prevents short-circuit propagation between components
-
-**Collision:** *"What if we treated services like electrical circuits?"*
-
-**Emergent properties:**
-- Circuit breakers → automatic service disconnection when error rates spike
-- Grounding → dedicated error-sink services that absorb failures
-- Load balancing → traffic redistribution under stress
-- Series vs. parallel circuits → synchronous vs. async dependency graphs
-
-**Where it breaks:** Circuits don't have retry logic, state, or dynamic reconfiguration.
-
-**What the breakdown reveals:** Distributed systems have *memory* and *intent* that circuits lack — that's why retry logic, exponential backoff, and health checks exist. The breakdown is the specification for the Half-Open state that Michael Nygard invented — an entirely software-native concept with no electrical equivalent.
-
-**Insight extracted:** Borrow the three-state model (closed/open/half-open); add retry and health-check logic exactly where the analogy breaks.
-
----
-
-## Worked Example 2: Event Sourcing
-
-**Problem:** Distributed write-heavy systems need audit trails, temporal queries, and consistency — but mutable state makes all three hard.
-
-**Escape:** This is a *state history* problem — how to track what happened, when, and be able to reconstruct any past state.
-
-**Source domain activated:** Double-entry bookkeeping (accounting, ~1494)
-- Mechanism 1: Transactions are never modified, only appended to the ledger
-- Mechanism 2: Account balance is *derived* from history, not stored directly
-- Mechanism 3: Every change is recorded from two perspectives (debit and credit)
-- Mechanism 4: The complete ledger is the source of truth — summaries are projections
-- Mechanism 5: Audit trail is the data, not a separate system bolted on
-
-**Collision:** *"What if we treated our database like a ledger?"*
-
-**Emergent properties:**
-- Event store → complete replay of any past state (time travel)
-- Derived projections → different read models from the same event stream
-- Immutable log → audit trail for free, debugging by replay
-- Append-only writes → no write contention on past records
-
-**Where it breaks:** Schema evolution is hard (old events must be readable with new schemas), and replaying years of events to reconstruct current state is slow.
-
-**What the breakdown reveals:** Bookkeepers solved schema evolution via versioned document formats and transition rules — software systems need the same: event versioning and migration scripts. The "slow replay" breakdown is the specification for snapshot strategies. Both breakdowns have direct solutions.
-
-**Insight extracted:** Immutable event logs as primary data; projections as derived views; snapshots for performance; versioned schemas for evolution. This is the event sourcing pattern that underlies Kafka, CQRS, and git.
-
----
-
-## Common Pitfalls
-
-**Surface analogy trap:** Borrowing vocabulary but not mechanisms. "Let's call modules 'genes'" is renaming, not insight. Insight is: *"What would selection pressure mean for code? What would mutation rate mean? What would epistasis mean?"*
-
-**Stopping too early:** Generating the collision but not running it. Commit to 5–7 mechanisms before claiming the collision is complete.
-
-**Adjacent-domain trap:** Choosing source domains that are too similar — produces incremental thinking, not breakthrough. Physics, biology, and economics produce more insight than other tech systems.
-
-**Discarding breakdowns:** Treating metaphor failures as dead ends. Every breakdown is a signal about what's genuinely different in your domain — and that's where the deepest insight lives.
-
----
-
-## When to Reach for This
-
-- "I've tried everything in this domain"
-- Solutions feel incremental, not breakthrough
-- Need innovation, not optimization
-- The problem feels structurally familiar but solutions in this domain have stalled
-- You're asked how a well-known pattern (circuit breakers, MapReduce, event sourcing) was invented
-
----
-
-## Source Domain Selection Rubric
-
-Use this to assess if a domain is worth entering deeply:
-
-1. **Structural richness:** Does it have well-developed causal mechanisms, or just patterns?
-2. **Surface dissimilarity:** Is it genuinely alien to your problem domain? (More different = more novel)
-3. **Your familiarity:** Can you articulate 5+ mechanisms, or are you guessing?
-4. **Validated solutions:** Has this domain solved its problems under real pressure (evolution, markets, physics)?
-
-If you can't articulate 5 mechanisms from the source domain, go deeper before colliding.
-
----
-
-## Reference
-
-For 11 historical examples of real cross-domain collisions that became software foundations — with full collision-zone analysis for each — see:
-
-`references/historical-examples.md`
-
-Use them as templates, as evidence this technique produces real results, or as a starting inventory when you're selecting source domains.