# Technical Reporting

> Write saved formal markdown: benchmarks, ADRs, architecture notes, asset paths, Mermaid diagrams. Not for Plotly chart construction, Dash apps, or stakeholder QBR narrative.

- Skill: `dmoreq/technical-reporting` (Agent Skill)
- Install (CLI): `npx skillmds@latest add dmoreq/technical-reporting`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dmoreq/technical-reporting/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: dmoreq (https://skillmd.com/u/dmoreq)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/dmoreq/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