Deck

---
name: deck
description: "Builds the project decks (kickoff, recurring status report, estimate presentation, demo) in deck.json. The data-driven slides are regenerated, the hand-written ones are preserved. Exports to PowerPoint and HTML."
user-invocable: true
pack: delivery
---

# /deck — Project decks

A status report is not a document you write once: you redo it every week or two for the
whole life of the project. So this skill does not generate a deck, it **keeps one up to
date**: it recomputes the numbers from the data and leaves the consultant's own words
alone.

Kickoff, status, estimate presentation and demo share the same skeleton and the same file
— what changes is `meta.type`.

---

**UX: chat stays conversational.** Do not narrate the slides one by one in chat: the user
sees the deck in the viewer, the way the client will see it. In chat you talk about the
message the deck carries, citing slides by id **and** title (e.g. "S4, the progress
slide").

## PROTOCOL

1. **Ask what kind of deck** if the request does not make it obvious (a `questions`
   block — format in `.claude/prompts/questions_format.md`)
2. **Read** the estimate, timeline, brief, people and context.md
3. **If the deck exists:** update it, preserving the hand-written slides
4. **Write deck.json straight away** with `meta.status: "draft"`
5. **Say in words** what the deck says (BLOCKING)
6. **On confirmation:** `meta.status: "confirmed"`
7. **Update context.md**

---

## PHASE 1 — TYPE OF DECK

| type | When | What it has to get across |
|---|---|---|
| `kickoff` | At the start | What we will do, who does it, by when, how we work together |
| `status` | Every 1-2 weeks | Where we are, what changed, what worries us |
| `estimate` | At the approval meeting | What it costs and why, on which assumptions |
| `demo` | At demos with users | What can be seen today, and in what order to show it |

If the project already has a `deck.json` of a different type, ask in a ```questions
block (format in `.claude/prompts/questions_format.md`): a project holds one deck at a
time in this file, and replacing it is the user's decision, not yours.
````
```questions
[
  {
    "id": 1,
    "q": "This project already has a '{existing_type}' deck.json. A project holds one deck at a time in this file — replace it with a '{new_type}' deck, or keep working on the existing one?",
    "options": ["Replace it with the new deck", "Keep the existing deck"]
  }
]
```
````

---

## PHASE 2 — READING

Read ALL of these before you go on:
- `projects/{project}/estimate.json` — epics, days, assumptions, open questions
- `projects/{project}/timeline.json` — if it exists: team, lanes, states, **milestones**
- `projects/{project}/people.json` — if it exists: who the people are, for the kickoff
- `projects/{project}/mockup.json` — if it exists: the pages, for the demo
- the brief (`brief.json` or the input document, possibly via `.extracted/`)
- `projects/{project}/context.md` — decisions, assumptions
- `projects/{project}/deck.json` — if it exists
- `knowledge/` — if the folder exists: client conventions and branding

If `timeline.json` is missing you can still do a status deck, but without real progress
figures: say so, and suggest planning the timeline first from the Estimate tab.

---

## PHASE 3 — WRITE THE DRAFT deck.json (before you talk in chat)

**This skill writes ONLY JSON.** The PowerPoint (`deck.pptx`) and the HTML version
(`deck.html`) are generated by the backend on demand from `deck.json`. Never hand-build a
pptx.

Build the JSON following `schemas/deck.schema.json`. `meta` requires `project`, `title`,
**`client`** (a plain string here, not nullable like in `estimate.json` — do not omit it
or leave it empty), `date` and `type`.

**Write it in pieces, not in one call.** A finished deck runs to tens of thousands of
characters, and emitting all of it in a single tool call is where this breaks: observed on
a local model, the `Write` arrived with an EMPTY payload and the document was never
created at all. So: `Write` the skeleton first — `meta` (with `status: "draft"`) and
`slides` holding the FIRST slide already composed (typically the `cover`). `slides` has
`minItems: 1`, so `slides: []` is not a valid skeleton and `save_doc` rejects it — from
this moment the document must already validate. Then add one slide per `Edit`, anchoring
`old_string` on the last slide already written (its unique `id`, e.g. `"id": "S3"`, makes
the match unambiguous) and inserting the new slide right after it. Every call stays
small, the file is valid JSON throughout, and an interruption costs the last item instead
of the whole document.


### The `auto` field is the heart of this skill

- `auto: true` — the slide **is made of data**: progress, the milestone timeline, days per
  epic, the list of items closed. At the next run it is **rebuilt** from the files. Do not
  write commentary into it — that would be lost
- `auto: false` (or absent) — the slide is **written by a person**: risks, messages to
  management, context notes, asks of the client. At the next run it is **preserved word
  for word**

That distinction is the only reason a status deck regenerated every fortnight stays useful
instead of decaying into a page of numbers with nothing said about them.

### Structure per type

**kickoff** — cover; "Goals" (list); "Scope" (list, from the estimate epics); "Team and
contacts" (table from `people.json`); "Plan" (timeline with the milestones); "How we
work" (list: status cadence, channels, how change requests are handled — `auto: false`,
that is ours to write).

**status** — cover with the period (`meta.period`); "Progress" (kpi: days completed of
total, percentage, days remaining — `auto: true`); "Plan and milestones" (timeline —
`auto: true`); "Closed this period" (list from the dev tasks moved to done — `auto:
true`); "In progress" (list — `auto: true`); "Next period" (list — `auto: true`); "Risks
and watch items" (list — **`auto: false`**); "Asks of the client" (list drawn from the
high-priority open questions, but `auto: false`: the wording that goes to a client is
worth doing by hand).

**estimate** — cover; "Scope" (list of the epics); "Days per epic" (table: epic, days,
notes — `auto: true`); "Totals" (kpi: development, E2E, contingency, total — `auto:
true`); "Assumptions" (list from `estimate.json` — `auto: true`); "Open points" (list from
the open questions — `auto: true`); "Notes" (`auto: false`).

**demo** — cover, then one `image` or `text` slide per page you want to show, in flow
order, with `speaker_notes` saying what to point at and what to say. Almost all
`auto: false`: the running order of a demo is a narrative choice.

### Writing rules
- Few words per slide. A bullet is a line, not a paragraph
- Numbers come from the files, never from the eye. If a figure is not there, do not invent
  it: one slide fewer beats one slide wrong
- `speaker_notes`: what to actually say while the slide is up. This is the part the
  presenter is grateful for
- Every layout requires its own content (`list`→`bullets`, `table`→`table`, `kpi`→`kpi`,
  `timeline`→`milestones`, `text`→`text`, `image`→`image`). The backend rejects a slide
  without it

### When updating (the normal case for a status deck)
1. Read the existing `deck.json`
2. **Keep** every slide with `auto: false`, identical, in its position
3. **Rebuild** every slide with `auto: true` from the current data
4. Update `meta.date` and `meta.period`
5. If a hand-written slide has become false (it talks about a risk that has since closed),
   **do not delete it**: flag it in chat and let the user decide

Check validity:
```
python -c "import json; from jsonschema import validate; validate(json.load(open(r'projects/{project}/deck.json', encoding='utf-8')), json.load(open(r'schemas/deck.schema.json', encoding='utf-8'))); print('valid')"
```

---

## PHASE 4 — CONVERSATIONAL SUMMARY (BLOCKING)

The deck already exists and the user can see it in the viewer. In chat: what message it
carries, what the progress numbers say, what you preserved from the previous version, and
above all **what still needs writing by hand** — the risks and the notes only the
consultant knows.

An example of the tone (not a fixed template):
```
Status deck updated for 8-19 September. The numbers say 62 of 91 days done (68%), in line
with the plan: the 15 October acceptance milestone holds.

I rebuilt the progress slides and the timeline, and left untouched the two you wrote
yourself on risks and asks. The risks one still talks about the delay on the supplier
file, which the dev tasks say closed a week ago: want me to update it, or will you
rewrite it?

The deck downloads as PowerPoint from the "download" button.
```

**STOP. Wait for confirmation or change requests.**

---

## PHASE 5 — CONFIRMATION

On confirmation: set `meta.status: "confirmed"` in `deck.json` (`Edit` just that line — do
not rewrite the file: it is tens of thousands of characters, and regenerating all of them
to change one word is both slow and a chance to alter something by accident),
re-validate against `schemas/deck.schema.json`. Remind them the deck downloads as a pptx
(that is what goes to the client) and that the HTML is what the viewer shows.

---

## PHASE 6 — UPDATE context.md

`## Deck` section: type of deck, period covered, date of the last update, and which slides
are hand-written — so the next run knows what not to touch.

---

## RULES

- `auto: false` is never touched on regeneration. It is a promise to whoever wrote it
- The numbers come from the files. An invented figure in a status report is worse than a
  missing one
- Few words per slide: a deck is looked at, not read
- If the client has a template of their own we do not have it: start from ours and adapt
  when the real one arrives
- Chat stays conversational: never the list of slides in the message