---
name: cse-rich-report
description: Rendering specification for agents producing polished local CSE report artifacts, including a copy-safe HTML region, plain-text and Confluence-storage fallbacks, conditional diagram assets, a manifest, and operator-voice checks.
argument-hint: "[--input report.json|draft.md|draft.html] [--out-dir DIR] [--basename NAME] [--no-diagrams]"
---

# CSE Rich Report

## Compact MCP routing

Follow the shared [compact MCP routing contract](../../shared/compact-mcp-routing.md). Interactive facade tools are `cse_capabilities`, `cse_read`, `cse_apply`, `context_assemble`, and `cse_session_info`; named operations are capability ids. Call reads through `cse_read` with the capability id. Any Confluence mutation goes through `cse_apply` twice: dry-run first, then the identical capability and arguments with `execute:true`, justification of at least 16 characters, and the returned `preview_digest`. Call `cse_session_info` directly when needed. This rendering specification doesn't call `context_assemble`.


Use this specification when already-gathered CSE data needs to become a real work artifact, not just a styled webpage. It doesn't ship a renderer, perform entity fan-out, call `context_assemble`, or launch a source-gathering workflow. The agent implements the documented artifacts directly or uses a verified existing renderer, validates the outputs, and follows the operator voice rules. Diagram images are conditional on a real generator being available.

## Hard boundaries

- Do not publish to Confluence in this skill. Generate local artifacts and Confluence storage fallback only.
- Do not fake diagrams. If image auth is missing or generation fails, report the skip reason clearly.
- Do not paste raw transcripts, secrets, customer-private implementation detail, tokens, or credentials into image prompts.
- Do not use raw voice corpus text as prose material. Use `prose-voice.md`, voice invariants, and approved examples only as calibration bands.
- Keep report claims sourced. If evidence is weak, say so in the report or manifest instead of smoothing it over.
- Do not add external CSS, hosted fonts, or remote image URLs to the copyable report body.

## Setup

From the repo root, load the shared bootstrap when running the script directly:

```sh
source "${PLUGIN_ROOT:-${DROID_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-$PWD/plugins/cse-tools}}}/.agents/shared/skill-bootstrap.sh"
```

Generate images only with a local image generator already available in the calling environment or an existing report script that is present in the workspace. Don't invent a helper path or bootstrap a new image service as part of this skill. Record the actual command/tool, model, and output in the manifest. If no real generator is available, skip diagrams explicitly.

If the environment advertises an image capability, read its tool schema from `tools/list`; call non-mutating status/generation capabilities directly, and gate any mutating upload/apply operation via the two-phase dry-run/execute contract's two-phase dry-run/execute flow. Never assume the legacy capability names are installed.

## Inputs

Accept one of:

- Structured JSON report model, preferred for deterministic rendering.
- A local Markdown or HTML draft that the agent converts into the report model first.
- Freeform user notes, which the agent must turn into the report model before rendering.

Inputs must already contain the facts and evidence needed for the report. If a required fact is missing, mark the gap or request a bounded capability read; don't fan out around an entity or silently start a research pass.

Structured model shape:

```json
{
  "title": "Customer rollout update",
  "audience": "Internal update",
  "status": "Draft for Eric",
  "summary": "One short thesis paragraph.",
  "sections": [
    { "type": "heading", "level": 2, "text": "What changed" },
    { "type": "paragraph", "text": "Use **bold**, `code`, and links when useful." },
    { "type": "list", "items": ["First point", "Second point"] },
    { "type": "table", "headers": ["Area", "Status"], "rows": [{ "Area": "Pilot", "Status": "Live" }] },
    { "type": "callout", "variant": "info", "title": "Read", "text": "What the reader should notice." },
    { "type": "diagram", "id": "rollout-flow", "title": "Rollout flow" }
  ],
  "diagrams": [
    {
      "id": "rollout-flow",
      "title": "Rollout flow",
      "alt": "Generated rollout flow diagram",
      "prompt": "A clean B2B SaaS rollout flow diagram with three stages...",
      "size": "landscape"
    }
  ]
}
```

## Run Pattern

1. Validate the supplied source material and write the story spine. Don't gather broad entity context.
2. Convert the report to the structured model. Prefer explicit `sections` over arbitrary HTML.
3. Check the selected image generator's availability and auth:
   - If available, generate diagram PNGs with deterministic filenames.
   - If unavailable, record a plain manifest status and exact skip reason unless the user asked for diagrams as a hard requirement.
4. Run voice validation on visible report prose before writing artifacts.
5. Resolve output names before rendering. Default `--out-dir` to `$PWD/cse-rich-report-output`. Default the basename to a lowercase ASCII slug of the report title, with runs of non-alphanumeric characters collapsed to `-`; use `report` if the slug is empty. Never overwrite: if any target exists, append `-2`, `-3`, and so on until the whole artifact set is free.
6. Render:
   - `.html` browser preview
   - `.txt` plain-text fallback
   - `.storage.html` Confluence storage fallback
   - `.manifest.json` artifact manifest
7. Open the HTML page for interactive local runs only when the selected implementation supports it and `--no-open` isn't set.
8. Report the absolute path of every emitted artifact, including each diagram asset.

This skill doesn't ship a renderer script. Use an existing report script only after confirming its path in the workspace, otherwise render the local artifacts directly from the structured model. Don't cite `scripts/render-report.js` unless that file exists. Use only flags supported by the script actually selected, and run its focused tests before handoff.

## Capability routing for Confluence

Local rendering needs no MCP call. When a caller asks for a Confluence operation, describe the capability first if its contract isn't known. Before any mutation, fetch the page through `confluence_get_page`; for attachments, also call `confluence_list_attachments`. Save those pre-write responses as the operation snapshot. Because attachment reads expose metadata rather than bytes, use a new filename unless original bytes were captured through a supported read. Dual-mode operations dry-run first and execute only after explicit approval. The dry-run response must contain a snapshot and `preview_digest`; absence of either blocks the execute call. For example, an attachment preview and apply use:

```js
cse_apply({
  capability: "confluence_upload_attachment",
  arguments: {
    page_id: "<page-id>",
    file_path: "/tmp/<diagram>.png"
  },
  execute: true,
  justification: "Preview the approved report image attachment"
})
```

```js
cse_apply({
  capability: "confluence_upload_attachment",
  arguments: {
    page_id: "<page-id>",
    file_path: "/tmp/<diagram>.png",
    execute: true,
    preview_digest: "<digest-from-preview>"
  },
  execute: true,
  justification: "Attach the approved report image"
})
```

After an attachment apply, call `confluence_get_page` and `confluence_list_attachments`; assert the page id/title/parent/version and body are unchanged except for the approved reference, and that the expected filename is present. The same preview/digest split applies to `confluence_create_page` and `confluence_update_page`; prose bodies must use a `/tmp` `body_storage_path`, and updates must include `page_id` plus `expected_version`. After a page apply, GET the page by the returned or existing id and assert title, parent, expected new version, and exact intended storage body. This skill still doesn't publish by default.

## Editing Scope

This skill provides no WYSIWYG editor, save-back server, token scheme, or universal `--edit` flag. Edit generated source/model files and re-render, or use a separately supplied renderer under its own documented and tested contract. Do not advertise inline editing as an output of this skill.

## Agent-Implemented Copy Contract

The agent's HTML artifact must implement two layers:

- Preview shell: a local renderer wrapper, optional copy controls, and manifest summary.
- Copy root: `article[data-copy-root]`, containing only the report body with Confluence-compatible renderer classes such as `ak-renderer-document`, `ProseMirror`, `ak-editor-panel`, and `pm-table`.

If the agent implements a `Copy report` button, it must write both `text/html` and `text/plain`. If the browser blocks rich clipboard access, it must fall back to a plain-text clipboard write and show a status message. Without a tested button, the report must still make `article[data-copy-root]` directly selectable and must not claim clipboard automation.

The copy root must use paste-safe HTML:

- headings
- paragraphs
- bold, italic, inline code
- ordered and unordered lists
- simple tables
- styled callout boxes
- generated diagram images as `<img>` tags

Avoid interactive widgets, Mermaid runtime blocks, external CSS, proprietary Atlassian bundle copies, and script-dependent content inside the copy root.

## Diagrams

Generate diagrams as actual images, not Mermaid placeholders, when the report needs a visual.

Prompt rules:

- Describe the diagram style and structure, not internal raw data.
- Keep labels short. Generated image text is fallible, so do not rely on tiny labels for critical facts.
- Prefer executive-readable systems diagrams, rollout flows, swimlanes, state summaries, and simple architecture maps.
- Save prompt, model, output path, bytes, status, and auth source in the manifest.

If diagrams are skipped, include the exact reason in `.manifest.json` and render an explicit warning callout where the diagram would have appeared.

## Voice

Use `plugins/cse-tools/.agents/shared/prose-voice.md` and the active profile from `skill-bootstrap.sh`.

Minimum report checks:

- no bot identity language
- no copied calibration strings
- no Unicode em dash
- no `Source:` scaffolding in reader-facing prose
- contractions by default
- concrete, consequence-first framing
- no unsupported customer claims

## Success Criteria

- The HTML opens locally and the agent verifies the report body is selectable from `article[data-copy-root]`; clipboard automation is claimed only when tested.
- A reported Google Docs paste check records which headings, lists, links, tables, callouts, and images were preserved; untested compatibility isn't claimed.
- A reported Confluence paste check records preserved structure where the editor allows it; `.storage.html` is emitted as the fallback.
- Diagram assets are real PNGs only when a verified generator produced them; otherwise the manifest and report contain the explicit skip reason.
- The manifest records paths, diagram prompts/results, copy compatibility details, and validation status.
- Focused tests for the renderer or report script actually used pass before handing the report back; if rendering was direct, validate that every emitted artifact opens/parses and all manifest paths exist.