Producing a service report

This guide walks Solutions Engineering through producing a portfolio-diagnostic report against the cell’s spec. Read this when you have an account question that needs unblocking and the right artifact is a multi-page leave-behind, not a sales deck or a case study.

If you’re not sure which cell or genre fits, start with the /pick-cell-and-genre skill or the index.md decision tree.

Step 1 — Confirm the report’s purpose

What account question is this report unblocking?

If you cannot name the question in one sentence, the report is theatre. A service report exists to land a specific decision in the customer’s hands: keep or replace this equipment? Is this a fleet pattern or a unit issue? Where do we send a tech?

Common purposes:

• “We’ve flagged X across the portfolio; the customer’s engineering team needs to decide whether to investigate.”
• “The customer asked whether their fleet’s harmonic profile is within IEEE limits; here’s the answer with peer comparison.”
• “We need to demonstrate that Verdigris’s high-frequency telemetry surfaces a class of fault their existing 1-minute polling cannot.”

If the purpose is “stay top of mind” or “show technical depth,” the artifact is not a service report. Use a case study (outcome proof) or a one-pager (single decision aid) instead.

Step 2 — Pick the genre

Currently one: portfolio-diagnostic. See portfolio-diagnostic.md for the spec.

If your shape doesn’t fit (single site investigation; regulator-facing audit), file an issue against the cell rather than coercing portfolio-diagnostic. The cell will graduate additional genres as evidence accumulates.

Step 3 — Anonymization checklist (only if the report will be shared publicly)

Default: real customer reports stay private. They are CUSTOMER-CONFIDENTIAL and ship via secure channel (Drive folder with explicit access, encrypted email, in-person review).

If the report will be shared as an example in examples/ — to teach the cell to other producers — it must be fully anonymized. See the examples index for the 7-point checklist (customer name, site nicknames, equipment IDs, vendor names, dollar amounts, Verdigris team names, channel identifiers).

The discipline is engagement-shape preservation with full identity substitution: keep the technical content fully (IEEE thresholds, THD values, gate logic, methodology), substitute every identifying string with a placeholder.

Step 4 — Threshold anchor

Before writing findings, name the citable threshold. The threshold appears once in the methodology section with full citation; findings reference it by short form.

Acceptable threshold sources:

• Industry standards — IEEE Std 519-1992, NEC, ASHRAE
• Regulations — LL97, IEEE 1547, EU AI Act
• Published internal benchmarks — Verdigris case studies (cite case study + section)
• Manufacturer specs — cite manufacturer + part number + spec sheet revision

If you cannot name a citable threshold, the report has no anchor. Pause and identify one before proceeding. Findings without anchors are not actionable.

Step 5 — Fill the canonical structure

Open portfolio-diagnostic.md and fill the six required sections in order:

1. Header callouts (3-4 portfolio-scale numbers)
2. What this report covers (one paragraph; names the threshold anchor and category structure)
3. Methodology (threshold anchor block + detection gates + data filters + peer-comparison logic)
4. Upstream check (per engagement)
5. Findings by category (multi-tier; system patterns + unit-level investigations have different remediation registers)
6. Spotlights (1-2 deep dives with figures)
7. Reference appendix (methodology details + source documents + standards + internal evidence atom IDs)

Step 6 — Validate

Run the per-artifact compliance audit before delivery:

npm run audit:compliance -- categories/service-reports/examples/{your-file}.html

Or, for a private report not in the repo, run the audit against a copy in /tmp/:

npm run audit:compliance -- /tmp/your-report-draft.html

Resolve all critical findings before delivery. Should-fix findings are judgment calls — fix them, justify them in a comment, or document them as known deviations in the report’s introduction.

The 6 composition rules the audit checks against:

1. composition.advise-service-report.threshold-anchor-required
2. composition.advise-service-report.peer-comparison-required
3. composition.advise-service-report.dual-category-discipline
4. composition.advise-service-report.no-replacement-recommendation
5. composition.advise-service-report.confidentiality-marking
6. composition.advise-service-report.spotlight-figure-required

Step 7 — Deliver

Service reports are CUSTOMER-CONFIDENTIAL. Mark every page with the confidentiality tier. Distribution channels:

• Google Drive folder with explicit access (preferred — auditable, revocable)
• Encrypted email with PDF attachment (acceptable for one-off; audit trail is weaker)
• In-person review with hard-copy print (preferred for sensitive engagements; PDF version follows for the customer’s engineering team)

Never:

• Post in shared Slack channels (even internal #team-z2o; the report’s confidentiality tier doesn’t permit casual Slack distribution)
• Attach to a sales-CRM record where access is broader than the engineering audience
• Ship without the confidentiality tier marked on every page

See also

• index.md — cell overview
• portfolio-diagnostic.md — genre spec
• examples/ — shipped reference examples + provenance discipline
• /pick-cell-and-genre — genre selection skill (if unsure)