---
name: shared-context-report
description: Create a professional shared-context report for imdone stories, including executive summary, ranked shared-context quality, current-state summary, risk assessment, pie chart, and PDF output. Use when a user asks to assess story handoff readiness, brief others on active work without interrupting the team doing it, compare planning artifact quality across a list like DOING or In Progress, or generate/update the shared-context report files. The report content should refer to the active work set as In Progress even when the underlying imdone query uses DOING.
---

# Shared Context Report

Use this skill when a user wants a durable, professional report that answers which stories have the best shared context, which are risky to hand off, where planning artifacts are weak, how to brief others on the active work without interrupting the team doing it, and what low-scoring stories should improve next.

Handoff risk applies to three dimensions: team handoff (another engineer picking up the work), AI context loading (AI agents getting sufficient context to assist), and self-resumption (the original developer picking up their own work after interruption).

This skill generates:

- a markdown report
- a Mermaid pie-chart source file
- a rendered SVG pie chart
- a PDF version of the report

## Workflow

Run the wrapper:

`./.codex/skills/shared-context-report/scripts/create_shared_context_report.sh --list DOING --outdir /tmp`

Filtered subset:

`./.codex/skills/shared-context-report/scripts/create_shared_context_report.sh --query 'meta.jira=/^TEAM/' --scope-label TEAM --outdir /tmp`

Single story:

`./.codex/skills/shared-context-report/scripts/create_shared_context_report.sh --issue SCRUM-240 --outdir /tmp`

Optional flags:

- `--list <name>` defaults to `DOING`
- `--query <expr>` adds an extra `imdone` filter on top of the selected list, such as `meta.jira=/^TEAM/`
- `--scope-label <name>` gives a filtered query a cleaner report title and output basename
- `--issue <key>` generates the report for one local story or task by issue key
- `--outdir <dir>` defaults to `/tmp`
- `--basename <name>` overrides the default output prefix

## What it does

1. Queries `imdone ls -q list=<LIST> -f json`, or `imdone ls -q 'list=<LIST> AND <QUERY>' -f json`, or loads one local story directly when `--issue <KEY>` is used
2. Filters to `Story`, `Task`, and pull-request work items
3. Reads planning context from the issue content and supporting markdown files under `attachments/`
4. Scores shared-context quality and handoff risk using deterministic heuristics
5. Writes deterministic shared-context improvement advice for low-scoring stories and tasks, plus deterministic unblock advice for items carrying blocked provider metadata
6. Writes a professional markdown report with `backlog/...` paths
7. Writes a pie chart `.mmd`
8. Renders the pie chart to SVG using Docker Mermaid
9. Renders the markdown report to PDF using the `markdown-pdf-docker` renderer

## Dependencies

- Docker daemon access
- Local image `codex/markdown-pdf-docker:latest`

If the image is missing, the wrapper will try to build it via:

`./.codex/skills/markdown-pdf-docker/scripts/build_image.sh`

## Notes

- The ranking and risk assessment are heuristic, not product-judgment-perfect. The report should discuss planning context, not attachments directly. Supporting markdown file names should make the specific task or boundary obvious, not just echo the overall story theme. After generation, read the top-ranked stories and refine narrative if the user wants stronger qualitative reasoning.
- Shared-context advice is deterministic and intentionally simple. It should point to the next context-improving move for weak stories and hard-to-review pull requests, not pretend to diagnose root cause perfectly.
- Blocked-work advice is also deterministic. It should use local blocked metadata plus visible local text signals to point readers toward communication, mock-to-real integration, feature-flag follow-up, or a neutral unblock fallback.
- Paths in the report intentionally start with `backlog/`.
- Use `In Progress` in report headings and prose when the queried list is `DOING`. When `--issue <KEY>` is used, refer to the work set as `Story <KEY>`. When `--query <expr>` is used, it narrows the selected list rather than replacing it, so `--query 'meta.jira=/^TEAM/'` with the default list still means in-progress `TEAM` work. Prefer `--scope-label <name>` if the user asked for a named subset such as a Jira project prefix.
- If Docker is blocked by the sandbox, request escalation and proceed.
