report-slides

name report-slides description Use when creating presentations and research reports, especially diagram-heavy decks with architecture, flowcharts, timelines, charts, conceptual illustrations, or editable PPTX output. metadata {"data_access_level":"raw","task_type":"open-ended"} Report Slides Generates a slide deck from research log entries using three source paths: [A] generate_slides.py — data-driven slides (charts, tables, metrics) [B] Mermaid ( mmdc ) — diagram slides (flowcharts, architectures, state machines) [C] Claude SVG — free-form slides (conceptual layouts, text-heavy content) Every non-trivial visual goes through the mandatory visual-authoring gate below. After generation, slides can optionally be exported as native editable PPTX shapes, with SVG embedding retained as the backward-compatible fallback. Setup (first use in a project) Step 1 — Resolve directories (always first) Resolve the slides and research-log directories before anything else — in particular before the auto-setup check in Step 2, which creates directories under $SLIDES_DIR (see skills/resource-resolver/SKILL.md ): # macOS / Linux / Git Bash: RESOLVE= " $(find ~/.claude -path "*/resource-resolver/scripts/resolve.py" | head -1) " SLIDES_JSON=$(python " $RESOLVE " --role slides --json) SLIDES_DIR=$( echo " $SLIDES_JSON " | python3 -c " import json, sys d = json.load(sys.stdin) if d.get('status') == 'resolved': print(d['primary']) " ) LOG_JSON=$(python " $RESOLVE " --role research_log --json) RESEARCH_LOG_DIR=$( echo " $LOG_JSON " | python3 -c " import json, sys d = json.load(sys.stdin) if d.get('status') == 'resolved': print(d['primary']) " ) # Windows (PowerShell): $RESOLVE = (Get-ChildItem $env:USERPROFILE\.claude -Recurse -Filter resolve.py | Where-Object FullName -like "*resource-resolver*" | Select-Object -First 1).FullName $SlidesJson = python $RESOLVE --role slides --json | ConvertFrom-Json $SLIDES_DIR = if ($SlidesJson.status -eq "resolved") { $SlidesJson.primary } else { "" } $LogJson = python $RESOLVE --role research_log --json | ConvertFrom-Json $RESEARCH_LOG_DIR = if ($LogJson.status -eq "resolved") { $LogJson.primary } else { "" } Only a "resolved" status yields a usable path — a stale_mapping response also carries a non-empty primary , so never read primary without checking status . If either variable comes back empty, inspect the corresponding JSON ( $SLIDES_JSON / $LOG_JSON ) and follow the branching rules in the "Calling convention for other skills" section of skills/resource-resolver/SKILL.md : an error key means surface message and stop; status: "stale_mapping" means the configured directory is gone and the user must re-confirm it (do not silently recreate it); only "unresolved" / "no_candidates" leads to the normal first-use confirmation flow. Do not run Step 2 until $SLIDES_DIR is a confirmed, non-empty path. Setup creates directories under it, and creating them from an unconfirmed or empty value would write outside the intended project layout. The rest of this file refers to the resolved slides directory as $SLIDES_DIR and the resolved research log directory as $RESEARCH_LOG_DIR . Shell state does not persist across separate tool-call invocations. When a later section needs these paths in a new bash/PowerShell call, either re-run the resolve snippet above in that same call, or substitute the already-resolved path as a literal value into the command. Step 2 — Install project scripts macOS / Linux / Git Bash: bash " $(find ~/.claude -path "*/report-slides/scripts/setup.sh" | head -1) " " $SLIDES_DIR " Windows (PowerShell): & (Get-ChildItem $env:USERPROFILE\.claude -Recurse -Filter setup.ps1 | Where-Object FullName -like "*report-slides*" | Select-Object -First 1).FullName $SLIDES_DIR This copies generate_slides.py , validate_diagram_manifest.py , and render_review_sheet.py into scripts/ and creates both $SLIDES_DIR/reports/ and $SLIDES_DIR/assets/diagrams/ . to_pptx.py stays in the skill bundle and is invoked directly from there. Auto-setup: if you invoke /report-slides and scripts/generate_slides.py is missing, run the setup command above automatically before proceeding — no need to ask the user. This is only ever automatic after Step 1 has produced a confirmed $SLIDES_DIR ; if the slides role is still unconfigured or stale, resolve and confirm it with the user first, because setup creates directories. Check for Mermaid (optional, for diagram slides): # macOS / Linux which mmdc && echo "Mermaid OK" || echo "Mermaid missing (npm i -g @mermaid-js/mermaid-cli)" # Windows Get-Command mmdc -ErrorAction SilentlyContinue && "Mermaid OK" || "Mermaid missing (npm i -g @mermaid-js/mermaid-cli)" Style system Slides inherit colors and fonts from a style file — a .md file with YAML frontmatter. Three built-in styles ship with this skill: default , minimal , dark , paper . Full schema and color role descriptions are in references/styles/STYLES.md (read it when resolving styles). Project default: if $SLIDES_DIR/_style.md exists it is applied automatically to every deck. Design tokens (the machine contract) Sizes, spacing, radii, connector geometry, contrast floors, and density budgets come from a design-token file, not from style Markdown. The shipped default is references/tokens/default.tokens.yaml ; select another with --tokens . # Validate a token file before use: python3 " $(find ~/.claude -path "*/report-slides/scripts/validate_design_tokens.py" | head -1) " \ --tokens <file> # Render with a specific token file: python3 scripts/generate_slides.py --tokens <file> --data <json> --out < dir > --deck-id < id > Every ModuleSpec must name a token file in style_tokens_ref ; null is rejected and the path is resolved and validated at the gate. --style and --tokens are composed before rendering, not applied in sequence afterwards. The result is written to <out>/_effective.tokens.yaml , and that file — not the file passed to --tokens — is what $STYLE_TOKENS_REF must point at for the rest of the pipeline. A style file may set the value of a colour role or the sans font family; a key naming no role is an error, because the role names are the vocabulary every downstream check is written against. set-style <name> Copy a built-in style as the project default (one command): # macOS / Linux / Git Bash: bash " $(find ~/.claude -path "*/report-slides/scripts/set-style.sh" | head -1) " <name> # Windows (PowerShell): & (Get-ChildItem $env :USERPROFILE\.claude -Recurse -Filter set-style.ps1 | Where-Object FullName -like "*report-slides*" | Select-Object -First 1).FullName <name> # built-in names: default minimal dark paper To create a custom style : make $SLIDES_DIR/styles/<name>.md using the schema in references/styles/STYLES.md , then copy it to $SLIDES_DIR/_style.md to activate it as the project default. Workflow This is a 15-stage, approval-gated, multi-agent pipeline. presentation_state.py is the state machine of record: every stage transition below is a call into it, not a prose convention. Nothing that is not deterministic orchestrator logic is performed by the orchestrator itself — planning, review, and visual authoring are always dispatched to a named agent via the Task tool, and the orchestrator's job is to create records, validate agent output, and gate transitions. Schema-v2 migration preflight Run the presentation workflow from the project root. Before the first workflow action for an existing presentation state, inspect the version or schema_version header in every YAML file under .research/presentations/state/ . All existing state stores must have one shared schema version; mixed, malformed, or unsupported headers are not safe to infer from a single file. The required operator flow is: inspect schema -> migrate-state --dry-run -> migrate-state -> workflow action Use the existing migration entry point; it is the only state-migration command: PROJECT_ROOT= " $(git rev-parse --show-toplevel) " MIGRATE= " $(find ~/.claude -path "*/report-slides/scripts/migrate_presentation_state.py" | head -1) " STATE_DIR= " $PROJECT_ROOT /.research/presentations/state" if [ -d " $STATE_DIR " ]; then rg -n --glob '*.yaml' '^(version|schema_version):' " $STATE_DIR " else echo "No presentation state exists; continue with Stage 1." fi # Preview first: this creates no locks, directories, sidecars, journals, # backups, CAS objects, or mtimes. python3 " $MIGRATE " --project-root " $PROJECT_ROOT " --dry-run --json # Apply only after reviewing the dry-run JSON report. python3 " $MIGRATE " --project-root " $PROJECT_ROOT " --json Schema 0 and schema 1 are read-only workflow states. Any workflow write before migration fails with the structured JSON error MigrationRequiredError and identifies its source and required target schema version. After successful migration, schema 2 is the only workflow-write schema; re-running migration on schema 2 is an exact no-op. Schema-2 gates authorize only the immutable evidence envelope selected by the current deck pointer and the corresponding verified CAS bytes. They never fall back to a legacy event or a path-based assertion. Operational lock sidecars coordinate access only: they are not workflow evidence. Historical envelopes remain audit history, but an envelope marked historical_unavailable cannot authorize a current gate. A targeted revision preserves prior immutable evidence and clears the current preview, draft-approval, and completion evidence pointers; create and validate fresh current evidence before the next gated action. 1. Create the Deck Orchestrator. After Setup, before asking the user anything, create the Deck record so every later stage has a $DECK_ID to attach state to: PSTATE= " $(find ~/.claude -path "*/report-slides/scripts/presentation_state.py" | head -1) " DECK_JSON=$(python3 " $PSTATE " --create-deck --title "<deck working title>" --json) DECK_ID=$( echo " $DECK_JSON " | python3 -c "import json,sys; print(json.load(sys.stdin)['id'])" ) deck.status starts at planning . Enforcement Mechanism (the exact rule from the design spec): no SVG, PNG, PPTX, or manifest is ever written before deck.status reaches approved , and this is enforced by --check-production-allowed (Stage 14), not by prose discipline — a production call against an unapproved deck fails closed. 2. Ask (one message) Before asking, show the user what already exists to select from — reuse the existing log-discovery step: cat " $RESEARCH_LOG_DIR /INDEX.md" 2>/dev/null \ || find " $RESEARCH_LOG_DIR " -maxdepth 1 -name "*.md" ! -name "INDEX.md" | sort -r | head -20 Show the user which entries exist and which have already been made into slide decks. If no log files exist, tell the user to run /research-log add first and stop. Academic data source (optional). When the user passes --source academic or selects "academic pipeline" as source in the question below: Check for a passport YAML file (default: docs/passport.yaml ; override with --passport <path> ) Run the bridge script to extract stage data: BRIDGE= " $(find ~/.claude -path "*/research-lab-skills/bridge/scripts/passport_to_log.py" 2>/dev/null | head -1) " python3 " $BRIDGE " --passport docs/passport.yaml Use the extracted stage records as input for slide generation instead of research-log entries. If no passport file exists, fall back to research-log source and notify the user. This is the existing questionnaire — copy it verbatim from the current file, unchanged; it still runs before any planning: Source? ( research-log = experiment logs (default) / academic = pipeline passport data) If research-log: which logs? ( all / recent-N / by name / date range) If academic: passport file path? (default: docs/passport.yaml ) Audience? (advisor / team meeting / conference) Charts? ( list = output paths to chart_list.md / embed = base64 into SVG) Language? (follow log language / force English / force another language) Emphasis? (progression / final results / failure analysis / let Claude decide) Style? (skip = use $SLIDES_DIR/_style.md if present / name a built-in / custom to create one) Read the selected log files (or the academic bridge output) and any CLAUDE.md for project context and baselines. This resolved log/passport content is exactly what Stage 3 receives. 3. Narrative planning Dispatch research_narrative_planner_agent (Task tool) with: the resolved log/passport content from Stage 2, $DECK_ID , and instructions to write .research/presentations/decks/$DECK_ID/plan.yaml (a Deck Plan document per the design spec §3 contract table) and return its path. Orchestrator then runs: DDP= " $(find ~/.claude -path "*/report-slides/scripts/validate_deck_plan.py" | head -1) " python3 " $DDP " --plan ".research/presentations/decks/ $DECK_ID /plan.yaml" --json A non- valid result is a bug in the agent's output, not a workflow state — re-dispatch the same agent with the validator's errors, do not proceed. Once valid, deck.status: planning -> content_review . 4. Content review Dispatch content_reviewer_agent with the Deck Plan path. The agent returns a Review Result ( subject_type: plan , subject_id: $DECK_ID ); orchestrator writes it and validates: python3 " $PSTATE " --record-review --subject-type plan --subject-id " $DECK_ID " \ --reviewer-role content_reviewer --status <passed|failed> \ --findings-json " $(cat review_result_findings.json) " --round 1 --json VVR= " $(find ~/.claude -path "*/report-slides/scripts/validate_visual_review.py" | head -1) " python3 " $VVR " --review-result review_result.json If status: failed , deck.status stays content_review ; feed the findings back into the Research Narrative Planner (Stage 3) as a Revision Request ( --create-revision-request --subject-type plan --subject-id "$DECK_ID" --requested-by reviewer --instructions "<findings summary>" ) and re-run Stage 3-4 against a new plan_version . If status: passed , deck.status: content_review -> awaiting_approval . 5. Approval gate Orchestrator, interactive by default. Present the approved-by-content-review Deck Plan to the user in the same style as the current outline-confirmation prompt — a numbered slide list, one line per slide: title plus intended visual type tag: