Lessons Learned Capture & Register
TL;DR: Systematically captures, categorizes, and stores lessons learned from project experiences (successes and failures). Maintains a living lessons register that feeds into organizational knowledge management, ensuring future projects benefit from past experiences.
Principio Rector
Una lección no capturada está condenada a repetirse. Pero una lección capturada y no consultada es igualmente inútil. El registro de lecciones solo tiene valor si es consultado al inicio de cada proyecto. Las lecciones deben ser específicas, accionables, y buscables — no reflexiones genéricas.
Assumptions & Limits
- Assumes team psychological safety sufficient for honest lesson sharing — blame culture kills learning [STAKEHOLDER]
- Assumes retrospective or review data exists as primary input source [SUPUESTO]
- Breaks if lessons are generic platitudes ("communicate better") — must be specific and actionable [PLAN]
- Scope limited to project-level lessons; organizational transformation lessons require OCM framing [PLAN]
- Does not replace retrospective facilitation — consumes retrospective outputs as input [PLAN]
Usage
/pm:lessons-register $PROJECT_NAME --capture-from=retrospective
/pm:lessons-register $PROJECT_NAME --capture-from=gate-review --phase=3
/pm:lessons-register $PROJECT_NAME --search --domain=risk --priority=high
Parameters:
| Parameter | Required | Description |
|---|
$PROJECT_NAME | Yes | Target project identifier |
--capture-from | No | retrospective / gate-review / closure / manual |
--phase | No | Pipeline phase for context |
--search | No | Search existing lessons register |
--domain | No | Filter by domain (risk, planning, communication, etc.) |
Service Type Routing
{TIPO_PROYECTO}: Agile captures lessons in retrospectives; Waterfall captures at phase gates; SAFe captures in Inspect & Adapt; All types consolidate in project closure.
Before Capturing Lessons
- Read
retrospective-engine outputs — primary source for team-level lessons [PLAN]
- Glob
*gate-review* and *quality-audit* — secondary sources for process lessons [PLAN]
- Read existing lessons register — avoid duplicating already-captured lessons [PLAN]
- Confirm psychological safety — team must feel safe sharing negative lessons [STAKEHOLDER]
Entrada (Input Requirements)
- Retrospective outputs
- Phase gate review findings
- Team feedback and observations
- Quality audit results
- Post-implementation review data
Proceso (Protocol)
- Lesson identification — Collect lessons from all project touchpoints
- Categorization — Classify: What worked well, What didn't work, Suggestions for improvement
- Domain tagging — Tag by area (planning, execution, communication, risk, quality, team)
- Root cause — Document root cause for negative lessons
- Action recommendation — Define what future projects should do or avoid
- Priority rating — Rate lesson impact (High, Medium, Low)
- Applicability — Define which project types/contexts benefit from each lesson
- Register entry — Add to searchable lessons register with metadata
- Distribution — Share relevant lessons with organizational knowledge base
- Integration — Reference relevant lessons in future project planning
Edge Cases
- Same lesson appearing in multiple consecutive projects — Escalate as systemic organizational issue; lesson register alone cannot fix structural problems.
- Team resistant to sharing negative lessons — Use anonymous collection first; facilitate with specific prompts rather than open-ended "what went wrong."
- No organizational mechanism for lesson distribution — Create project-level register as minimum; propose PMO-level knowledge base as improvement initiative.
- Lessons too generic to be actionable — Apply "5 Whys" to reach specific, actionable root cause; reject entries that cannot answer "what should the next project do differently?"
Example: Good vs Bad
Good Lessons Register Entry:
| Attribute | Value |
|---|
| Lesson | "Vendor API integration took 3x estimated time due to undocumented rate limits" [METRIC] |
| Root cause | Vendor documentation incomplete; no PoC before full integration commitment [PLAN] |
| Domain | Technical, Procurement |
| Recommendation | "Run 1-week integration PoC with production-like data volume before committing to vendor" [PLAN] |
| Applicability | All projects with third-party API integration |
| Priority | High |
Bad Lessons Register Entry:
"Communication could have been better." — No specific situation, no root cause, no actionable recommendation, no applicability context. Future projects cannot derive any value from this entry.
Salida (Deliverables)
- Lessons learned register
- Categorized lessons summary
- Top 10 lessons for executive briefing
- Recommendations for process improvements
- Knowledge base update
Validation Gate
Escalation Triggers
- Same lesson appearing in multiple consecutive projects
- Lessons register not consulted at project startup
- Team resistant to sharing negative lessons
- No organizational mechanism for lesson distribution
Additional Resources
| Resource | When to read | Location |
|---|
| Body of Knowledge | Before starting to understand standards and frameworks | references/body-of-knowledge.md |
| State of the Art | When benchmarking against industry trends | references/state-of-the-art.md |
| Knowledge Graph | To understand skill dependencies and data flow | references/knowledge-graph.mmd |
| Use Case Prompts | For specific scenarios and prompt templates | prompts/use-case-prompts.md |
| Metaprompts | To enhance output quality and reduce bias | prompts/metaprompts.md |
| Sample Output | Reference for deliverable format and structure | examples/sample-output.md |
Output Configuration
- Language: Spanish (Latin American, business register)
- Evidence: [PLAN], [SCHEDULE], [METRIC], [INFERENCIA], [SUPUESTO], [STAKEHOLDER]
- Branding: #2563EB royal blue, #F59E0B amber (NEVER green), #0F172A dark
Sub-Agents
Lesson Harvester
Lesson Harvester Agent
Core Responsibility
The Lesson Harvester scours every available project artifact — retrospective notes, post-mortem reports, stakeholder interview transcripts, metric dashboards, and risk logs — to extract raw lessons learned. It operates continuously across all project phases (initiation through closure), ensuring no insight is lost due to recency bias or documentation gaps.
Process
- Inventory sources. Catalog all retrospective minutes, post-mortem documents, stakeholder feedback forms, escalation logs, and metric reports available for the target project or time window.
- Extract raw observations. Parse each source and pull verbatim quotes, data points, and flagged issues into a structured extraction template with source attribution.
- Classify by phase. Tag each observation with the project phase (initiation, planning, execution, monitoring, closure) where it originated to preserve temporal context.
- Categorize by domain. Assign each lesson a domain category: scope, schedule, cost, quality, risk, stakeholder, team, tooling, or governance.
- Assess sentiment and impact. Label each lesson as positive (repeat), negative (avoid), or neutral (context), and rate its impact on project outcomes (high / medium / low).
- Deduplicate and merge. Identify overlapping observations from different sources and consolidate them into single canonical lessons while preserving all source references.
- Produce harvest register. Compile the final structured register with ID, title, description, category, phase, sentiment, impact, sources, and date harvested.
Output Format
- Lesson Harvest Register — Structured table of all extracted lessons with ID, title, category, phase, sentiment, impact rating, and source references.
- Source Coverage Map — Matrix showing which artifact types and project phases were covered, highlighting any gaps in data collection.
Pattern Detector
Pattern Detector Agent
Core Responsibility
The Pattern Detector operates at the portfolio and organizational level, scanning across multiple projects and time periods to surface recurring themes that individual project teams cannot see. It identifies systemic issues, chronic process bottlenecks, cultural blind spots, and repeated success factors that transcend any single initiative, turning isolated lessons into organizational intelligence.
Process
- Aggregate cross-project data. Collect root cause analyses and lesson registers from multiple projects, normalizing categories and terminology for consistent comparison.
- Cluster by similarity. Group lessons that share common root causes, affected domains, or causal factors using thematic clustering to reveal natural groupings.
- Measure recurrence frequency. Count how often each cluster appears across projects, teams, and time periods to distinguish one-off incidents from systemic patterns.
- Map to organizational dimensions. Plot recurring patterns against organizational axes — departments, methodologies, team sizes, client types, technology stacks — to identify where patterns concentrate.
- Detect blind spots. Identify areas where lessons are conspicuously absent despite known risk — these silences often indicate unrecognized systemic issues or cultural taboos.
- Assess pattern severity. Score each pattern by frequency, cumulative impact, trend direction (worsening / stable / improving), and organizational reach.
- Produce pattern intelligence brief. Synthesize findings into a strategic brief that frames patterns as organizational risks or opportunities rather than project-level incidents.
Output Format
- Pattern Intelligence Brief — Strategic summary of top recurring patterns with frequency, severity score, affected organizational dimensions, and trend direction.
- Systemic Issue Heatmap — Visual matrix mapping pattern clusters against organizational dimensions (team, methodology, domain, time) to show concentration zones.
Recommendation Packager
Recommendation Packager Agent
Core Responsibility
The Recommendation Packager is the final-mile agent that converts analyzed lessons, root causes, and detected patterns into concrete, implementable recommendations. Each recommendation is packaged with a clear owner, priority level, target audience, estimated effort, and step-by-step implementation guidance — ensuring lessons actually change behavior rather than gathering dust in a repository.
Process
- Synthesize inputs. Consolidate outputs from the Lesson Harvester, Root Cause Analyst, and Pattern Detector into a unified view of validated lessons, causes, and systemic patterns.
- Formulate recommendations. For each root cause or pattern, draft a specific, measurable, and actionable recommendation that addresses the underlying issue — not just the symptom.
- Assign ownership and audience. Identify the accountable owner (role or team) and the target audience who must adopt the recommendation for it to take effect.
- Set priority and effort. Rate each recommendation by urgency (critical / high / medium / low) and estimated implementation effort (S / M / L / XL) to support planning.
- Write implementation guidance. Provide 3-5 concrete steps for each recommendation, including triggers (when to apply), success criteria, and known constraints.
- Link to source lessons. Trace each recommendation back to the specific lessons, root causes, and patterns that justify it, maintaining full auditability.
- Package for distribution. Format the final recommendation set for multiple audiences: executive summary for leadership, detailed playbook for PMO, and quick-reference cards for project teams.
Output Format
- Recommendation Register — Structured table with ID, title, description, owner, priority, effort, target audience, implementation steps, success criteria, and source lesson references.
- Executive Action Brief — One-page summary of top 5-10 recommendations with expected impact, suitable for steering committee or leadership review.
Root Cause Analyst
Root Cause Analyst Agent
Core Responsibility
The Root Cause Analyst takes harvested lessons and drills beneath surface-level observations to uncover the true drivers of both failures and successes. By applying structured techniques — 5 Whys, Ishikawa fishbone diagrams, and contributing factor analysis — it transforms anecdotal observations into deep, evidence-backed insights that prevent recurrence of problems and enable replication of wins.
Process
- Prioritize lessons for analysis. Select high-impact and recurring lessons from the harvest register that warrant deeper investigation beyond their surface description.
- Apply 5 Whys drill-down. For each selected lesson, iteratively ask "why" at least five times to trace the causal chain from observable symptom to fundamental root cause.
- Construct fishbone diagrams. Map contributing factors across standard categories (people, process, technology, environment, management, materials) to reveal multi-dimensional causality.
- Identify contributing factors. Distinguish between root causes (must fix), contributing factors (should fix), and correlations (monitor) to avoid misattribution.
- Validate with evidence. Cross-reference each proposed root cause against project data, timelines, and stakeholder accounts to confirm or reject the causal hypothesis.
- Analyze successes equally. Apply the same rigor to positive outcomes — identify what specific conditions, decisions, and behaviors produced the success so they can be intentionally replicated.
- Document causal chains. Produce a structured root cause report linking each lesson to its validated causal chain, evidence, and confidence level.
Output Format
- Root Cause Analysis Report — For each analyzed lesson: symptom, 5 Whys chain, fishbone factors, validated root cause, confidence level, and supporting evidence.
- Causal Pattern Summary — Aggregated view of the most frequent root cause categories across all analyzed lessons, highlighting systemic vs. situational causes.