Technical Reporting

Technical Reporting Skill

Create a saved technical markdown document when the user asked for a durable report, benchmark write-up, or ADR file. Skip this skill for in-chat answers.

When to Use

• User asked to save a report, benchmark summary, or architecture analysis as markdown
• Embedding Mermaid or SVG assets into a persistent .md file

When Not to Use

• Short in-chat answers (tables in the reply are enough)
• Plotly figure construction (data-visualization)
• Stakeholder decision narrative (data-storytelling)
• Interactive dashboards (plotly-dash)

Related Skills

• Use data-visualization when embedding Plotly/SVG charts (layout and overlap QA live there).
• Numbers come from the skill that produced them; do not chain research → optimize → report.

1. Execution Flow

1. Generate assets first: compute metrics and export SVG (via data-visualization) before drafting.
2. Draft the markdown using verified numbers.
3. Embed assets with relative paths from the report file.

2. File Organization & Naming

• Prefix persistent files with ISO date: YYYY-MM-DD_<topic>.md.
• Workspace default: match existing docs layout, else docs/reports/YYYY-MM-DD_<topic>.md.
• Session default: host artifact directory if the environment provides one; otherwise docs/reports/.
• Assets: docs/reports/assets/YYYY-MM-DD_<topic>/ or beside the report. Always relative paths.

3. Mermaid (in-document diagrams)

• Supported headers only: xychart-beta, flowchart TD / flowchart LR / graph, sequenceDiagram, stateDiagram-v2, erDiagram, classDiagram.
• Keep sketches compact (3–5 nodes). No HTML inside nodes.
• Architecture / EDA charts that need real axes: export SVG via data-visualization (Plotly) or, if the repo already uses them, Seaborn/Matplotlib. Infrastructure diagrams: diagrams (Mingrammer). Decision trees / state machines: graphviz.
• Prefer .svg; PNG only when SVG cannot be produced. Do not embed raw HTML or iframes.

4. Content Standards

• Start with TL;DR / Executive Summary (metrics + takeaway).
• Professional engineering prose. No emojis, no Unicode sparklines or character bars (see global rules).
• Default to Markdown tables with explicit numbers, percentages (2 decimals), and deltas vs baseline.
• Minimize LaTeX math notation ($...$, $$...$$). Many downstream platforms (internal wikis, issue trackers, terminal renderers) lack KaTeX/MathJax. Express equations, bounds, and metrics using plain text, standard Unicode symbols (<=, >=, ≈, ±, ×), or backticks (O(n log n)). Reserve LaTeX only for advanced multi-line formal mathematics.
• Charts only when they reveal a pattern a table would hide.

Final Checklist

• User actually asked for a saved file (otherwise answer in-chat)
• ISO date prefix on persistent files
• TL;DR with key metrics
• Mermaid headers from the allowlist, or SVG via data-visualization
• Relative asset paths
• Claims backed by numbers
• LaTeX minimized in favor of plain text, Unicode, or backticks