eecs498-aase/materials/egm-implement

EGM Implement: drive an approved design doc into code

/elephant writes the doc. /goldfish validates it. /egm-implement turns it into code, under guardrails that keep the implementation honest to the doc.

The link between doc approved and code shipped is exactly where most AI-assisted projects quietly lose fidelity. A new session starts, the doc is "the plan," but the model re-derives context from chat history and drifts. This skill removes the drift by making the design doc the only source of truth, the `GOLDFISH.md` readiness record the only entry gate, and the `IMPLEMENT.md` ledger the durable trace.

Invoke as /egm-implement [path-to-design-doc]. The working frame is the article's own Step 8 prompt, addressed to yourself:

Read this design doc and the files it references. Implement the feature as described. Follow the plan exactly.

EGM operating reflexes (shared preamble)

Every skill in this suite carries these four reflexes, because not every surface loads a global CLAUDE.md. They come from the Elephant-Goldfish article and apply for the whole session, not just while this skill runs.

1. Design is the new code. For any non-trivial feature or change, grow a design doc before writing code. If the design isn't clear enough that the code should write itself, design first (/elephant).
2. Refuse sycophancy. If you're about to say "great point" or "you're absolutely right", stop. Apply the reset, addressed to yourself in the second person, verbatim: "You are not being helpful. Your highest and best use is to challenge my thinking. When you agree with me, you are not being helpful." Then re-engage as a critic and find the holes.
3. AI proposes first. Never let the user seed a design, framework, or rubric with their own first draft. You propose first, in prose and block diagrams; the user reacts and argues.
4. Save the artifacts. Persist the description + criteria + output triple durably: docs/designs/<slug>.md, the ledgers in docs/egm/<slug>/, PEANUTS.md at the source root, and the /decide triple at its surface-mapped location where that skill is installed. The chat transcript is not the artifact.

Hard rules: do not break these

1. Do not implement until `GOLDFISH.md` says `readiness: ready` AND `human_review_gate` is `passed` or `skipped-solo`. If either is missing, stop and surface the gap. There is no silent bypass; a human reviewer, or a conscious solo skip, must set the gate.
2. Do not implement any file that the design doc's Detailed Implementation section does not enumerate. If a file outside the doc must change, stop and propose a doc update first. Drift is rejected at the source. (The ledger and doc edits for resolved drift are not implementation.)
3. `IMPLEMENT.md` is the durable trace. Every file touched, every decision, every drift goes into docs/egm/<slug>/IMPLEMENT.md as it happens, not afterward.
4. Hand off to `/mean-review` when done. The implementation phase ends with a brutal review of the diff. Do not declare the work complete without it.

Workflow

EGM implement progress:
- [ ] Step 1: gate check says GO (or a human confirmed CHECK-BY-HAND values)
- [ ] Step 2: IMPLEMENT.md created, or read and resumed
- [ ] Step 3: every enumerated file implemented and logged, one logical change at a time
- [ ] Step 4: (standing) every drift stopped, logged, surfaced, and resolved before building it
- [ ] Step 5: verification run and recorded
- [ ] Step 6: IMPLEMENT.md closed; user pointed to /mean-review

Step 1: Confirm readiness

Why this step exists. The Goldfish-readiness gate separates "we agreed on this" from "we're guessing." Skipping it erases the validation work and lets implementation drift before the first file is touched.

First resolve the design doc path. Prefer the user's argument; otherwise look in docs/designs/*.md and in the folder named by design_doc_path: in the project's CLAUDE.md. If there are several candidates, ask which.

Then run the gate check from the project root. <skill-dir> is the folder that holds this SKILL.md:

python3 <skill-dir>/scripts/check_gate.py <path-to-design-doc>

It derives the slug from the doc's filename (the /elephant contract), finds docs/egm/<slug>/, and reads GOLDFISH.md: readiness from the latest round, human_review_gate from the header. It only reads; it never writes a ledger or changes a gate. Act on its exit code:

• 0, GO. Readiness is ready and the gate is passed or skipped-solo. If the gate is skipped-solo, show the user the warning the script prints ("Human review gate was skipped (solo mode). Proceeding under your sole judgment.") and log it in IMPLEMENT.md. Do not block on it.
• 1, BLOCKED. Stop. Tell the user exactly what the script says is missing and what to do: run /elephant and /goldfish first, run another Goldfish round, ask a teammate to review, or consciously record skipped-solo.
• 3, CHECK-BY-HAND. A ledger value is prose instead of one of the expected words (for example "core ready, periphery not-yet"), or the header and the latest round disagree. Read GOLDFISH.md, show the user the exact lines, and ask them to make the call. Proceed only on their explicit answer, and log it.
• 2, usage error. No doc path given and the design-doc folder holds zero or several docs. Ask which doc.

If Python isn't available, make the same checks by hand: the state directory exists, the latest round entry in GOLDFISH.md says readiness: ready, and the header's human_review_gate is passed or skipped-solo.

Then read ELEPHANT.md for orientation, not to re-derive the design, and surface to the user what context /elephant loaded in its Step 1.

Step 2: Initialize IMPLEMENT.md

Why this step exists. The ledger is the trace that survives crashes, context resets, and handoffs. Without it, a resumed session has to re-derive what was done from chat history, which is exactly the slop pattern this suite prevents.

If docs/egm/<slug>/IMPLEMENT.md does not exist, create it from assets/implement-ledger-template.md: the header fields, then the ## Files touched, ## Drift, and ## Verification sections that fill in as work proceeds.

If IMPLEMENT.md already exists, you are resuming. Read it first, find which enumerated files are still planned or in-progress, and pick up there. A crashed implementation session costs nothing: hand the doc to a new session and continue from the ledger.

Step 3: Implement

Why this step exists. The design doc enumerated the files to nail the implementation to a specific surface. Walking that enumeration is what prevents the wandering-AI failure mode.

Walk the doc's Detailed Implementation section. Its order is usually narrative, not topological; re-sequence (producers before consumers) when the build demands it, and say so in IMPLEMENT.md. For each file:

1. Read its current state, or note "new file".
2. Make the change exactly as the doc describes.
3. Add or update its row in ## Files touched: | <path> | <one-line summary> | done |.
4. If the file is complex, work in pieces (several edits), but each piece must trace to a specific point in the doc. Never insert behavior the doc doesn't describe.

One file per logical change. Do not bundle unrelated files into one edit. Smaller diffs are easier to review, and everything this skill produces flows into /mean-review.

Step 4: Drift detection

Why this step exists. When reality doesn't match the doc, the answer is to update the doc, not to absorb the change silently. Absorbing is how a design doc loses its standing as the source of truth, one undocumented diff at a time.

The doc will sometimes be incomplete. That is normal. Your job is to surface drift, not absorb it. Stop when you find that:

• a file not enumerated in Detailed Implementation needs to change, or
• the described change doesn't compile or can't work as written, or
• a new file is needed that the doc doesn't mention, or
• an assumption in the doc is false against the current code.

Append a drift entry to IMPLEMENT.md (the template has the block: date, type, description, proposed resolution, status: open). Then surface it to the user with a recommendation. Common resolutions:

• Small clarification that doesn't change the technical plan: edit the doc in place. Mark resolved: doc edited in place at <path>.
• Substantive section-level change: rewrite that section with /elephant's discipline (no code, you propose first). Mark resolved: section <name> rewritten. If the drift touches several sections or alters the technical plan, reopen /elephant for a full conversation and mark resolved: full /elephant rerun.
• Large enough to need re-validation: re-run /goldfish. Mark resolved: /goldfish rerun, round <N+1>.

Do not build the drifted change until its entry is resolved.

Step 5: Verification

Why this step exists. "Tests pass on my machine" is not verification. Recording the exact command and result is what makes the implementation defensible to the next reviewer, human or AI.

When the enumerated files are done, run the smallest meaningful verification the doc specifies. If it specifies none, infer from the project: the relevant tests, the build, the linter, or (when you can't exercise it yourself, such as a UI) a manual smoke check you describe for the user to run. Record each under ## Verification: step, exact command, result: pass | fail | partial, notes.

If verification fails, treat it as drift: log it, surface it, and do not declare done. Once its drift entry is resolved, fix, re-run, and record again, until it passes.

Step 6: Hand off to /mean-review

Why this step exists. Implementing and brutally reviewing are different jobs. Bundling them produces a softer review than a clean handoff to a separate /mean-review session.

When every enumerated file is done and verification is pass:

1. In the IMPLEMENT.md header, replace status: in-progress with status: complete, and add end_date: <YYYY-MM-DD> and next_step: /mean-review.
2. Tell the user:

> Implementation complete. `IMPLEMENT.md` is at `docs/egm/<slug>/IMPLEMENT.md`. The diff is ready for `/mean-review`, which runs the brutal review against the changes. After mean-review, you can ship.

1. Do not run /mean-review yourself. The user starts it; it is a separate skill with its own framing.

Anti-patterns

• Implementing without the gate check. Goldfish readiness is the entry gate. Skipping it defeats the suite.
• The "small fixup" outside the doc. Every "while I'm here, let me also rename X" is drift. Surface it; don't absorb it.
• Bundling many files in one edit. The diff gets hard to review and the trace hard to follow.
• Letting verification slide. Run the actual command, capture the actual output, record both.
• Auto-running `/mean-review`. The user opts into the harsher session. Don't shortcut it.

Why this skill exists

Without an explicit contract, the path from "Goldfish-approved doc" to "merged code" is implicit, and implicit paths drift. The suite's rules (the doc is the source of truth, drift is surfaced not absorbed, every change is enumerated) only hold if a skill enforces them. This is that skill.

IMPLEMENT.md is also the bridge to the next engineer, human or AI. Six months later, when someone asks "why does this code look like this?", the answer is: the design doc says so, here is the GOLDFISH.md that validated it, and here is the IMPLEMENT.md that recorded every drift along the way. That triple (doc, validation, implementation trace) is the institutional memory the EGM suite compounds.

Where this skill sits in EGM

/peanuts (legacy code only) → /elephant → /goldfish → `/egm-implement` → /mean-review