Skip to content

reporting-for-practitioners.md

Latest commit

 

History

History
232 lines (150 loc) · 14.5 KB

reporting-for-practitioners.md

File metadata and controls

232 lines (150 loc) · 14.5 KB
Raw

Governance Reporting — A Guide for Project Delivery Professionals

This guide explains the governance document generation capabilities available in the PDA Platform. No technical background is needed.

What this module does

Writing a gate review summary, board exception report, or PIR takes time. Significant time — pulling data from multiple systems, synthesising it into a coherent narrative, translating technical delivery metrics into language a non-specialist board member can act on, and formatting everything to IPA standards. For a complex programme, a Gate 3 summary can take a senior assurance professional a week to write.

The pm-reporting module does not replace that professional judgement. But it does most of the heavy lifting: it gathers all available delivery data from the AssuranceStore, assembles it into a coherent evidence base, and uses Claude to generate structured, IPA-format documents that a practitioner can review, refine, and submit.

The output is not a first draft that needs heavy editing. It is a working document pre-populated with real project data, written in IPA language, that surfaces the key issues. The practitioner's job becomes review and sign-off rather than extraction and formatting.

When to use it

  • When preparing for a gate review and needing to produce a Gate Review Summary document from delivery data held in the store.
  • When the SRO needs a one-page delivery dashboard for a weekly or monthly reporting pack — quickly, without pulling data from multiple sources manually.
  • When a programme has entered exception and you need to brief the board — use the board exception report to translate the situation into non-technical, decision-focused language.
  • When producing a Portfolio Summary for the investment committee or departmental board and need a cross-project view with systemic analysis.
  • When closing a programme and needing to write the Post-Implementation Review — the PIR template pre-populates delivery performance data automatically.
  • When the SRO wants to open a dashboard in their browser showing DCA rating, schedule confidence, cost variance, risks, and benefits at a glance — use the UDS export.

The six tools

1. generate_gate_review_summary — IPA-format gate review document

Gathers all available project data from the store — risks, gate readiness history, benefits, financial data, change requests, confidence scores — and uses Claude to produce a formal IPA Gate Review Summary document.

What it produces:

  • Delivery Confidence Assessment (GREEN / AMBER-GREEN / AMBER / AMBER-RED / RED) with evidence-based rationale
  • Executive Summary — 2–3 paragraphs on the project's delivery position
  • Strengths — bullet list of genuine project strengths grounded in the data
  • Areas Requiring Management Attention — specific issues, gaps, or concerns
  • CONDITIONS — specific, actionable conditions the project must satisfy before proceeding
  • Recommended Actions (optional) — numbered list of recommendations
  • Assessment by Dimension — RAG rating and one-line commentary for all 8 IPA dimensions: Strategic Context and Benefits, Leadership and Stakeholder Management, Risk Management, Governance and Assurance, Financials, Delivery Approach and Schedule, People and Capability, Commercial and Procurement

Key parameters:

Parameter What it controls
gate_number 0 (Strategic Assessment) through 5 (Benefits Evaluation)
reviewer_name Name of the reviewing practitioner
include_recommendations Whether to include a Recommended Actions section (default: true)

Worked example prompt:

"Generate a Gate 3 Review Summary for Project ALPHA-001. The reviewer is Jane Smith. Include recommended actions."

The output is a complete markdown document ready for formatting and submission. The tool references actual data values — risk scores, financial figures, benefit targets — where available in the store. Where data is missing, it notes the gap rather than assuming performance is good.

Important: This document is generated by AI and requires review by a qualified assurance practitioner before submission. The tool includes a standard disclaimer to this effect.

2. generate_sro_dashboard — one-page delivery dashboard

The fastest tool in the module. Fully deterministic — no Claude, no API key needed. Assembles all key delivery metrics from the store into a structured markdown table, typically in under a second.

What it shows:

Section Data
Delivery Status DCA rating, current gate stage, open change request count, schedule P50, EAC vs BAC
Top Risks Up to 5 open risks by risk score, with owner and status
Benefits Status Up to 5 benefits with target value and status
Key Actions Required Derived action list from the above data

Status icons (✅ / ⚠️ / 🔴) are applied automatically based on thresholds.

When to use it: For weekly or monthly SRO reporting packs. The dashboard is deliberately brief — it surfaces exceptions and escalation items, not comprehensive programme detail. For the comprehensive browser-based view, use export_sro_dashboard_data instead.

3. generate_board_exception_report — board-language exception report

Translates technical delivery data into the language a non-specialist board member needs to make a decision. Uses Claude (max 2,000 tokens) to produce a Situation / Implication / Decision Required structure for each exception item.

What it produces:

  • 2–5 exception items, each with Situation, Implication, and Decision Required sections
  • A Recommended Board Resolution — specific, actionable, not vague
  • Written in plain English with no technical jargon
  • References actual figures (financial, risk scores, dates) where data exists

The board exception report is not:

  • A full programme update — it contains only items requiring board awareness or decision
  • A retelling of good news — if no exceptions warrant escalation, the report says so briefly

When to use it: When a programme has entered exception — cost overrun, schedule slippage, a critical risk that has materialised, or a condition from a previous gate review that has not been resolved. Not for routine progress updates.

Worked example output structure:

# Board Exception Report — PROJ-001
Reporting Period: Q1 2026/27  Date: 2026-04-11

## Exception Items

### Exception 1: EAC exceeds BAC by 18%
**Situation:** The latest cost forecast (EAC) has increased to £49.2m against a Budget at Completion of £41.7m...
**Implication:** At current trajectory, the programme will exhaust its approved budget before reaching Gate 4...
**Decision Required:** Board to approve a revised financial envelope of £52m or direct a formal scope reduction...

## Recommended Board Resolution
The board should approve a one-month pause to allow the project team to produce a credible recovery plan...

4. generate_portfolio_summary — cross-project portfolio narrative

Gathers delivery data for a list of projects and produces a portfolio-level summary for investment committees or departmental boards. Uses Claude (max 2,000 tokens) to identify common themes, systemic risks, and recommended interventions across the portfolio.

What it produces:

  • Portfolio Scorecard table — one row per project with DCA, CPI, SPI, top risk, and benefits count
  • Portfolio Health Narrative — 2–3 paragraphs on overall confidence distribution and financial position
  • Common Themes and Systemic Risks — patterns that appear across multiple projects (the cross-project view that single-project reporting misses)
  • Recommended Portfolio Interventions — numbered list, prioritised by impact

Worked example prompt:

"Generate a portfolio summary for projects ALPHA-001, BETA-002, GAMMA-003 for the Q1 investment committee. Portfolio name: Digital Transformation Portfolio."

The tool gathers data independently for each project, compiles a consolidated view, and produces a single document covering all three. This replaces the manual process of summarising three separate programme reports into a coherent portfolio narrative.

5. generate_pir_template — pre-populated Post-Implementation Review

Generates a complete PIR template pre-populated with all available project data from the store. Uses Claude (max 4,000 tokens) to write narrative sections and [PLACEHOLDER] markers where human input is still required.

What it pre-populates:

Section Pre-populated with
Delivery Performance vs Business Case — Schedule Store data where available
Delivery Performance vs Business Case — Cost Financial baselines vs EAC
Benefits Delivery Benefits register with target values and status
Risks That Materialised Closed risks from the risk register
Lessons Learned Lessons stored by the pm-lessons module (if available)

What requires human completion:

Sections where store data is absent are marked [PLACEHOLDER]. The practitioner completes these before sign-off. The tool does not invent data — it flags gaps explicitly.

Sign-off block: The template includes a standard sign-off table with rows for SRO, Project Manager, and Benefits Owner.

When to use it: At programme closure, ideally after the pm-lessons module has been used throughout delivery to capture gate review and PIR lessons. The more data in the store, the more the template is pre-populated. A programme with full financial, risk, and benefits data will produce a template that is 60–70% complete on generation.

6. export_sro_dashboard_data — UDS browser dashboard

Exports all SRO dashboard metrics as a static JSON file for the Universal Dashboard Specification (UDS) Renderer, and returns a URL to open the dashboard in a browser.

What it exports (panel by panel):

Panel Data
dca_rating Latest DCA rating string
gate_status Current gate stage
open_changes Count of open change requests
schedule_p50 / schedule_p80 Monte Carlo P50 and P80 in days
financial_variance_pct EAC vs BAC as a percentage
top_risks_table Top 5 open risks with score, category, owner, status
benefits_table Top 5 benefits with target value, owner, status

How it works:

The tool writes a JSON file to a directory you specify (typically the uds-renderer/public/data/ directory) and returns a localhost URL:

http://localhost:5173/?dashboard=sro-dashboard.uds.yaml&project_id=PROJ-001&data_mode=static

Open this URL while the UDS Renderer is running to see the full interactive dashboard. The UDS layout (sro-dashboard.uds.yaml) is included with the platform — it defines the visual structure, panel types, and thresholds. You do not need to configure it.

Requirements: The UDS Renderer must be running on http://localhost:5173. See the UDS repository for setup instructions.

When to use it: When the SRO or programme director wants an interactive browser view rather than a markdown table. The dashboard renders DCA rating, schedule confidence intervals, a cost variance gauge, a risks table with conditional formatting, and a benefits status table — all in a single screen designed for the executive persona.

Common workflows

Workflow A: Gate review preparation

  1. Ensure delivery data is current in the store (risks updated, gate readiness assessed, financials logged).
  2. Call scan_for_red_flags (pm-assure) to identify any CRITICAL items to address before generation.
  3. Call generate_gate_review_summary with the appropriate gate_number and reviewer_name.
  4. Review the output — verify DCA rating is consistent with your assessment, conditions are specific and accurate.
  5. Export to Word or PDF for formatting and submission.

Workflow B: Monthly SRO reporting pack

  1. Call generate_sro_dashboard to produce the one-page markdown summary.
  2. If the SRO prefers a browser view, call export_sro_dashboard_data with the output directory.
  3. For any exceptions identified in the dashboard, call generate_board_exception_report to produce a board-ready escalation paper.

Workflow C: Investment committee portfolio update

  1. Compile the list of project IDs for the portfolio.
  2. Call generate_portfolio_summary with the full list and the committee name.
  3. The output is a single document covering all projects — portfolio scorecard, health narrative, systemic risks, and recommended interventions. Format for the agenda pack.

Workflow D: Programme closure — PIR

  1. Ensure all gate review lessons have been extracted using extract_lessons (pm-lessons module).
  2. Call generate_pir_template with the project ID and closure date.
  3. The template is pre-populated with delivery performance data, risks that materialised, benefits status, and lessons learned.
  4. Complete [PLACEHOLDER] sections with human input — sign-off names, dates, qualitative assessments where data is absent.
  5. Circulate for review by the project team before submission.

Limitations

  • Output quality depends on data in the store. A project with complete financial, risk, benefits, and gate readiness data will produce rich, evidence-grounded documents. A project with minimal store data will produce documents with more [PLACEHOLDER] markers and less specific commentary.
  • AI tools require ANTHROPIC_API_KEY. generate_gate_review_summary, generate_board_exception_report, generate_portfolio_summary, and generate_pir_template all call Claude. generate_sro_dashboard and export_sro_dashboard_data are deterministic and have no API dependency.
  • DCA ratings are AI-generated and require practitioner review. The DCA rating produced by generate_gate_review_summary is Claude's assessment of the data. It is a starting point for the reviewer's judgement, not a substitute for it. A qualified assurance practitioner must review and sign off on the rating before submission.
  • Board exception reports identify exceptions from store data only. If an exception exists that has not been captured in the store (e.g., an undisclosed risk, an oral commitment), the tool will not surface it.
  • PIR templates are pre-populated, not complete. The generate_pir_template tool produces a working document with [PLACEHOLDER] markers where data is absent. Human input is required before submission.
  • The UDS dashboard requires the UDS Renderer to be running locally. export_sro_dashboard_data writes static JSON — it does not host a server. The UDS Renderer must be separately installed and running.