stakeholder-reporting

name	stakeholder-reporting
description	This skill should be used when the user asks to "create a sourcing report", "build a dashboard", "generate a pipeline update", "update for hiring manager", "stakeholder report", "sourcing metrics", "pipeline report", "weekly sourcing update", "market insights report", "talent map presentation", or needs to compile sourcing data into structured reports or visual dashboards for stakeholders.

Stakeholder Reporting for Recruiting Sourcing

Purpose

Compile sourcing data, insights, and progress into structured reports and visual dashboards for hiring managers and leadership. Effective reporting transforms sourcing activity into clear, actionable narratives that build stakeholder confidence and drive hiring decisions.

Report Types

1. Sourcing Pipeline Report

Regular update on sourcing progress for a specific role.

Audience: Hiring manager Frequency: Weekly or bi-weekly Format: Markdown summary + optional HTML dashboard

Contents:

• Candidates identified this period
• Outreach status and response rates
• Pipeline stage breakdown
• Key candidate highlights
• Blockers and recommendations

2. Market Insights Report

Research-driven report on the talent market for a role or function.

Audience: Hiring manager + leadership Frequency: At search kickoff, updated monthly Format: Markdown report + HTML dashboard with charts

Contents:

• Compensation landscape
• Talent supply & demand analysis
• Competitive landscape
• Hiring difficulty assessment
• Strategic recommendations

3. Talent Map Report

Visual representation of the talent landscape.

Audience: Hiring manager + leadership Frequency: At search kickoff Format: Markdown + HTML with interactive tables

Contents:

• Target company matrix (concentric circles)
• Pool size estimates by segment
• Geographic distribution
• Key individual highlights
• Recommended approach per segment

4. Search Retrospective

Post-search analysis of what worked and what didn't.

Audience: Recruiting team + hiring manager Frequency: After role is filled Format: Markdown report

Contents:

• Search timeline and milestones
• Channel effectiveness analysis
• Funnel conversion rates
• Lessons learned
• Recommendations for future searches

Markdown Report Structure

Standard Report Template

# [Report Type]: [Role Title]
**Date:** [Date]  |  **Author:** [Name]  |  **Status:** [Active/Closed]

## Executive Summary
[3-5 bullet points with key findings and recommendations]

## [Section 1]
[Content with supporting data]

## [Section 2]
[Content with supporting data]

## Key Metrics
| Metric | Value | Trend |
|--------|-------|-------|
| [Metric 1] | [Value] | [↑/↓/→] |
| [Metric 2] | [Value] | [↑/↓/→] |

## Recommendations
1. [Actionable recommendation]
2. [Actionable recommendation]

## Next Steps
- [ ] [Action item with owner]
- [ ] [Action item with owner]

Pipeline Metrics Table

## Pipeline Overview

| Stage | Count | This Week | Conversion |
|-------|-------|-----------|------------|
| Identified | 45 | +12 | - |
| Contacted | 28 | +8 | 62% |
| Responded | 14 | +3 | 50% |
| Interested | 8 | +2 | 57% |
| Screened | 5 | +1 | 63% |
| Submitted to HM | 3 | +1 | 60% |

HTML Dashboard Generation

For visual dashboards, generate standalone HTML files using Chart.js for charts. Dashboards should be self-contained (no external dependencies beyond CDN) and openable in any browser.

Dashboard Template

Use the full template from references/dashboard-templates.md. It includes HTML structure, CSS, Chart.js setup, KPI cards, pipeline funnel, source channel doughnut, and candidate table with placeholder comments.

Chart Types for Sourcing

Pipeline funnel - Horizontal bar chart showing conversion through stages Source effectiveness - Pie or doughnut chart of candidates by source channel Timeline - Line chart of pipeline growth over time Talent map - Table with color-coded priority indicators Compensation - Box plot or range chart for salary data

Dashboard Best Practices

• Use 4-6 KPI cards at the top (total identified, response rate, pipeline health, time-in-stage)
• Include 2-3 charts maximum per dashboard
• Keep one actionable table (top candidates, target companies, or pipeline)
• Use consistent color scheme aligned with company brand
• Ensure all data has context (comparisons, benchmarks, trends)
• Include last updated timestamp prominently
• Make it printable (reasonable page breaks, no horizontal scroll)

Report Writing Guidelines

For Hiring Managers

• Lead with insights, not activity metrics
• Frame data around decisions they need to make
• Use comparisons: "This search is performing 20% above average response rate"
• Highlight blockers clearly with recommended solutions
• Keep reports scannable: bullets, tables, bold key numbers

For Leadership

• Focus on strategic insights over tactical details
• Include market context (supply/demand, compensation trends)
• Frame recommendations in business terms
• Quantify trade-offs: "Expanding budget by €20K increases pool by 40%"
• Keep to one page / one screen when possible

Data Integrity

• Always cite data sources
• Note data recency and limitations
• Distinguish between hard data and estimates
• Flag where sample sizes are small
• Use ranges rather than false precision

File Organization

Store reports in the role-based directory structure:

roles/
└── senior-backend-engineer/
    └── reports/
        ├── pipeline-week-NN.md            ← e.g., pipeline-week-06.md
        ├── market-insights-YYYY-MM.md     ← e.g., market-insights-2026-02.md
        ├── dashboard.html                 ← updated in place
        └── retrospective.md

Brand Guidelines

All branded reports and PDF-exportable deliverables MUST follow the QuoIntelligence brand guidelines. See .claude/skills/stakeholder-reporting/references/brandguidelines.pdf for the complete specification including:

• 60-30-10 color rule — White (60%), QUO Sec Blue (30%), QUO Main Orange (10%)
• Typography — Inter font family at specified weights and sizes
• Logo placement — White logo on dark headers, dark logo on light footers
• Print CSS — Required @media print rules for browser-to-PDF export
• CSS custom properties — Standardized variables for all templates

PDF Export Workflow (Automated — Puppeteer)

The preferred method uses a mechanical pipeline that avoids Chrome's default header/footer (which prints file:/// URLs on every page):

Pipeline: markdown → HTML body → branded HTML → Puppeteer PDF

# Step 1: Strip any metadata lines (e.g., "Analyst:" prefix) from source markdown
sed '/^Analyst:/d' SOURCE.md > /tmp/market-clean.md

# Step 2: Convert markdown → HTML body fragment
npx marked --gfm /tmp/market-clean.md > /tmp/market-body.html

# Step 3: Build branded HTML wrapper (see references/market-insights-template.md)
#   - Base64-encode logos from .claude/assets/PNG/
#   - Inject body HTML into branded template with CSS, charts, print styles
#   - Charts use hidden divs + DOMContentLoaded JS to relocate inline
bash /tmp/build-branded.sh   # outputs /tmp/market-branded.html

# Step 4: Generate PDF with Puppeteer (no URL footer)
node /tmp/print-pdf.mjs

Puppeteer script (print-pdf.mjs):

import puppeteer from 'puppeteer';
const browser = await puppeteer.launch({
    headless: true,
    executablePath: '/usr/bin/google-chrome-stable',
    args: ['--no-sandbox', '--disable-gpu', '--disable-setuid-sandbox']
});
const page = await browser.newPage();
await page.goto('file:///tmp/market-branded.html', { waitUntil: 'networkidle0', timeout: 30000 });
await page.pdf({
    path: 'roles/[role-name]/reports/market-insights-YYYY-MM.pdf',
    format: 'A4',
    printBackground: true,
    displayHeaderFooter: false,
    margin: { top: '10mm', bottom: '10mm', left: '0', right: '0' }
});
await browser.close();

Key details:

• displayHeaderFooter: false — suppresses Chrome's default URL/date footer on every page
• printBackground: true — required for brand colors (blue header, table headers, chart cards)
• Logos are base64-embedded in the HTML for self-contained output
• Charts use Chart.js loaded from CDN; hidden initially then repositioned via DOM relocation
• The Puppeteer script must run from a directory where puppeteer is installed as a Node module

Chart DOM relocation technique: Charts are placed as hidden <div> blocks after the </div> closing the content body. A DOMContentLoaded script scans <h3> headings for section numbers (e.g., "1.4", "3.2") and uses insertBefore() to move the chart blocks to their contextually correct positions. This keeps the markdown→HTML conversion mechanical while placing charts inline.

Why not --print-to-pdf-no-header? Chrome's CLI flag does not reliably suppress the source URL footer in Chrome 133+. Puppeteer's displayHeaderFooter: false is the correct solution.

PDF Export Workflow (Manual Fallback)

If Puppeteer is unavailable:

1. Generate the HTML report using the branded template
2. Open in browser and verify layout
3. Print to PDF: Ctrl+P / Cmd+P, Save as PDF, Background graphics: ON
4. Save to roles/[role-name]/reports/

Additional Resources

Reference Files

You are stongly encouraged to read the reference files

• references/brandguidelines.pdf - your brand guidelines
• references/market-insights-template.md - Branded HTML template for market insights reports (PDF-ready)
• references/dashboard-templates.md - Complete HTML dashboard templates for pipeline dashboards
• references/chart-examples.md - Chart.js code snippets for common sourcing visualizations