k-report

Files (17)

• SKILL.md
• EXTRACTED-DESIGN-SYSTEM.md · references/
• design-tokens.css · references/
• icons.md · references/
• interactive-compare.md · references/
• mermaid-guide.md · references/
• sample-figure.jpg · references/templates/assets/
• comparison-interactive.html · references/templates/
• comparison.html · references/templates/
• concept-explainer.html · references/templates/
• decision-summary.html · references/templates/
• stat-highlight.html · references/templates/
• status-report.html · references/templates/
• bad_braces.md · scripts/tests/
• golden_fixture.html · scripts/tests/
• good_themed.md · scripts/tests/
• validate_mermaid.py · scripts/

SKILL.md (first lines)

> [!info] In force on this repo (Team Party map)
> Remap mold citations: constitution [[adr-24-constitution]], layout [[adr-25-harness-layout]],
> agent contract [[adr-26-agent-contract]], guardians [[adr-27-guardians-and-delivery]].
> Product SSOT: `docs/constitution/PRD.md`. Do not invent station/product law.


# k-report

Convert a **given** markdown summary (prose, lists, code, and `mermaid` blocks)
into a single self-contained dark HTML file — mobile-first, also readable on
desktop — following the **Presentation Orange** design system. The output is one
`.html` opened on a phone over WhatsApp. **You fill templates; you do not invent
a new look.**

## Responsibility — read first

This skill has ONE job: **convert markdown → HTML in this fixed format.**

> [!important] Default source = your last answer
> When kodex invokes `/k-report` with **no markdown attached**, the content
> to convert is **the assistant's own immediately-preceding message** (the last
> substantive answer rendered to kodex before this invocation). Do **not** ask
> for content and do **not** re-summarize from scratch — take that last answer
> verbatim as the markdown input and convert it. Only ask if there is genuinely
> no prior assistant answer to grab (e.g. first turn). If kodex *does* attach
> markdown or a file path in the same turn, that explicit content wins over the
> last-answer default.

- It is **NOT** a summarizer, writer, or researcher. The markdown summary is an
  **input** the caller provides (or, per the box above, the last answer). Do
  **not** invent, expand, or fact-find the content — convert exactly what you're
  given.
- Be **fast and deterministic**: no deliberation about design, no exploring
  options. Fixed pipeline below, every time.

## The one rule

This skill is opinionated to the extreme. The aesthetic is settled and lives in
`references/`. Your job is: receive the markdown → pick a template → fill it with
that content → emit one file → validate → report its path. Do not change colors,
fonts, radii, or layout. Do not add frameworks. Do not improvise.

## Pipeline

1. **Read the design contract** (once): `references/design-tokens.css` is the
   literal CSS you embed inline. `references/EXTRACTED-DESIGN-SYSTEM.md` is the
   rationale (read only if a judgment call comes up — do not re-fetch any URL).
2. **Take the supplied markdown** (the caller's summary — never write your own).
   If it's missing, ask for it and stop. Identify sections, code/diff blocks,
   and any ```mermaid fences.
3. **Pick a template** from `references/templates/` (see mapping below). Copy it
   as the skeleton.
4. **Fill it.** Replace placeholder content with the user's. Map markdown:
   - `# / ##` → `<h1>/<h2>` (lowercase, kept lowercase by CSS).
   - tiny eyebrow like `03 · QUÉ ES` → `<p class="kicker">`.
   - paragraphs → `<p>`; `**bold**` → `<strong>`. **Ration `<strong>` hard** —
     reserve it for the one genuinely load-bearing phrase in a passage, not every
     key term. Most paragraphs should carry zero `<strong>`. Over-bolding flattens
     emphasis and reads as noise.
   - fenced ```lang code → `<pre><code>`; a diff (lines `+`/`-`) → `<pre class="diff">` with `<span class="add">` / `<span class="del">` per line.
   - ```mermaid → `<div class="diagram"><pre class="mermaid">…</pre></div>` with the minimal `%%{init}%%` + the classDef component kit (see `references/mermaid-guide.md`), and the loader present. **HARD RULE: never emit `{{ }}` or `{ }` placeholders inside a mermaid block** — they collide with mermaid node syntax and break the parse. Write LITERAL, concrete lowercase labels at generation time. State diagrams: ids can't contain spaces/braces, use the `s1 : etiqueta` form. Style nodes with `class id hero|step|cool|ok|bad`, not themeVariables.
   - the ONE conclusion of the report → `<div class="takeaway">` (solid orange
     block, black type, hard contrast). At most one per report — it is loud on
     purpose. Everything else stays flat prose.
   - status words / tags → `<span class="chip ok|work|stop">`. Group two or more
     tags in a `<div class="chips">…</div>` row (they wrap side by side) — prefer a
     couple of short, specific tags over one long catch-all chip.
   - keep the hero hook to ONE tight line — no trailing filler clauses ("· la idea
     completa en cuatro pasos" and the like). The number, title and one hook line
     carry the top; don't pad it.
   - icons → inline Lucide SVG (`references/icons.md`); one accent icon per section, orange `.icon-lg` for a hero.
   - **images** (only if the caller passes one) → `.figure` component (see Images below). One image per section, room around it.
5. **Emit ONE file.** All CSS inline (`design-tokens.css` verbatim inside
   `<style>`), fonts via Google Fonts `<link>`, mermaid via CDN `<script>`,
   icons inline SVG. No external CSS/JS files. **Exception:** interactive
   compare reports may add one **inline** vanilla-JS block (IIFE tab switcher) —
   see `references/interactive-compare.md`. **Never React** and no npm/bundler.
6. **Validation gate (mandatory).** See below — run it before saving/reporting.
7. **Save a local copy & report (MANDATORY — always).** ALWAYS persist the
   artifact to disk before anything else downstream. There is **no** in-memory /
   send-only path: every report MUST leave a copy in a folder, every time, with
   no asking. Canonical archive dir is `~/Documents/k-report/` (create it with
   `mkdir -p` if missing); write `~/Documents/k-report/<slug>-YYYYMMDD.html`. If the
   user named a different target folder in the request, ALSO write a copy there,
   but the `~/Documents/k-report/` archive copy is always written regardless. Tell the
   user the absolute path(s). If a chrome-devtools MCP is available and they want
   a preview, offer to open it. **Never** deliver a report without first having
   written its local copy — the saved file is the artifact.
8. **Close on the path (no delivery channel).** The saved file IS the delivery.
   Report the absolute path and the `<h1>` + one-line summary in chat, and stop
   there. This harness ships **no** send step: no Telegram, no bot token, no
   outbound push. If the caller wants the report somewhere else, they name the
   folder (step 7 writes the extra copy) or move it themselves.

## Validation gate (mandatory)

After emitting the HTML artifact and BEFORE delivering it, run the deterministic
mermaid validator:

```bash
python3 skills/k-report/scripts/validate_mermaid.py <artifact.html>
```

- Exit `0` → all mermaid blocks pass; proceed to save & report.
- Exit `1` → at least one block is broken. Read the per-block report, FIX the
  offending block (almost always a `{{ }}` brace collision or a bad
  stateDiagram id), and re-run. Loop until exit `0`.
- **NEVER deliver an artifact that fails the gate.**

Tier 1 (stdlib, always runs) catches the brace collision and bad state ids
deterministically. Tier 2 renders each block through `bunx @mermaid-js/mermaid-cli`
(`PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium`, `--no-sandbox`) for an
authoritative parse; it degrades to a WARN (Tier-1-only) if bun/mmdc is absent —
the gate still blocks brace bugs. `--selftest` runs bundled fixtures.

## Images (only when the caller attaches one)

Images are an **input**, like the markdown — never invent or generate them. The
caller passes a photo by **local file path** (or pastes one; if pasted, ask for

From kodexArg/astro-drf-aws, MIT.

More from kodexArg/astro-drf-aws