How this works

Use this when leaders need to understand the kinds of work delivered across many repositories without reading every merged change. AI groups the records into themes such as reliability, customer-facing capabilities and internal maintenance, then links each theme back to evidence.

The map describes observed change records, not employee performance or hours spent. Pull requests differ dramatically in size and meaning; a large change count can reflect workflow conventions. Keep counts clearly labelled and avoid translating them into effort percentages unless independently measured effort data exists.

Before you start

Prepare the inputs

merged_changes

Required

PR export with stable IDs

Include title, description, merge time, repository and relevant issue references.

taxonomy

Optional / conditional

Versioned theme definitions

If absent, generate provisional themes for owner review rather than asserting strategic intent.

initiative_links

Optional / conditional

Issue or planning references

Treat links as evidence; do not infer business priority from an author’s identity.

Implementation, step by step

1. 01

   Build the scoped dataset

   • Retrieve merged records through authorized tools or use a local export. Record the query, window and any repositories without access.
   • Exclude unmerged drafts and reconcile duplicates, backports and automated updates according to the agreed rules. Preserve excluded counts and reasons.

   Checkpoint: The dataset has a clear denominator and reproducible inclusion criteria.

2. 02

   Extract change meaning

   • Summarize each record’s stated purpose using its description and linked issue where available. Avoid reading unrelated source code or private discussions beyond scope.
   • Separate explicit intent from an inferred theme. Mark titles such as fix or cleanup as insufficient evidence when no detail supports classification.

   Checkpoint: Each change has a short evidence-based description or an information gap.

3. 03

   Propose themes

   • Map clear records to the approved taxonomy. Where discovery is needed, cluster semantically similar descriptions and propose plain-language labels.
   • Allow multiple relevant tags while defining one primary theme only if required for totals. Keep ambiguous records unclassified instead of forcing a neat distribution.

   Checkpoint: Every proposed theme includes representative evidence and its classification rule.

4. 04

   Validate the interpretation

   • Ask engineering and product owners to review boundary cases and a sample of apparently clear assignments. Apply corrections consistently across similar records.
   • Check whether a theme represents delivered functionality, maintenance or a planning label. Do not report a whole initiative complete because one related change merged.

   Checkpoint: The theme map reflects reviewed classifications and visible uncertainty.

5. 05

   Produce the portfolio view

   • Export themes, counts of records, representative changes and unresolved gaps. Explain the denominator and whether multi-tag totals can overlap.
   • Compare periods only when inclusion rules are consistent. Return a reproducible table and a short narrative of observed delivery patterns without ranking individuals.

   Checkpoint: The review can trace each theme to actual records and understand the limits.

Decisions along the way

What you will produce

Check the result

• Reconcile included, excluded and unclassified records.
• Verify sample assignments against original descriptions.
• Check no count is labelled as hours, impact or individual productivity.

When something goes wrong

A worked example

SYNTHETIC EXAMPLE · NOT A REPORTED BUSINESS RESULT

Run a small pilot

Keep the scope clear

• Never use this output to rank employees or infer individual effort from code activity.
• Merged changes do not prove customer adoption, business impact or completed strategic outcomes.