{
  "markdown": "# Claude Code Workflows\n\nA Claude Code plugin: five-stage workflow for software work, built around the elephant/goldfish pattern from [Dave Rensin's article](https://drensin.medium.com/elephants-goldfish-and-the-new-golden-age-of-software-engineering-c33641a48874).\n\n> The **elephant** is your working session - Claude Code with full context: the conversation, CLAUDE.md, recent file reads, decisions already made. The **goldfish** is a fresh subagent with no prior context that stress-tests a problem doc, a design doc, or a diff. The asymmetry is the test: a goldfish that can't reach the same conclusion from the doc alone tells you the doc is wrong, not the goldfish.\n\n## Install\n\n`/plugin` command is **only** available in Claude CLI. Open `claude` in your terminal, and:\n\n**This repo's marketplace:**\n\n```\n/plugin marketplace add vshvedov/claude-code-workflows\n/plugin install elephant-goldfish@eg-workflow\n```\n\n> Note: `/plugin` runs inside a Claude Code session. If your terminal says \"/plugin isn't available in this environment,\" start `claude` first, then paste the commands at the prompt.\n\nFive skills become available, namespaced under `/elephant-goldfish:`:\n\n| Skill | When to use |\n|---|---|\n| `/elephant-goldfish:brainstorm <rough idea>` | Early-stage concept design. Multiple goldfish run in parallel with different lenses (technical / business / UX / contrarian / market research). Output: a concepts brief. |\n| `/elephant-goldfish:prd <idea \\| feature \\| #issue>` | Turn an idea into a Product Requirements Document. Codebase grounding, structured gap-filling, deep research. Output: a PRD with explicit Open Questions. |\n| `/elephant-goldfish:fix-bug <description \\| #issue \\| URL>` | Bug fix flow. Problem doc → goldfish diagnosis check → failing test → fix → precommit review → test gate. |\n| `/elephant-goldfish:new-feature <description \\| #issue \\| URL>` | Feature flow. Scope confirm → design doc → three-goldfish design check (readiness / critic / implementer) → implement → precommit review → test gate. |\n| `/elephant-goldfish:precommit-review` | Independent reviewer loop on the pending diff. Lint + typecheck + tests as pre-flight, then a fresh subagent reviews the diff cold. |\n\nImplementation skills (`fix-bug`, `new-feature`) stop short of committing. You authorize the commit explicitly.\n\nUsage examples:\n\n```sh\n/elephant-goldfish:fix-bug gh issue 42\n/elephant-goldfish:new-feature gh issue 67\n/elephant-goldfish:precommit-review\n/elephant-goldfish:brainstorm \"I have a an idea, but I don't know what to do with it.\"\n/elephant-goldfish:prd \"I need to implement X in Y, here is the description.\"\n```\n\n## The pipeline\n\n> `brainstorm` produces a **concept**. `prd` turns a concept into **requirements**. `new-feature` and `fix-bug` produce **code**. `precommit-review` produces **validated code**. Each upstream stage feeds the next.\n\n```mermaid\nflowchart LR\n    R([\"rough idea\"]) --> A[\"brainstorm\"]\n    A -- concept --> B[\"prd\"]\n    B -- PRD --> C[\"new-feature\"]\n    BG([\"bug, issue, repro\"]) --> D[\"fix-bug\"]\n    C -- code change --> E[\"precommit-review\"]\n    D -- code change --> E\n    E -- validated change --> F([\"commit\"])\n```\n\nYou don't have to start at the top. Pick the stage that matches what you have:\n\n| You have | Start with | The output |\n|---|---|---|\n| A half-formed thought, no direction yet | `brainstorm` | A concepts brief; pick a direction. |\n| A direction but no requirements | `prd` | A PRD: scope, users, metrics, open questions. |\n| A clear feature to build | `new-feature` | Implemented + reviewed code, ready to commit. |\n| A bug or a `#<issue>` | `fix-bug` | A failing-test-driven fix, ready to commit. |\n| A diff already in hand | `precommit-review` | A reviewer-cleared diff, ready to commit. |\n\n## How each skill uses the pattern\n\n- **`brainstorm`** inverts the pattern. Multiple goldfish run in parallel, each with a different lens, free to web-search. The elephant synthesizes the divergent ideas into a concepts brief. All clarifying questions go through `AskUserQuestion`.\n- **`prd`** uses two waves: exploration goldfish ground the request in the existing codebase, then research goldfish run in parallel across distinct lenses (web search, optional Chrome MCP for logged-in sources). The elephant synthesizes a PRD with explicit Open Questions for whatever the user deferred.\n- **`new-feature`** uses **three** goldfish per round: comprehension (does the doc read cleanly to a cold reader?), critic (where does the design break?), readiness (could a first-pass implementer ship this without follow-up questions?). A no-code gate holds until critic AND readiness sign off; comprehension is informational. Round 2+ skips comprehension.\n- **`fix-bug`** uses one goldfish to diagnose from only the symptom and repro. The elephant's hypothesis stays hidden; convergence buys confidence, divergence is signal. The bug is captured as a failing test before any fix.\n- **`precommit-review`** is itself a goldfish. Sees only the diff, not the conversation. Findings triaged round by round with a hard cap and an `AskUserQuestion` escalation if the loop doesn't converge.\n\n## Workflows\n\nEach skill structures a different elephant↔goldfish dance. The diagrams below show the message flow. The **elephant** is your Claude Code session — full context, institutional memory. A **goldfish** is a fresh subagent spawned with no shared context, receiving only what the elephant hands it. The **user** is you, kept in the loop via `AskUserQuestion` at decision points.\n\n### `brainstorm`\n\n**Inverts the pattern.** Multiple goldfish run in **parallel**, each on a different lens (technical, business, UX, contrarian, market research). Their lack of shared context is what makes them generate divergent ideas. The elephant synthesizes the divergent output into a concepts brief and helps the user converge on a direction.\n\n**Output:** a clusters → ranked picks → open questions brief; optional handoff to `/elephant-goldfish:new-feature`.\n\n```mermaid\nsequenceDiagram\n    autonumber\n    participant U as User\n    participant E as Elephant\n    participant G1 as Goldfish (Technical)\n    participant G2 as Goldfish (Business)\n    participant G3 as Goldfish (UX)\n    participant Gn as Goldfish (Contrarian/Market)\n    participant GC as Contrarian sweep\n\n    U->>E: rough idea\n    E->>U: Q1 stage / Q2 breadth / Q3 web research\n    U->>E: framing answers\n    E->>U: SEED (problem statement)\n    U->>E: approve / refine / restart\n\n    par Divergent lenses (parallel)\n        E->>G1: SEED + Technical lens\n        E->>G2: SEED + Business lens\n        E->>G3: SEED + UX lens\n        E->>Gn: SEED + Contrarian/Market lens\n    end\n    G1-->>E: concepts (lens complete)\n    G2-->>E: concepts (lens complete)\n    G3-->>E: concepts (lens complete)\n    Gn-->>E: concepts (lens complete)\n\n    opt Breadth = ~10 / ~20\n        E->>GC: SEED + dedup'd concepts (\"what did they all miss?\")\n        GC-->>E: 2-3 outsider concepts\n    end\n\n    E->>E: cluster, rank, surface convergence/divergence\n    E->>U: CONCEPTS BRIEF + ranked picks\n    U->>E: pick / re-run / save / drop\n    opt Handoff\n        E-->>U: \"Run /elephant-goldfish:new-feature <concept> when ready\"\n    end\n```\n\n---\n\n### `prd`\n\n**Two waves of goldfish.** Wave 1 grounds the request in the existing codebase (parallel exploration goldfish). Wave 2 — after structured gap-filling Q&A with the user — runs research goldfish in parallel across distinct lenses. The elephant synthesizes a PRD with explicit Open Questions for whatever the user deferred.\n\n**Output:** a PRD (executive summary, scope, requirements, metrics, risks, open questions, sources); optional save to disk and/or handoff to `/elephant-goldfish:new-feature`.\n\n```mermaid\nsequenceDiagram\n    autonumber\n    participant U as User\n    participant E as Elephant\n    participant GA as Goldfish (Existing surfaces)\n    participant GB as Goldfish (Architecture)\n    participant R1 as Goldfish (Market/Prior art)\n    participant R2 as Goldfish (Technical patterns)\n    participant R3 as Goldfish (UX/Compliance/Perf)\n\n    U->>E: idea or #issue\n    E->>U: Q1 depth / Q2 research / Q3 output target\n    U->>E: framing answers\n\n    par Wave 1 — codebase grounding\n        E->>GA: find closest existing surfaces\n        E->>GB: read CLAUDE.md, manifests, conventions\n    end\n    GA-->>E: file:line citations\n    GB-->>E: stack, constraints, patterns\n    E->>U: CODEBASE BRIEF + numbered gap list (G1..Gn)\n\n    U->>E: which gaps to fill\n    loop For each selected gap\n        E->>U: structured Q (3-5 plausible answers + Defer/Other)\n        U->>E: answer or defer\n    end\n\n    par Wave 2 — research lenses (parallel)\n        E->>R1: SEED + brief + answered gaps (Market lens)\n        E->>R2: SEED + brief + answered gaps (Technical lens)\n        E->>R3: SEED + brief + answered gaps (UX/Compliance lens)\n    end\n    R1-->>E: findings + sources (lens complete)\n    R2-->>E: findings + sources (lens complete)\n    R3-->>E: findings + sources (lens complete)\n\n    E->>E: synthesize PRD (deferred gaps → Open Questions)\n    E->>U: full PRD\n    U->>E: approve / refine sections / restart\n    opt Output\n        E->>E: write to disk / memory\n        E-->>U: \"Run /elephant-goldfish:new-feature <summary> when ready\"\n    end\n```\n\n---\n\n### `new-feature`\n\n**Three goldfish per round** stress-test the design doc the elephant drafted. Comprehension (does the doc read cleanly to a cold reader?), Critic (what gaps?), Readiness (could a first-pass implementer ship this without asking any questions?). A **no-code gate** holds until BOTH Critic and Readiness sign off (`design ready` + `implementation ready`). Round 2+ skips Comprehension. Implementation only starts after the gate closes; then the diff goes through `/elephant-goldfish:precommit-review`.\n\n**Output:** implemented + reviewed code, ready for the user to commit.\n\n```mermaid\nsequenceDiagram\n    autonumber\n    participant U as User\n    participant E as Elephant\n    participant PA as Goldfish A (Comprehension)\n    participant PB as Goldfish B (Critic)\n    participant PC as Goldfish C (Readiness)\n    participant PR as /elephant-goldfish:precommit-review\n\n    U->>E: feature description or #issue\n    E->>U: scope confirmation (1-2 sentences)\n    U->>E: confirm / correct\n    E->>U: DESIGN DOC (no code yet — gate is closed)\n\n    rect rgb(245,245,245)\n    Note over E,PC: Round 1 — all three passes\n    par Three-goldfish design check\n        E->>PA: design doc only (cold reader paraphrase)\n        E->>PB: design doc only (find gaps)\n        E->>PC: design doc only (executable in one pass?)\n    end\n    PA-->>E: \"comprehension passed/unclear\"\n    PB-->>E: gaps + \"design ready\" or \"design needs revision\"\n    PC-->>E: open questions + \"implementation ready\" or \"not ready\"\n    end\n\n    alt Both Critic & Readiness sign off\n        Note over E: Gate opens — implementation allowed\n    else Gaps remain\n        loop Up to 3 revisions (skip Pass A)\n            E->>E: revise doc, address every gap or rebut verbatim\n            E->>U: revised doc\n            par\n                E->>PB: revised doc\n                E->>PC: revised doc\n            end\n            PB-->>E: gaps / design ready\n            PC-->>E: questions / implementation ready\n        end\n        opt Still not converging\n            E->>U: stop — feature under-specified, need direction\n        end\n    end\n\n    E->>E: implementation plan (layer-ordered)\n    E->>E: implement layer by layer with per-layer verification\n    E->>PR: hand off diff for independent review\n    PR-->>E: rounds, fixes, rebuttals\n    E->>E: run test gate + UI walkthrough (golden + edge case)\n    E->>U: final report (STOP — no commit)\n```\n\n---\n\n### `fix-bug`\n\n**One goldfish diagnoses the bug** from only the symptom + repro. The elephant's hypothesis stays hidden until after the goldfish reports — convergence buys confidence; divergence is signal worth investigating. The bug gets captured as a **failing test before any fix is written**. Then the same diff goes through `/elephant-goldfish:precommit-review`.\n\n**Output:** failing-test-driven fix, ready for the user to commit.\n\n```mermaid\nsequenceDiagram\n    autonumber\n    participant U as User\n    participant E as Elephant\n    participant GD as Goldfish (Diagnosis)\n    participant PR as /elephant-goldfish:precommit-review\n\n    U->>E: bug description / #issue / URL\n    opt Triviality gate (typo, formatter, version bump)\n        E->>PR: skip ceremony, go straight to review\n    end\n\n    E->>E: PROBLEM DOC (symptom, repro, hidden hypothesis, \"fixed means\")\n    opt No repro provided\n        E->>U: ask for repro path (URL, steps, log line)\n        U->>E: repro details\n    end\n\n    Note over E,GD: Asymmetry: goldfish gets symptom + repro only,<br/>NOT the elephant's hypothesised root cause\n    E->>GD: investigate, rank candidate root causes (no fix)\n    GD-->>E: top 1-3 candidates with file:line + falsifying evidence\n\n    alt Convergence — goldfish matches elephant hypothesis\n        Note over E: Proceed with confidence\n    else Divergence\n        E->>E: re-investigate, update problem doc if goldfish is right\n        E->>U: surface — goldfish flagged a different root cause\n    end\n\n    E->>E: write failing test capturing the bug\n    E->>E: run test — must fail for the right reason\n    E->>E: smallest fix that turns it green (no adjacent refactors)\n    E->>E: re-run test — must go green\n\n    E->>PR: hand off diff\n    PR-->>E: rounds, fixes, rebuttals\n    E->>E: test gate + re-verify original repro\n    E->>U: final report (root cause, fix, test, goldfish agreement) — STOP\n```\n\n---\n\n### `precommit-review`\n\n**The reviewer is itself a goldfish.** It sees only the diff, not the conversation, not the implementation intent, not what the elephant was trying to do. Findings are triaged round by round: **fix or rebut verbatim** (no silent dismissals). The loop runs until `no findings` AND every prior-round finding is settled, with a **hard cap of 5 rounds** and structured user escalation if it doesn't converge.\n\n**Output:** a reviewer-cleared diff with every rebuttal surfaced verbatim to the user.\n\n```mermaid\nsequenceDiagram\n    autonumber\n    participant U as User\n    participant E as Elephant\n    participant GR as Goldfish (Reviewer)\n\n    Note over E: Pre-flight: lint, typecheck, unit, e2e, codegen<br/>(sequential, not chained — new errors only are blockers)\n\n    rect rgb(245,245,245)\n    Note over E,GR: Loop — hard cap 5 rounds\n    loop Round N\n        E->>GR: EXACT template (no intent leakage) + focus area if any\n        Note over GR: Reads git status / diff / diff --cached /<br/>diff main...HEAD / log, reads touched files in full\n        GR-->>E: numbered findings (file:line + why + fix) OR \"no findings\"\n        E->>E: triage each finding — fix or rebut verbatim\n        E->>U: ledger — open findings going into round N+1\n        opt All settled AND \"no findings\"\n            Note over E: Exit loop\n        end\n    end\n    end\n\n    alt Hit 5-round cap or repeat finding at same file:method\n        E->>U: AskUserQuestion — accept / keep working / abandon\n        U->>E: choice\n    end\n\n    E->>U: final report (rounds, fixes, rebuttals VERBATIM) — STOP, no commit\n```\n\n## Stack support\n\nThe plugin is **stack-agnostic**. On every invocation the skill reads your repo's manifests (`package.json`, `Gemfile`, `pubspec.yaml`, `pyproject.toml`, `go.mod`, etc.), version managers (`mise.toml`, `.tool-versions`, `.nvmrc`), CI config (`.github/workflows/`), and `CLAUDE.md` itself, then picks the right lint / typecheck / test / e2e commands for that repo. No install-time configuration.\n\nTested patterns include Rails (with mise + Brakeman + MiniTest), Flutter (with build_runner + Drift), Node + Vite + Cloudflare Workers, Python (Django / FastAPI), and Go.\n\n## Project-specific commands\n\nThe skills include a routing hint in `new-feature`: if your repo has its own stack-specific commands (e.g. `/new-module`, `/new-migration`, `/new-worker`), the skill suggests them instead of running its generic feature flow. Project-specific commands stay in your `.claude/commands/` and don't need to be part of this plugin.\n\n## Local development\n\n```sh\ngit clone https://github.com/<your-fork>/elephant-goldfish-plugin\ncd /path/to/your-test-repo\nclaude --plugin-dir /path/to/elephant-goldfish-plugin/plugins/elephant-goldfish\n```\n\nInside the session:\n\n```\n/elephant-goldfish:precommit-review\n```\n\nThe skill should detect your test repo's stack and run the appropriate lint / test sequence.\n\n## License\n\n[MIT](LICENSE).\n",
  "bytes": 16550,
  "sha": "c7c77317371e5719d931e43f1880d2e65bfb5058440f0105b09dc75ff37df73c",
  "repo_slug": "vshvedov/elephant-goldfish-plugin",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_vshvedov_elephant_goldfish_plugin_elepha_419058a5/readme"
}