Implementation Postmortem Agent

This skill guides structured postmortem analysis of completed implementations. The goal is adversarial review: surface friction, identify architectural drift, challenge assumptions. Implementers can handle honest critique.

Workflow

Phase 1: Context Gathering

Before conducting a postmortem, gather sufficient context. Never assume—ask.

1.1 Obtain PR/Implementation Summary

If reviewing a PR, fetch the summary:

# Get PR details including description and changed files
gh pr view <PR_NUMBER> --json title,body,files,commits,additions,deletions

# Get the diff for detailed analysis
gh pr diff <PR_NUMBER>

# List files changed
gh pr view <PR_NUMBER> --json files --jq '.files[].path'

For non-PR work, request:

• •The implementation scope (what was built)
• •Entry points and key files
• •Any design documents or ADRs referenced

1.2 Establish Architecture Context

Ask these questions if the architecture is not already known:

Structural questions:

• •What architectural pattern does this codebase follow? (hexagonal/ports-adapters, MVC, layered, event-driven, actor-based, codec pipeline, etc.)
• •What are the primary module/crate boundaries?
• •What invariants must the architecture preserve?

Implementation questions:

• •What in-house libraries were used? What are they meant to do?
• •What tooling was used during development? (test frameworks, code analysis, documentation tools)
• •Were there design documents or specifications? Where do they live?

Scope questions:

• •What was the goal of this implementation phase?
• •What constraints or deadlines applied?
• •Were any shortcuts intentionally taken (and documented)?

Phase 2: Select Assessment Framework

Based on the architecture, load the appropriate reference template:

If the architecture doesn't match a template, use the Core Postmortem Dimensions (Section 3) and adapt terminology.

Phase 3: Conduct Assessment

Work through each dimension systematically. For each finding:

1. •Cite evidence — file:line references, specific code patterns, measurable data
2. •Classify severity — architectural violation (fix now) vs technical debt (track and schedule)
3. •Distinguish symptom from cause — "slow" is a symptom; "O(n²) loop in hot path" is a cause
4. •Note spec ambiguity — where design docs failed to answer a question the implementation faced

Core Postmortem Dimensions

These dimensions apply regardless of architecture. Architecture-specific templates extend them.

3.1 Specification Fidelity

• •Divergences between spec and implementation (intentional vs accidental)
• •Ambiguities in spec that caused implementation friction
• •Missing requirements discovered during implementation
• •Requirements that proved unnecessary or misguided

Key question: Where did the spec lie by omission?

3.2 Boundary Integrity

Every architecture defines boundaries. Assess:

• •Are boundaries enforced by the module/crate system?
• •What crosses boundaries that shouldn't?
• •Are boundary-crossing types appropriately abstract?

Smell test: If you had to replace one component (database, UI framework, protocol), what would break that shouldn't?

3.3 State Management

• •Where does authoritative state live?
• •Is there derived state that can drift from source?
• •Are state transitions explicit and auditable?

3.4 Error Handling

• •Error taxonomy: are different error categories (validation, I/O, business logic) distinguishable?
• •Recovery semantics: what errors are recoverable? How?
• •Observability: are errors logged with sufficient context?

3.5 Testability

• •Can components be tested in isolation?
• •Are there integration tests for boundary crossings?
• •What's untested that should be?

3.6 In-House Library Evaluation

For each in-house library used:

## [Library Name]

### Fit for Purpose
- How well did the library's model match implementation needs?
- Impedance mismatches requiring workarounds?

### What Worked
- Specific positive example with context

### What Hurt
- Specific friction point
- Impact: [time lost / workaround complexity / bug introduced]
- Suggested fix or documentation improvement

### Documentation Gaps
- What you searched for but didn't find
- What was present but wrong/stale

3.7 Tooling Effectiveness

For each tool used (test frameworks, analysis tools, documentation generators, MCP servers):

Questions per tool:

• •Did it surface useful insights or noise?
• •Integration friction with workflow?
• •False positives/negatives?
• •Where did it fail you?

Output Format

Structure the postmortem as:

1. •Executive Summary (5 bullets maximum, ranked by severity)
2. •Specification Gaps (ranked by impact)
3. •Architecture Assessment (using appropriate template)
4. •Boundary Violations (with file:line references where possible)
5. •Library Feedback (per-library structured assessment)
6. •Tooling Report Card (keep/improve/retire recommendations)
7. •Recommendations (concrete, actionable, with effort estimates: S/M/L)

Conduct Guidelines

• •Cite evidence. "The adapter felt bloated" → "OrderAdapter grew to 400 lines; 60% is validation logic that belongs in domain"
• •Distinguish symptoms from causes. "Tests are slow" is a symptom; "each test spins up a real database" is a cause.
• •Separate architectural violations from technical debt. Violations need immediate attention; debt can be scheduled.
• •Acknowledge what worked. If something worked well, say so briefly and move on—dwell on what needs attention.
• •Measure against the spec. The design documents are the contract. If no spec exists, note that as a finding.
• •Note spec ambiguity as feedback. Where the spec was unclear and implementation chose reasonably, feed that back to improve the spec.
• •Be direct. The implementer is reading this to improve. Hedging wastes their time.

Architecture-Specific Templates

For detailed assessment criteria, see:

• •references/hexagonal-template.md — Domain/ports/adapters pattern
• •references/mvc-action-template.md — MVC with action/command pipelines (e.g., GPUI-based apps)
• •references/codec-template.md — Protocol codec and framing pipelines

Load the appropriate template based on the architecture identified in Phase 1.