jhincapie/egm-cursor

EGM Drift Report: what the doc said versus what got built

/egm-implement builds from the design doc and logs drift in IMPLEMENT.md as it happens. Some drift still slips through: a change the session judged too small to log, a later fix, an interface that settled differently once real callers existed. This skill measures the gap after the fact and writes it down, so the user can later say "update the design doc to match" and the doc becomes the source of truth again.

Invoke as /egm-drift-report [path-to-design-doc].

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 (/egm-design).
2. Refuse sycophancy. Your job is to challenge the user's thinking; agreement on its own doesn't help them. If you're about to say "great point" or "you're absolutely right", stop and look for what's wrong instead. If the user says "You are not being helpful" (the EGM reset), treat it as a sign you've been agreeing too much, and go back to finding 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 /egm-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. Read-only. The only file this skill writes is docs/egm/<slug>/DRIFT-REPORT.md. Never edit the design doc, the code, tests, or any other ledger (IMPLEMENT.md, GOLDFISH.md, ELEPHANT.md). Applying the suggested updates is a separate request the user makes afterward.
2. Evidence or it isn't drift. Every item cites what the doc says (section and a short quote) and what got built (path:line, or a commit, or "no such file"). An item without evidence on both sides is an open question, listed as one.
3. The code is the observed fact; the doc is the claim. Report the difference neutrally. Do not decide which one is right unless a ledger records the decision; the suggested update is a proposal, not a verdict.
4. Fresh eyes do the comparison. The session that implemented the feature is biased toward reading its own intent into the code. Hand the comparison to a fresh read-only subagent (Step 3) whenever one is available.

Workflow

EGM drift report progress:
- [ ] Step 1: design doc and slug resolved; docs/egm/<slug>/ found
- [ ] Step 2: baseline commit chosen; evidence pack paths listed
- [ ] Step 3: comparison run by a fresh read-only subagent (or inline, noted)
- [ ] Step 4: findings checked, classified, and written to DRIFT-REPORT.md
- [ ] Step 5: user told where the report is and that they can ask to apply the updates

Step 1: Resolve the design doc

Prefer the user's argument. Otherwise look in the folder named by design_doc_path: in the project's AGENTS.md or CLAUDE.md, and else in docs/designs/*.md. If exactly one doc exists, use it; if several, list them and ask which. The slug is the doc's filename without .md, and the state directory is docs/egm/<slug>/. If that directory does not exist, the feature never went through /egm-design; say so, and offer to write the report there anyway (creating only docs/egm/<slug>/DRIFT-REPORT.md).

Step 2: Choose the baseline and gather the evidence pack

The baseline is the point where the doc was approved. Pick the first that applies and record which one you used:

1. The commit that set human_review_gate: passed (or skipped-solo) in docs/egm/<slug>/GOLDFISH.md: git log --format='%H %ad %s' --date=short -- docs/egm/<slug>/GOLDFISH.md.
2. The last commit touching the design doc on or before start_date in IMPLEMENT.md: git log --format='%H %ad %s' --date=short -- <doc>.
3. Ask the user for a commit or date.

Then list, without summarizing, the evidence the comparison will read:

• the design doc (at HEAD, and at the baseline if it changed since: git show <base>:<doc>);
• docs/egm/<slug>/IMPLEMENT.md, especially ## Files touched, every ## Drift entry (open and resolved) and ## Verification;
• GOLDFISH.md disposition notes where they record a doc change;
• git log --stat <base>..HEAD and git diff --stat <base>..HEAD, plus uncommitted changes from git status and git diff;
• the files the doc's Detailed Implementation enumerates, and the files the diff touched that the doc does not.

Not in the pack: this chat, ELEPHANT.md design reasoning, or your own recollection of why something was done. Those belong in the "likely reason" column only when a ledger says so.

Step 3: Run the comparison in a fresh read-only session

In Cursor, spawn one Task subagent of type drift-auditor (installed at ~/.cursor/agents/drift-auditor.md, readonly: true). If it isn't installed, use a generic Task subagent and tell it it is read-only. Send the prompt in assets/drift-auditor-prompt.md with the doc path, slug, baseline and evidence list filled in. Add nothing else: no summary of the implementation, no explanation of why things changed.

If no subagent runtime exists, do the comparison inline by following the same prompt yourself, and record comparison: inline (no fresh subagent available) in the report header so the reader knows it was not independent.

Step 4: Check, classify and write the report

Check each returned item before writing it: open the cited path:line and the cited doc section, and drop or fix anything the evidence does not support. Use the categories in the template: changed-approach, added, not-built, renamed-or-moved, interface-change, data-model-change, behavior-change, new-dependency, constraint-discovered, alternative-switched. Severity is major (the doc would mislead a reader about how the system works), minor (a detail is wrong) or cosmetic (naming, wording).

Cross-reference IMPLEMENT.md: mark each item logged (a drift entry exists, with its status) or unlogged. Unlogged major items are the headline.

Write docs/egm/<slug>/DRIFT-REPORT.md from assets/drift-report-template.md. If the file already exists, put the new dated report at the top under the file header and move the previous reports below ## Earlier reports unchanged. Never rewrite an earlier report.

If there is no drift, write the report anyway with drift_items: 0, the baseline used, and what was compared, so "no drift" is a recorded result rather than an absence.

Step 5: Hand back to the user

Tell the user, in this shape:

Drift report written to docs/egm/<slug>/DRIFT-REPORT.md: items ( major, not logged in IMPLEMENT.md). I have not changed the design doc or the code. When you want the doc to match what was built, ask me to apply the suggested doc updates from the report; items that change the Technical Plan should go back through /egm-design, and a large rewrite through /egm-review.

Do not apply the updates in this session unless the user asks after seeing the report.

Anti-patterns

• Fixing the doc while reporting. The report is the deliverable. Editing the doc mixes measurement with change and hides what the drift was.
• Fixing the code to match the doc. Same problem in the other direction. The user decides which side moves.
• Explaining drift from memory. "We changed this because X" without a ledger line is a guess; write reason: unknown and let the user fill it in.
• Summarizing the diff instead of comparing. A list of changed files is not a drift report. Each item ties one doc claim to one observed fact.
• Skipping the fresh session to save time. The implementing session already believes the code matches the doc. That belief is what this skill exists to test.

Where this skill sits in EGM

/egm-learn (legacy code only) → /egm-design → /egm-review → /egm-implement → /egm-code-review, with /egm-drift-report any time after /egm-implement (before or after the code review).

• Reads: the design doc, IMPLEMENT.md, GOLDFISH.md, git history since the baseline, and the code.
• Writes: docs/egm/<slug>/DRIFT-REPORT.md only.
• Feeds: a later "update the design doc from the drift report" request; /egm-design for Technical Plan changes; /egm-review when the updated doc needs re-validation.