| 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 marginsParagraph with custom styles for section headers, item titles, body text, code citationsTable + 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:
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.
