ldsAS/elephant-goldfish-skill

🐘🐟 Elephant & Goldfish Development Pattern

📌 Overview

• 🐘 Elephant (Coordinator, that's you): Has the full picture memory. Responsible for communication, writing CUJ specs, assigning tasks, and reviewing results. Does not write code themselves, does not run tests themselves.
• 🐟 Goldfish (Coder / Tester / Reviewer): A stateless sub-agent with zero history baggage. Only acts based on the CUJ, completes the task and is discarded, avoiding context pollution.

---

🚦 Step 0: Decide Whether This Task Should Follow This Flow

This is the first decision. Do not skip it.

Task Type	Follow This Flow?
New feature or module	✅
Modifying behavior of existing functionality	✅
Refactoring involving external interface changes	✅
Bug fix requiring logic changes	✅
Pure documentation updates (README, comments)	❌
Code formatting / lint	❌
Dependency version upgrades (no behavior change)	❌
Configuration tweaks	❌
Emergency hotfix (critical bug in production)	❌ Fix directly, must add Tester validation afterward

Default when unsure: Change ≤ 10 lines and does not alter any externally observable behavior → do not follow the flow.

❌ When not applicable, just follow the project's existing rules, do not mention this Skill, and do not write a CUJ just to go through the motions.

---

🎯 Core Principles

1. Goldfish Test Standard: A brand new sub-agent (goldfish), relying only on the CUJ document, must be able to independently complete the Explain → Implement → Test entire flow. If it cannot, it means the spec is not good enough, not that the AI is not smart enough.
2. Strict Role Separation: The person writing the code (Coder) cannot grade their own test (Tester / Reviewer).
3. Spec + Test: The CUJ defines what is wanted, the test proves it has been obtained. If either is missing, the CUJ degenerates into a document for humans, not an executable contract for the goldfish.
4. Trust the Script, Not Just Markdown: Use scripts/validate_cuj.py for objective checks, not self-perception.

---

🚀 Flow

Step 1: Load Reference Materials as Needed

Do not read everything at once. Load based on current actual need. This is key to progressive disclosure:

When to Read	Which Document to Read
Before dispatching a goldfish (required)	references/dispatch-prompts.md
Unsure whether a role can do something	references/role-separation.md
Unsure how detailed a CUJ should be, or validation keeps failing	references/cuj-workflow.md
When starting to write a CUJ	assets/cuj-template.md (format)assets/cuj-001-user-login.md (quality benchmark)
If using a tool without sub-agent mechanisms	Cross-tool mapping table in references/role-separation.md

Step 2: Write the CUJ

• Follow the template format, save to the project's cuj/ directory with filename cuj-XXX-short-description.md
• The id in the frontmatter must match the filename prefix (see Gotchas)
• If requirements are ambiguous, clarify before writing — see step 2 of cuj-workflow.md for clarification mechanisms (outside this Skill's scope)

Step 3: Validate the CUJ (Objective Gate)

python .agent-skills/elephant-goldfish/scripts/validate_cuj.py cuj/

• exit code 0 allows proceeding to Step 4
• Non-zero → fix the CUJ based on the error message, rerun until it passes, do not bypass
• After passing, still ask yourself the goldfish test question — the script checks structure, this question checks usability

Step 4: Dispatch Goldfish and Converge

Before dispatching, must read the "❌ Do Not Include" list in references/dispatch-prompts.md. Role separation most often breaks at the moment of dispatch.

Execute sequentially, do not parallelize, do not merge roles:

• 4a. Dispatch Coder — Only give the CUJ path and the path to the file to be modified, not the conversation history
• 4b. Dispatch Tester (independent sub-agent) — Only give the acceptance criteria and test cases from the CUJ, not the Coder's implementation explanation or output summary
• 4c. On Test Failure — Hand the failure message to a new Coder goldfish to fix, then go back to 4b and retest. Do not let the same Coder repeatedly fix until it passes; that is equivalent to letting it grade its own test
• 4d. Dispatch Reviewer (independent sub-agent, optional) — Only give the code path and acceptance criteria, not the Tester's results
• 4e. Coordinator Consolidation — Update the CUJ's status, report actual results to the user

Convergence Condition: Every acceptance criterion has a corresponding test and all pass.

Failure Limit: If the 4b ↔ 4c loop for the same CUJ runs 3 full iterations without convergence → stop blind fixing, go back to Step 2 and examine the CUJ itself for issues (contradictory specs, untestable acceptance criteria, missing preconditions).

---

⚠️ Gotchas

Environmental facts you will trip over if you don't know them:

• id must match the filename prefix — id: cuj-001 must correspond to cuj-001-*.md, mismatch leads to immediate fail
• Directory mode only scans cuj-*.md — Misspelled filenames (e.g., cju-001-x.md) will be listed as "skipped" not "failed", pay attention to the skip list in the output
• Section content threshold varies by language — 10 characters for CJK text, 30 characters for pure Western text, evaluated per section. Override with --min-section-chars N
• Validation script requires Python 3.12+, even if the project itself is not a Python project
• Skipped does not equal Passed — look at the Passed count in the summary line, not just whether ✅ is printed
• Script only validates structure, not semantics — It should work correctly is structurally identical to a concrete acceptance criterion and will pass the script. The script is the floor; the goldfish test checkpoint is the ceiling

---

🛑 Anti-Rationalization & Red Flags

Scope: The following rules only apply when following this flow for feature development, not as all-time iron laws. Operations checks, pre-deployment validation, and emergency hotfixes follow the project's existing rules. If conflicts arise with existing project norms during adoption, resolve by domain separation, not by overriding each other.

• ❌ Absolutely forbidden for the Coordinator to personally write changes exceeding 10 lines, or to personally execute test commands.
• ❌ Absolutely forbidden to copy the Coder's implementation context to the Tester. The Tester must test independently based on the CUJ acceptance criteria in a clean context.
• ❌ Absolutely forbidden to consider a validation as passed just because the script printed ✅ — check the Passed count in the summary line.
• ❌ Absolutely forbidden to modify tests or relax acceptance criteria just to make tests pass. Test failures are valuable information.

For more common excuses and rebuttals, see the Anti-Rationalization table in references/role-separation.md.

---

🔲 Scope of Responsibility

This Skill is only responsible for the Elephant & Goldfish mechanism itself, not the entire development lifecycle:

Stage	This Skill	Description
① Define Requirements	Out of scope	Human responsibility
② Clarify Requirements	Out of scope (Defining the Contract)	Each tool pairs independently, see step 2 of cuj-workflow.md
③ Produce CUJ	✅ Core	CUJ template + validate_cuj.py
④ Develop	✅ Core	Four-role separation + dispatch prompt templates
⑤ Post-mortem	Out of scope	Native tool mechanisms (e.g., Claude Code memory)

One Skill does one thing. There are mature standalone skills for requirements clarification and learning consolidation; reinventing them adds no value.

---

⚙️ Prerequisites

Item	Requirement
scripts/validate_cuj.py, scripts/install.py	Python 3.12+ (zero third-party packages)
Skill self-test	pytest

The above are the Skill itself's execution requirements, unrelated to the technology stack of the project using this Skill.