adu-corrections-pdf - SKILL.md Agent Skill

name: adu-corrections-pdf description: "Formats a draft corrections letter (markdown) into a professional PDF. Single-purpose formatting sub-agent — no research. Receives markdown from the research agent, generates a styled PDF using the document-skills/pdf primitive, and returns a screenshot for QA. If the main agent finds issues in the screenshot, it will re-invoke this skill with fix instructions."

ADU Corrections PDF Generator

Overview

Take a draft corrections letter in markdown and produce a professional PDF. This is a formatting-only sub-agent invoked by the research agent at the end of the pipeline.

Depends on: document-skills/pdf — the primitive PDF skill. Load it for the actual PDF generation tools (reportlab for Python, pdf-lib for JavaScript). This skill adds the domain-specific formatting on top.

What This Skill Does and Does NOT Do

Does	Does NOT
Apply city letterhead styling	Research codes or review plans
Format sections, tables, confidence badges	Modify correction content
Generate paginated PDF	Make judgment calls about findings
Return screenshot for QA	Decide what goes in the letter

Inputs

Input	Format	Required
Draft corrections markdown	`.md` file path	Yes
City name	String	Yes
Project address	String	Yes
Project info	Object: applicant, designer, engineer, scope, dates	Yes
Output path	File path for the `.pdf`	Yes
Fix instructions	String (only on re-invocation after failed QA)	No

Outputs

Output	Format
Corrections letter PDF	`.pdf` at specified output path
QA screenshot	`.png` of page 1 — returned to calling agent

Workflow

Step 1: Read Draft Markdown

Read the .md file. Validate expected structure: header block, notice, numbered sections, summary tables. Log warnings on unexpected structure but don't fail.

If fix_instructions are provided (re-invocation after failed QA), apply them before generating. Fix instructions might say: "Header is cut off — add more top margin" or "Table overflows page — reduce font size."

Step 2: Generate PDF

Use the document-skills/pdf primitive skill for the actual PDF generation. Two recommended approaches:

Approach A: reportlab (Python — best for structured layouts)

Use reportlab.platypus (SimpleDocTemplate, Paragraph, Table, Spacer, PageBreak) to build the letter programmatically. See document-skills/pdf/SKILL.md for reportlab patterns. This gives the most control over pagination, headers/footers, and table formatting.

Key reportlab elements for this letter:

SimpleDocTemplate with letter pagesize and margins
Paragraph with custom styles for section headers, item titles, body text, code citations
Table + TableStyle for the review summary and sheet manifest tables
Custom PageTemplate for the city letterhead header and draft footer on every page

Approach B: markdown → HTML → PDF (faster to implement)

Convert markdown to HTML (use marked npm or Python markdown library)
Inject into HTML template with references/letter-styles.css
Render to PDF using puppeteer, md-to-pdf, or wkhtmltopdf

See document-skills/pdf/reference.md for pypdfium2 rendering and pdf-lib JavaScript options.

Step 3: Screenshot for QA

Convert page 1 of the generated PDF to a PNG. Use document-skills/pdf tools:

# Using pypdfium2 (from document-skills/pdf/reference.md)
import pypdfium2 as pdfium
pdf = pdfium.PdfDocument("corrections_letter.pdf")
bitmap = pdf[0].render(scale=2.0)
img = bitmap.to_pil()
img.save("qa_screenshot.png")

Or command line:

pdftoppm -png -r 200 -f 1 -l 1 corrections_letter.pdf qa_screenshot

Return the screenshot path to the calling agent. The calling agent handles the QA decision — this skill just provides the screenshot.

Letter Format Spec

Page Layout

Size: US Letter (8.5" x 11")
Margins: 1" top/bottom, 0.75" left/right
Font: Arial/Helvetica — 10pt body, 12pt section headers, 14pt city name
Line spacing: 1.3

Header (every page)

CITY OF [CITY NAME]
BUILDING AND SAFETY DIVISION
PLAN CHECK CORRECTIONS — AI-ASSISTED DRAFT

AI Notice Banner (page 1 only)

Light yellow box with amber border:

NOTICE: This is an AI-generated DRAFT corrections letter. Items flagged [VERIFY] require closer inspection. Items flagged [REVIEWER] require licensed professional assessment. A human plan checker must review and approve before issuance.

Confidence Badges (inline, color-coded)

CONFIRM → green (quick check, HIGH confidence)
VERIFY → amber (needs closer look, MEDIUM confidence)
REVIEWER → red (requires licensed professional)
COMPLETE → gray (human must fill in entirely)

Footer (every page)

Page [N] of [M]
AI-Assisted Draft — Not For Issuance Without Review
CrossBeam ADU Plan Review | [Timestamp]

Section Order

Planning / Zoning
Building
Site / Civil
Fire / Life Safety
Structural [REVIEWER]
Process Notes (Informational)
Review Summary (tables)

Dependencies

Skill	What It Provides
`document-skills/pdf`	PDF generation primitives — reportlab, pypdf, pdf-lib, pypdfium2, command-line tools

References

File	Contents
`references/letter-styles.css`	CSS stylesheet — only used if taking the HTML→PDF approach

Important Notes

Never modify correction content. Format exactly as received. Content issues are the research agent's problem.
Every page must say DRAFT. Header, footer, and notice banner. This document cannot be mistaken for an official city issuance.
Fail gracefully. If styling breaks, produce a plain-formatted PDF anyway. A plain PDF beats no PDF.
Accept fix instructions. When re-invoked after a failed QA, the main agent will provide specific fix instructions. Apply them and regenerate.