engagement-workflow

What this skill does

# /digital-marketing-pro:engagement-workflow — 12-Part Engagement Orchestrator

This skill orchestrates the full marketing engagement using the 12-Part sequential methodology. Every brand engagement runs through the same 12 parts in sequence, producing a canonical set of files at each stage.

## Context efficiency

Heavy skill. **Grep before Read** any referenced file, then `Read` only matched ranges with `offset` + `limit`. List `${CLAUDE_PLUGIN_DATA}/<brand>/` before opening files. On re-invocation mid-session, skip files already in context.

Read these references before producing output:
- [engagement-flow-methodology.md](../context-engine/engagement-flow-methodology.md) — the full 12-Part flow
- [two-views-model.md](../context-engine/two-views-model.md) — v1 / v2 architecture
- [stone-vs-opinion.md](../context-engine/stone-vs-opinion.md) — confidence tagging
- [decision-matrix-rerun.md](../context-engine/decision-matrix-rerun.md) — when to re-run what
- [update-back-rule.md](../context-engine/update-back-rule.md) — versioning protocol
- [living-instruction-file-spec.md](../context-engine/living-instruction-file-spec.md) — LIF schema

## Operating Mode

This skill is invoked via the `/digital-marketing-pro:engagement` command family. Each subcommand maps to a specific lifecycle action. The skill calls `scripts/engagement-state.py` for persistence; you should never hand-edit `_engagement.json`.

## Subcommands

### `/digital-marketing-pro:engagement start <brand-slug> <engagement-id>`

**Purpose:** Initialise a new engagement.

**Steps:**

1. Validate that the brand profile exists at `~/.claude-marketing/brands/{brand-slug}/profile.json`. If not, instruct the user to run `/digital-marketing-pro:brand-setup` first.
2. Run `python ${CLAUDE_PLUGIN_ROOT}/scripts/engagement-state.py init --brand {brand-slug} --id {engagement-id}`.
3. Confirm the directory tree was created and report the next required action (Part 1 intake).
4. Walk the user through Part 1 Stone vs Opinion intake by asking the questions one batch at a time.

**Part 1 intake questions (ask in this order):**

**Stone — what the client knows for certain:**

1. Company basics: founded year, employee count, headquarters location, geographic operations
2. Business model: revenue streams, pricing tiers, primary product/service categories
3. Current marketing: channels currently active, monthly marketing spend, current measurable KPIs
4. Tech stack: CRM, email service provider, analytics setup, ad accounts
5. Customer base scale: customer count, biggest named customer, average order value if known

For each Stone fact, capture:
- The fact itself
- Source (how the user knows / what document confirmed it)

Save each via:
```
python ${CLAUDE_PLUGIN_ROOT}/scripts/engagement-state.py add-stone-fact --brand {slug} --id {id} --fact-json '{"category":"...","fact":"...","source":"..."}'
```

**Opinion — what the client believes:**

1. Brand positioning: how does the client describe their position in the market?
2. Customer base: who do they think their customers are? Why do they buy?
3. Competitors: who do they consider their main competitors?
4. Growth opportunities: where do they think the biggest opportunity is?
5. What is working: what marketing activity does the client believe is working?
6. What is not working: what does the client believe is not working?

For each Opinion, capture:
- The hypothesis
- Client's evidence for it (could be intuition, anecdote, partial data)
- Research question — what would the unbiased research need to verify or refute?

Save each via:
```
python ${CLAUDE_PLUGIN_ROOT}/scripts/engagement-state.py add-opinion --brand {slug} --id {id} --hypothesis-json '{"category":"...","hypothesis":"...","client_evidence":"...","research_question":"..."}'
```

**On completion of Part 1:** mark Part 1 as completed via `mark-part-completed --part 1`, advise the user to proceed to Part 2 (External Research).

### `/digital-marketing-pro:engagement next [brand] [id]`

**Purpose:** Advance to the next part.

**Steps:**

1. Read engagement status via `engagement-state.py status`
2. Identify the current part and next not-yet-completed part
3. Confirm with the user that the current part is genuinely complete (do not auto-advance — ask)
4. On confirmation, mark current as completed, advance current_part pointer
5. Brief the user on what the new part requires

### `/digital-marketing-pro:engagement status [brand] [id]`

**Purpose:** Show engagement status.

**Steps:**

1. Run `engagement-state.py status` — get the full state
2. Read the Living Project Instruction File header
3. Format a human-readable summary:
   - Engagement: brand + id + start date
   - Current part: part name + days in
   - Completed parts: list
   - Pending parts: list
   - Open re-run decisions: count
   - LIF last updated: date
4. If the engagement has open items needing resolution, list them

### `/digital-marketing-pro:engagement file-tree [brand] [id]`

**Purpose:** Show the engagement directory file tree.

**Steps:**

1. Run `engagement-state.py file-tree`
2. Format as an indented tree
3. Highlight files that are missing per the canonical structure (e.g., if Part 3 is marked completed but `3.1-business-and-sbu-analysis.md` is missing, flag it)

### `/digital-marketing-pro:engagement validate [brand] [id]`

**Purpose:** Run the Part 5 Client Validation flow.

**Pre-condition:** Parts 2, 3, 4 must be completed.

**Steps:**

1. Verify pre-conditions (Parts 2, 3, 4 completed)
2. Invoke the `client-validation-document` skill — it produces the Part 5 deliverable: a structured document presenting each finding from v1 with ACCEPT/REJECT/EDIT/DEFER options
3. After the user reviews and provides decisions, parse them into a triggers list per the Decision Matrix categories
4. Run `engagement-state.py decision-matrix --triggers "{comma-separated}"` to compute the v2 re-run plan
5. Present the re-run plan to the user
6. Mark Part 5 completed; on user approval of the re-run plan, advance to Part 6

### `/digital-marketing-pro:engagement re-run-decision [brand] [id]`

**Purpose:** Apply the Decision Matrix to compute v2 re-runs.

**Steps:**

1. Read the Part 5 Client Validation Document
2. Categorise rejected/edited findings into Decision Matrix triggers
3. Show the triggers and the computed re-runs
4. Estimate the cost (rough token count) of each re-run
5. Await user approval — they can accept, modify (skip some, add others), or reject
6. Record the executed plan via `engagement-state.py record-rerun-execution`

### `/digital-marketing-pro:engagement update-back [brand] [id] --doc <doc-id> --reason <reason>`

**Purpose:** Apply the Update-Back Rule to bump a source document version after Part 7+.

**Pre-condition:** The user has already drafted the corrected document content.

**Steps:**

1. Read the current version of the doc
2. Confirm the correction with the user (validation step per the Update-Back Rule)
3. Bump the version via `engagement-state.py bump-version --doc {id} --reason "{reason}"`
4. Save the new version file with a header noting v(prev) → v(new) changes
5. Update the Living Project Instruction File via `lif-log-change`
6. Identify downstream documents that may need review and add to the engagement's review queue

### `/digital-marketing-pro:engagement lif-show [brand] [id]`

**Purpose:** Display the Living Project Instruction File.

**Steps:** Run `engagement-state.py lif-show` and format the markdown output for readability.

### `/digital-marketing-pro:engagement list-engagements [brand]`

**Purpose:** List all engagements (optionally filtered by brand).

**Steps:** Run `engagement-state.py list-engagements --brand {slug}` and format as a table.

## Per-Part Production Skills

Each part has a dedicated skill that produces its outputs. This orchestrator delegates:

| Part | Skill |
|------|-------|
| 1 | (this skill — intake walked here directly) |
| 2 | `external-research` (use existing market-intelligence + comp