vendor-positioning-report

What this skill does

# Vendor Positioning Report

Create independent, evidence-based vendor evaluation reports with an original two-axis positioning matrix. Treat requests for "magic quadrants" as requests for an **Independent Vendor Positioning Matrix** unless the user proves written permission and legal approval to use Gartner-owned naming or materials.

## Hard Rules

- Do not title reports "Magic Quadrant" or imitate Gartner, Forrester, IDC, Everest, ISG, or other analyst-firm trade dress, rankings, labels, report language, or graphics.
- Do not summarize, transform, scrape, or reconstruct paywalled analyst reports into a lookalike report.
- Use original axes, labels, scoring, visual style, and report structure.
- Cite every non-obvious factual claim with source IDs from `data/source_ledger.csv`.
- Separate evidence from assessment. Use explicit gaps such as `No public evidence found`, `Vendor confirmation required`, or `Internal SME assessment required`.
- Include the independent research disclaimer in every final report, including PDF and Microsoft Word outputs.
- For regulated financial-services contexts, include security, resilience, data residency, outsourcing risk, exit, auditability, identity integration, and contractual-control checks.

## Quick Start

When starting a new report package, scaffold the repository:

```bash
python <skill-dir>/scripts/scaffold_report.py --target . --market "Market name" --as-of-date YYYY-MM-DD --target-format pdf
```

Then work in this order:

1. Read or update `report_config.yaml`.
2. Define the market before selecting vendors.
3. Create inclusion and exclusion criteria before scoring.
4. Build a vendor longlist from public sources and internal input.
5. Research each vendor and populate `data/source_ledger.csv`.
6. Create one factsheet per included vendor in `data/vendor_factsheets/`.
7. Fill `data/scoring_evidence.csv` with cited, dimension-level scoring evidence.
8. Run `scripts/score_vendors.py` to produce `data/scoring_results.csv`.
9. Run `scripts/render_matrix.py` to produce the matrix PNG. Use the default observed-axis viewport for readability; use `--axis-mode full` only when the report needs a fixed 0-100 benchmark view.
10. Confirm or read the target output from `outputs.target_format`: `pdf`, `docx`, or `both`. If the user has not specified a target and the deliverable format matters, ask whether they want PDF, Microsoft Word, or both.
11. Write the report Markdown. For PDF, run `scripts/build_report.py` and `scripts/verify_pdf.py`; if WeasyPrint is unavailable, use `scripts/build_pdf_reportlab.py` as the PDF fallback. For Microsoft Word, run `scripts/build_docx.py` and `scripts/verify_docx.py`.
12. Deliver the selected PDF and/or DOCX target plus Markdown, matrix PNG, source ledger, scoring results, and review checklist.

## References

Load only the files needed for the current task:

- `references/report_workflow.md`: repository structure, report workflow, deliverables, and quality gates.
- `references/source_policy.md`: source tiers, source ledger schema, citation rules, and search patterns.
- `references/scoring_model.md`: default axes, dimensions, scoring formula, confidence handling, and CSV schema.
- `references/templates.md`: reusable text templates for AGENTS.md, market definition, vendor factsheets, RFI questions, disclaimer, and review checklist.
- `references/pdf_style_guide.md`: PDF, Word, and chart style rules that avoid analyst-firm imitation.

## Scripts

- `scripts/scaffold_report.py`: create the standard report repository structure and copy helper scripts.
- `scripts/score_vendors.py`: compute axis scores from `scoring_evidence.csv` and `methodology/scoring_model.yaml`.
- `scripts/render_matrix.py`: render an original two-axis matrix from `scoring_results.csv`.
- `scripts/build_report.py`: render Markdown from Jinja templates and optionally write HTML/PDF when dependencies are available.
- `scripts/build_pdf_reportlab.py`: build a simpler PDF from rendered Markdown when WeasyPrint or its native dependencies are unavailable.
- `scripts/build_docx.py`: build a Microsoft Word `.docx` report from rendered Markdown.
- `scripts/verify_pdf.py`: check that a PDF exists, has pages, has extractable text, and can render page PNGs.
- `scripts/verify_docx.py`: check that a DOCX exists, is a valid Word package, has document text, and optionally includes images.

Use the scripts as accelerators, not as a substitute for judgment. If dependencies are missing, install or adapt them in the report repository and document the verification result.

## Research Workflow

Start with the market definition. State buyer problem, mandatory capabilities, excluded adjacent categories, deployment scope, geography, buyer segment, strategic relevance, risk/procurement implications, and research cut-off date.

Create a vendor longlist before inclusion decisions. Acceptable sources include official product docs, security pages, release notes, pricing pages, customer stories, cloud marketplaces, certification registries, public filings, standards bodies, reputable technical media, internal inventories, and RFI/RFP responses supplied by the user.

For current vendor facts, browse or otherwise verify live sources. Prefer primary sources for capabilities, security, compliance, pricing, release history, and support. Treat vendor-sponsored claims and customer stories as partial evidence, not proof of general performance.

Create vendor factsheets with evidence summaries, confidence, assessment, evidence gaps, and due-diligence questions. Never fill missing evidence with plausible claims.

## Scoring And Matrix

Use the default model unless the user provides a buyer-specific model. The standard axes are:

- `Execution Strength`
- `Strategic Direction Fit`

Score each dimension from 0 to 5, then apply evidence-strength and recency modifiers. Normalize each axis to 0-100. Keep confidence separate from score so low-evidence vendors are visible without pretending certainty.

Do not force an even quadrant distribution. Clustering is acceptable in the underlying scores. For readability, the chart may zoom the X/Y display axes to the observed score range, but the report must disclose that the scores remain normalized to 0-100 and the viewport is zoomed. Use `--axis-mode full` when absolute distance from 0 or 100 is the intended visual message.

Use neutral quadrant labels such as `Strategic Leaders`, `Innovation Bets`, `Execution Anchors`, and `Specialist Plays`, or adapt them to the buyer context.

## Report Standards

Write the report in plain internal research language. Avoid hype and vendor marketing phrasing unless clearly labeled as a vendor claim. Use absolute dates for time-sensitive statements.

Final reports must include:

- Executive summary and recommended next actions.
- Market definition and inclusion/exclusion criteria.
- Matrix and explanation of axes, thresholds, and confidence.
- Vendor profiles with evidence, assessment, implication, confidence, and gaps.
- Bank or regulated-enterprise due-diligence appendix when relevant.
- Methodology appendix with dimensions, weights, and source policy.
- Source appendix expanding all source IDs.
- Independent research disclaimer.
- Human review checklist.

Before final delivery, verify the selected target format. For PDF, verify that the PDF renders, tables are legible, and page-render QA artifacts are kept outside `outputs/final`. For Microsoft Word, run structural verification with `scripts/verify_docx.py`; when document rendering tools are available, render the DOCX to page images and inspect the matrix and tables before delivery. In all formats, verify that citations resolve to the ledger and the report does not imply the top-right vendor is automatically the correct choice.

Keep `outputs/final` clean for deliverables. If PDF page renders are needed for QA, write them to `outputs/draft/pdf-render-check` via `scripts/verify_pdf.py --render-dir outputs/draft/pdf-render-check`, or run