Refresh/check upstream references first, on every invocation (run from this skill directory):
- uv run scripts/refresh_sources.py
- Optional: set GH_TOKEN/GITHUB_TOKEN to avoid GitHub API rate limits
- Do not pass --max-age-sec during normal skill use; the default should check upstream every time.
- references/refresh-metadata.json is an ignored local cache for conditional requests and diagnostics. Do not stage, commit, or require it to be clean.
- The refresh script must not rewrite tracked reference files for timestamp/provenance-only changes. Treat clean cache_not_modified output as a valid refresh.
Use the script's JSON output as the refresh status source:
- capture docs_source, gist_source, cheatsheet_source, and used_cache_fallback
- read references/refresh-metadata.json only for local diagnostics if the output indicates fallback or unavailable references
Read the conversation and extract:
- audience
- objective
- timebox (talk length) + format (demo, deep dive, status update, pitch)
- key claims and evidence
- constraints (must-include points, required sections, theme/footer if specified)
Build a narrative spine and a slide outline (titles + 1-line intent) before writing slides.
Draft a single Deckset markdown deck.
Do not force a provenance stamp into the deck. Add a short presenter note only when refresh status materially affects delivery, such as cache fallback or unavailable references.
Run quality gates before returning output.

Output Contract

Output exactly one complete Deckset markdown deck by default.
Include presenter notes using ^ when they improve delivery.
Defaults:
- if audience is not specified, assume a mixed technical audience
- if duration is not specified, target ~10 minutes / ~10 slides (do not force a hard slide count)
If missing duration/audience would materially change the deck, ask exactly one clarifying question; otherwise apply the defaults.
Keep styling prompt-driven:
- do not force a theme/footer/slidenumbers/autoscale unless requested
- do not force a fixed slide count; size to content
Prefer references/deckset-cheatsheet.md over the HTML docs cache.

Deckset Rules

Separate slides with ---.
Prefer # and ## headings for slide structure.
Use [fit] only when needed to preserve readability.
Keep one major idea per slide unless the content is inherently coupled.
Keep code blocks concise and language-labeled.
Use incremental build commands only when the user asks for staged reveals.
Global commands (e.g. theme:, footer:, slidenumbers:) must be at the top of the file with no blank lines between them.
If you open columns ([.column]), always close with [.end-columns].

Fidelity: preserve the conversation's claims and hierarchy.
Coherence: each slide should have a clear purpose in the narrative.
Syntax: deck parses as valid markdown with Deckset commands placed correctly.
Delivery: presenter notes clarify talking points, not duplicate slide text.
Structure: every slide has a title; one major idea per slide.
Density: keep slides scannable (<= 6 bullets per slide; move detail into presenter notes).
Provenance: disclose cache fallback or unavailable references in the response summary; do not require timestamp-only reference mutations or deck notes.

Cheatsheet (preferred):
- references/deckset-cheatsheet.md
Full docs cache (fallback):
- references/deckset-markdownDocumentation.html
Gist example cache:
- references/examples/*.md
Local refresh metadata (ignored, operational cache only):
- references/refresh-metadata.json

If used_cache_fallback is true, disclose that in the response summary.