Ambiguity Report

Ambiguity Report

Take an interpretive-ambiguity analysis of a legal text and turn it into a polished deliverable in one of six formats: multi-page website (the default), single-page interactive website, single-file HTML, Microsoft Word document, PowerPoint deck, or LaTeX source for a PDF.

Before promising a format, know what this host can do. Four of the six formats have requirements the host may not meet, and discovering that after the spec is built wastes the user's effort. Run the capability check in Stage 3 first.

The skill's central insight: the data is the same across formats, the rendering is not. An ambiguity analysis is a set of scenarios — each with a situation, two opposed positions, a weak point in the text, a likely outcome, and a proposed redraft — anchored to provisions of a source text. Once that data is captured in the canonical spec, the right format follows from how the deliverable will be used.

Workflow

This skill has four stages. Stages 1–3 are setup; stage 4 is rendering.

• Stage 1 — Identify the input. Determine what kind of analysis the user is handing over. Three common shapes: (a) the structured markdown output of the ambiguity-stress-test skill; (b) a less-formal report or memo with scenarios identified but not all seven canonical fields filled in; (c) raw prose that names some ambiguities but isn't formatted as scenarios at all. The strategy for each shape differs — see resources/parsing-unstructured.md.
• Stage 2 — Build the canonical spec. Convert the input into a structured JSON spec that every renderer can consume. The schema is in resources/data-format.md. Fill in defaults for missing fields rather than blocking on completeness, and surface to the user what was inferred so they can correct.
• Stage 3 — Choose the format and design. Confirm with the user which format they want (default: multi-page website). Capture any design overrides (accent color, fonts, brand label). Most users care only about format and accent color; almost everything else has a sensible default.
• Stage 4 — Render. Delegate to the right renderer. The website and LaTeX paths use the bundled generator scripts (scripts/generate_site.py and scripts/generate_latex.py). The Word and PowerPoint paths delegate to the existing docx and pptx skills with content structured for those formats. Format-specific guidance lives in resources/format-{website,docx,pptx,latex}.md.

Stage 1 — Identify the input

Look at what the user supplied. Three signatures to watch for:

Signature A — structured stress-test output. Markdown with sections titled like "## Scenarios" and individual scenarios under headers like "### S-1 —", each containing labeled fields ("Anchors:", "Defect family:", "Weak point:", "Likely outcome:", "Redraft:"). Often produced by the ambiguity-stress-test skill. This is the easy case — parse directly into the canonical spec.

Signature B — semi-structured report. Numbered ambiguities or issues in prose, each with a paragraph or two of explanation. The seven canonical fields may not all be present — the "situation" and "weak point" might be merged; the redraft might be missing entirely. Extract what's there, flag what's missing, and either infer reasonable defaults or ask the user. See resources/parsing-unstructured.md.

Signature C — raw prose. A memo, a draft, or a transcript discussing "places this text is unclear." No formal scenario structure. The skill must do more work: identify candidate ambiguities, split into discrete scenarios, propose a defect family for each. Confirm the extraction with the user before rendering — the rendered output is only as good as the structure.

In all three cases, the source text (the statute / contract / regulation / opinion being audited) needs to be identified. If the input does not include the full source text, ask the user to provide it. The skill can render scenarios without the source, but the result is much weaker — the source is the spine of the document.

Stage 2 — Build the canonical spec

The spec schema is documented fully in resources/data-format.md. The top-level shape:

{
  "meta": { title, subtitle, kicker, audit_date, profile, brand_short, brand_sub },
  "design": { accent_color, accent_soft, dept_color, adv_color, ... },
  "source": { name, sections: [ { id, label, subhead, text, subprovisions: [...] } ] },
  "families": [ { key, label, description, diagnostic } ],
  "scenarios": [ { id, title, tagline, anchors, families, situation, positions, weak_point, likely_outcome, redraft } ],