Report design and visual QA
Engineering quality and presentation are separate gates. Use
neqsim-professional-reporting for
traceability, evidence and analytical depth; use this skill for the reader's
experience. A well-formed DOCX is not proof of good pagination.
Boundaries
Flow diagrams (PFD/BFD/P&ID sketches) are first checked geometrically with neqsim pfd-check
(neqsim-pfd-layout-review); this skill covers page-level presentation.
Preserve the configured corporate template, fonts, heading colours, logos,
classification, revision history and header/footer content.
Work on a separately named derivative under the existing task's
step3_report/formatting_pilot/. Never overwrite the original during a pilot.
Do not rewrite numbers, conclusions, readiness labels or evidence to make the
layout easier. Formatting approval is not engineering approval.
Do not upload a company report to online converters or design services.
Never open, edit or copy the report generator. Put reusable finishing logic in
devtools/report_design.py; authored narrative belongs in report inputs.
Procedure
- Generate the normal report with
neqsim report TASK_DIR when needed. For an
existing approved example, use the existing DOCX without regenerating it.
- Run
neqsim report-design SOURCE.docx --output PILOT.docx --render.
In a checkout, use the selected Python interpreter with
devtools/report_design.py and the same arguments; without a checkout use
-m report_design. Quote paths containing spaces.
- Use
--table-label Tabell for new Norwegian captions. Existing caption
wording is preserved. --overwrite permits replacing only the derivative.
- Inspect the contact sheet and every page image, not just the cover.
The command writes
PILOT.pdf, PILOT.qa.json and PILOT_preview/.
Inspect dense tables, continued tables, figure/caption pairs and section
transitions at full size.
- Correct issues in the shared finishing helper or report inputs, run focused
tests, then repeat rendering. Do not repair only the final Word file and
leave the shared workflow broken.
- Record the inspected pages, renderer, findings, remaining editorial issues
and reviewer in the QA JSON. Change
visual_review from PENDING only after
actual inspection. Never equate empty geometry findings with visual approval.
The command is opt-in. Existing neqsim report output and scientific-paper
formatting are unchanged. Word rendering uses a separate application instance,
disables macros and link updates, and refreshes the derivative's contents and
fields. LibreOffice is used when Word automation is unavailable; its pagination
may differ from Word. Missing rendering software is an explicit blocker, not a
reason to claim visual QA passed.
Acceptance criteria
| Area |
Check |
| Body text |
Template font; consistent named-style sizing and spacing; comfortable line length |
| Hierarchy |
Clear heading levels; no orphan heading or short table lead-in |
| Tables |
Content-aware widths; aligned numeric values; readable type; repeated headers |
| Pagination |
No clipped content, logo collisions, blank spill pages or excessive whitespace |
| Long rows |
Ordinary rows stay intact; page-sized evidence rows can continue without overflow |
| Captions |
Every body data table has a live number; captions stay with their object |
| Figures |
Sharp text and axes; adequate size; no figure detached from its caption |
| Navigation |
Updated contents, page references and page numbers |
| Preservation |
Original paragraphs, evidence cells, branding and source file unchanged |
Use restrained rules and alternate-row shading instead of adding decorative
boxes everywhere. The finishing pass uses 10.5-point table text and preserves
template fonts and existing column proportions, except that two-column evidence
tables allocate more width to the text-heavy column. Short tables stay together;
long tables can continue with repeated headers. It does not impose a new brand.
Editorial problems formatting must expose
Serialized dictionaries, machine-generated headings, empty workflow columns,
placeholder sections and excessive results lists need source-level editing.
Do not silently summarize or delete them. Mark decisive results as headlines
in the report inputs when authorized, leaving complete results in an appendix.
Keep that editorial change distinct from a formatting-only pilot.
Validation and ownership
Focused regression suite: devtools/test_report_design.py. It covers source and
content preservation, template branding, merged cells, section widths, captions,
oversized rows, page previews, CLI routing and explicit rendering failures.
Synthetic fixtures only: private reports, logos and screenshots stay in the task.
These are independently authored engineering-report conventions, not copied
third-party document-skill materials.
1---2name: neqsim-report-design-and-visual-qa3description: "USE WHEN: improving technical report formatting, Word typography, table layout, captions, pagination, or professional presentation. Produces a separate template-preserving DOCX revision, PDF and all-page previews, with explicit visual QA. Complements neqsim-professional-reporting."4metadata:5 source: https://skillmd.com/skills/equinor/neqsim-report-design-and-visual-qa6---78# Report design and visual QA910Engineering quality and presentation are separate gates. Use11[neqsim-professional-reporting](../neqsim-professional-reporting/SKILL.md) for12traceability, evidence and analytical depth; use this skill for the reader's13experience. A well-formed DOCX is not proof of good pagination.1415## Boundaries1617- Flow diagrams (PFD/BFD/P&ID sketches) are first checked geometrically with `neqsim pfd-check`18 ([neqsim-pfd-layout-review](../neqsim-pfd-layout-review/SKILL.md)); this skill covers page-level presentation.1920- Preserve the configured corporate template, fonts, heading colours, logos,21 classification, revision history and header/footer content.22- Work on a separately named derivative under the existing task's23 `step3_report/formatting_pilot/`. Never overwrite the original during a pilot.24- Do not rewrite numbers, conclusions, readiness labels or evidence to make the25 layout easier. Formatting approval is not engineering approval.26- Do not upload a company report to online converters or design services.27- Never open, edit or copy the report generator. Put reusable finishing logic in28 `devtools/report_design.py`; authored narrative belongs in report inputs.2930## Procedure31321. Generate the normal report with `neqsim report TASK_DIR` when needed. For an33 existing approved example, use the existing DOCX without regenerating it.342. Run `neqsim report-design SOURCE.docx --output PILOT.docx --render`.35 In a checkout, use the selected Python interpreter with36 `devtools/report_design.py` and the same arguments; without a checkout use37 `-m report_design`. Quote paths containing spaces.383. Use `--table-label Tabell` for new Norwegian captions. Existing caption39 wording is preserved. `--overwrite` permits replacing only the derivative.404. Inspect the contact sheet and **every page image**, not just the cover.41 The command writes `PILOT.pdf`, `PILOT.qa.json` and `PILOT_preview/`.42 Inspect dense tables, continued tables, figure/caption pairs and section43 transitions at full size.445. Correct issues in the shared finishing helper or report inputs, run focused45 tests, then repeat rendering. Do not repair only the final Word file and46 leave the shared workflow broken.476. Record the inspected pages, renderer, findings, remaining editorial issues48 and reviewer in the QA JSON. Change `visual_review` from `PENDING` only after49 actual inspection. Never equate empty geometry findings with visual approval.5051The command is opt-in. Existing `neqsim report` output and scientific-paper52formatting are unchanged. Word rendering uses a separate application instance,53disables macros and link updates, and refreshes the derivative's contents and54fields. LibreOffice is used when Word automation is unavailable; its pagination55may differ from Word. Missing rendering software is an explicit blocker, not a56reason to claim visual QA passed.5758## Acceptance criteria5960| Area | Check |61|---|---|62| Body text | Template font; consistent named-style sizing and spacing; comfortable line length |63| Hierarchy | Clear heading levels; no orphan heading or short table lead-in |64| Tables | Content-aware widths; aligned numeric values; readable type; repeated headers |65| Pagination | No clipped content, logo collisions, blank spill pages or excessive whitespace |66| Long rows | Ordinary rows stay intact; page-sized evidence rows can continue without overflow |67| Captions | Every body data table has a live number; captions stay with their object |68| Figures | Sharp text and axes; adequate size; no figure detached from its caption |69| Navigation | Updated contents, page references and page numbers |70| Preservation | Original paragraphs, evidence cells, branding and source file unchanged |7172Use restrained rules and alternate-row shading instead of adding decorative73boxes everywhere. The finishing pass uses 10.5-point table text and preserves74template fonts and existing column proportions, except that two-column evidence75tables allocate more width to the text-heavy column. Short tables stay together;76long tables can continue with repeated headers. It does not impose a new brand.7778## Editorial problems formatting must expose7980Serialized dictionaries, machine-generated headings, empty workflow columns,81placeholder sections and excessive results lists need source-level editing.82Do not silently summarize or delete them. Mark decisive results as headlines83in the report inputs when authorized, leaving complete results in an appendix.84Keep that editorial change distinct from a formatting-only pilot.8586## Validation and ownership8788Focused regression suite: `devtools/test_report_design.py`. It covers source and89content preservation, template branding, merged cells, section widths, captions,90oversized rows, page previews, CLI routing and explicit rendering failures.91Synthetic fixtures only: private reports, logos and screenshots stay in the task.9293These are independently authored engineering-report conventions, not copied94third-party document-skill materials.