Mdd Workflow

MDD Workflow Companion

This skill complements the /mdd command. The command owns the workflow; this skill keeps things honest between command runs. Its single most valuable job is preventing documentation drift the moment it would happen, before it accumulates.

Step 1 — Gate (do this first, every time)

Act only if this project uses MDD. Check for any of:

• a .mdd/ directory in the project root, or
• a resolvable /mdd command (.claude/mdd/, ~/.claude/mdd/, .claude/commands/mdd.md).

If none exist, stop silently. Do nothing, say nothing, never mention MDD. This skill is installed globally and will activate in projects that have never adopted MDD; in those projects it must be invisible.

Two hard rules that hold for everything below:

• Never run the workflow yourself. No branching, no .mdd/ bootstrap, no phase execution. You recommend /mdd and let the user confirm. The command performs all side effects.
• Silence is the default. When you activate but there is nothing controlled to sync and nothing substantial to recommend, produce no MDD output at all. Never narrate the gate or the check.

Step 2 — Job 1: Prevent doc drift when editing controlled code (priority)

Feature docs declare the source they own in frontmatter (source_files, plus routes and models). When that source is edited outside a /mdd run, the doc silently goes stale. Catch it at the edit, not weeks later in /mdd scan.

When you are about to edit (or have just edited) a source file in an MDD project:

1. Cheap controlled-file check. Grep .mdd/docs/*.md for the file's path in source_files (and routes/models if the change adds or alters a route or model):

   grep -rl "<relative/path/to/file>" .mdd/docs/*.md

   No match → the file is not controlled. Stay silent and proceed normally.

2. If a doc controls the file, name it and keep it in sync:

   • Read .mdd/docs/00-frontmatter-spec.md first so any frontmatter edit conforms to the schema.
   • Make the lightweight, factual updates inline: bump last_synced to today; add a new endpoint to routes; add a new model to models; append a genuinely new defect to known_issues (append-only — never remove entries).
   • Tell the user in one line: 📝 Edited <file>, controlled by .mdd/docs/<id>.md — synced last_synced and routes.
   • If the change is structural (behavior, business rules, contracts, or data flow changed, not just a field), don't try to re-derive the doc body yourself. Recommend the command that does a full resync: This change affects how <id> behaves. Run \/mdd update <id>` (or `/mdd audit`) for a full doc resync.`

3. If the user is mid-flow and declines the sync, don't block their work. Note it once so it isn't lost: Leaving .mdd/docs/<id>.md unsynced — \/mdd scan` will flag it later.`

This is real-time and pre-commit, which is precisely what /mdd status and /mdd scan cannot do (they detect drift retrospectively, from git history, only when invoked). Defer batch and historical drift detection to those commands; this skill catches the single edit as it lands.