Cma PDF Current Comps Workflow

CMA PDF current-comps workflow

Honor the project contract

1. Resolve the actual directory containing this SKILL.md as the skill root. All required template code, branding, and instructions are inside it; do not look for a separate Desktop project.
2. Read references/project-instructions.md completely before research, report writing, code changes, or generation. It contains the full original project contract, including provenance, adjustment derivation, report structure, and quality requirements.
3. Use the PDF skill alongside this skill for rendering and visual inspection when available, while keeping this skill's existing report design.
4. Use the bundled scripts/generate_pdf_report.py as the only final rendering pipeline. Do not substitute HTML print, DOCX, LaTeX, a generic PDF script, or a reconstructed design.
5. Use the original logos in assets/. The renderer checks their hashes and requires the approved Arial and Georgia font files. Missing or different fonts, logos, or dependencies are setup errors; never silently substitute them or claim the original format was preserved.
6. Honor an explicit user output path; otherwise use ~/Desktop/Reports. Always pass an explicit absolute --output path. Keep generated reports and research outside the installed skill folder.

Prepare a new device

Read references/setup.md for pinned Python packages, Poppler, font requirements, installation updates, and platform-specific setup. Fonts are licensed local dependencies and are not included as redistributable files.

Run scripts/check_environment.py using the Python interpreter that will generate the report. On a new installation or after a renderer/dependency update, also run scripts/verify_format.py. It renders the bundled synthetic sample and compares every page with references/format-reference.pdf at 144 DPI. Require both checks to pass before claiming that the device preserves the original formatting.

The shell examples below assume the default installation and a python3 that passes preflight. Resolve the actual skill directory if installed elsewhere; use the virtual-environment interpreter from the setup guide when needed.

CMA_SKILL_DIR="${CODEX_HOME:-$HOME/.codex}/skills/cma-pdf-current-comps-workflow"
python3 "$CMA_SKILL_DIR/scripts/check_environment.py"
python3 "$CMA_SKILL_DIR/scripts/verify_format.py" --work-dir "$PWD/work/cma-format-check"

If using --font-dir, pass the same directory to preflight, format verification, and report generation. If setup cannot pass, report the precise missing dependency and stop before generating a differently formatted PDF.

Start with preflight

1. Confirm the exact subject address, user-provided facts, purpose, audience, requested output, and whether overwrite is intended.
2. Proceed from an address alone when the property is identifiable. Ask only if identity is ambiguous or an unbracketable missing fact would materially change the analysis.
3. Inspect scripts/generate_pdf_report.py in full, assets/, recent report Markdown, recent working notes, the bundled formatting reference, dependencies, and the named existing PDF if refreshing.
4. Run python3 scripts/generate_pdf_report.py --help from the skill root and inspect the bundled baseline before any narrow generator change.
5. Preserve unrelated user changes. Modify the generator only for a confirmed reusable defect or a required field that cannot be represented through its current Markdown/HTML input.

Research fresh evidence

1. Use the current date as the effective date and record source-access dates in internal working notes.
2. Normalize the subject profile before selecting comps. Apply the full contract's [U] user-provided / [W] web-sourced / [A] assumed provenance waterfall, with sources, retrieval dates, conflicts, and uncertainty preserved.
3. Research official public records first, then direct listing or sold pages, Realtor association reports, government economic data, reputable local sources, and secondary aggregators.
4. Treat automated valuations as secondary context only. Never treat an asking price as equivalent to a closed sale.
5. Target four to six defensible closed sales from a broader pool of six to ten candidates when the market permits. Start within six months and the same competitive market; expand only in the documented sequence in the full project instructions. Disclose thin evidence instead of inventing comps or adjustments.
6. Select two to four active or pending competitors when available. Label pending figures as list prices unless the sale has closed.
7. Create the weighted comp-screening table in internal notes before choosing final comps. Weight location and buyer pool most heavily; downgrade anomalous, non-arm's-length, poorly verified, or heavily adjusted candidates.
8. Research macro and micro conditions with the correct geography and period. Do not mix county, city, ZIP, median, and average figures without explanation.
9. Browse live sources for every new report. Reuse prior reports only for formatting and workflow, never for stale comps, prices, market statistics, or value conclusions.

Read references/report-contract.md before drafting the report. It contains the required evidence classifications, report order, comp fields, valuation constraints, and closeout gates.

Keep auditable working files

1. Store report Markdown and internal research notes under the current task's work/cma/ tree, not inside the installed skill or final Reports folder.
2. Include source labels, URLs, access dates, quoted or paraphrased support, data conflicts, rejected comps, expansion decisions, adjustment support, and the mandatory self-check in the internal notes.
3. Keep private reasoning out of the report. Include concise decision-useful rationale, assumptions, and limitations.
4. Do not silently replace a user-provided fact. Resolve or disclose every material conflict.

Draft the report

Follow the exact section order required by the bundled project instructions:

1. Executive Summary
2. Property Description and Initial Assessment
3. Macro Market Analysis
4. Micro Market Analysis
5. Comparable Sales Analysis
6. Competitive Listing Analysis
7. Valuation Estimate
8. SWOT Analysis
9. Market Outlook and Conclusion
10. Sources, Assumptions, and Limiting Conditions

Use descriptive Markdown links such as [County assessor property record](https://...). Do not display bare URLs. State the value range, single most-likely value, effective date, valuation premise, and confidence level consistently. Include the required no-inspection, public-data, non-appraisal, and professional-verification limitations.

Choose the final path

Generate the required filename before rendering:

python3 "${CODEX_HOME:-$HOME/.codex}/skills/cma-pdf-current-comps-workflow/scripts/next_report_path.py" \
  --street-address "54499 Cemetery Road" \
  --city "Calumet" \
  --date "2026-07-09"

Use the printed absolute path. The helper preserves existing files by appending _v2, _v3, and so on. For an explicitly requested replacement, use the exact existing path and pass --overwrite to the renderer; the filename helper does not accept that flag.

Generate through the authoritative pipeline

Use explicit absolute paths:

python3 "${CODEX_HOME:-$HOME/.codex}/skills/cma-pdf-current-comps-workflow/scripts/generate_pdf_report.py" \
  --input "/absolute/path/to/report.md" \
  --output "$HOME/Desktop/Reports/Street_City_Market_Analysis_YYYY-MM-DD.pdf" \
  --address "Full subject address" \
  --prepared-for "Seller" \
  --date "Month D, YYYY"

Use --no-photo-gallery only when no property photos should appear. The brand assets remain embedded. If the user explicitly requested overwrite, pass --overwrite after resolving and confirming the exact target.

Validate the artifact

Run the bundled deterministic closeout helper:

python3 "${CODEX_HOME:-$HOME/.codex}/skills/cma-pdf-current-comps-workflow/scripts/validate_cma_pdf.py" \
  "$HOME/Desktop/Reports/example.pdf" \
  --source "/absolute/path/to/report.md" \
  --expected-address "Full subject address" \
  --expected-text '$150,000 - $180,000' \
  --expected-text '$165,000'

The helper must pass file, page, text, heading, hyperlink, Letter-size, raw-URL, placeholder, and rendered-page checks. It prints the rendered-page directory.

Then inspect every rendered PNG visually. Verify branding, cover, margins, headings, tables, wrapping, page breaks, page numbering, values, dates, address, links, and absence of clipping or blank pages. Compare with an existing baseline when available. Regenerate through generate_pdf_report.py until both deterministic and visual checks pass.

Finish honestly

Do not claim completion from source review alone. In the final response, state:

1. The exact clickable PDF path.
2. The estimated value range and most-likely value.
3. The confidence level and the most material evidence limitation.
4. The completed technical and visual validation.

Keep conclusions property- and date-specific. Never imply MLS access, a physical inspection, legal conclusions, or licensed-appraisal status unless those facts are explicitly true.