post-mortem

Files (1)

• SKILL.md

SKILL.md (first lines)

# Post-Mortem — Session Analysis & Self-Improvement Skill

**Agent:** Librarian (orchestrator)
**Phase:** Closure (Phase 5 in BUILD, Phase 4 in DEBUG/REVIEW)
**Priority:** MANDATORY — Runs at the end of every completed workflow
**Consolidates:** self-improve, pattern-detector, intelligent-pattern-detector, pattern-implementer

---

## IRON LAW

**EVERY COMPLETED WORKFLOW GETS A POST-MORTEM. NO EXCEPTIONS.**

Even if the workflow was perfect. Especially if the workflow was perfect — document WHY it worked so we can replicate it.

---

## Purpose

Run the complete self-improvement cycle at workflow closure:
1. Collect session data
2. Detect meaningful patterns (not noise)
3. Classify: real issues vs. normal development patterns
4. Present findings to user
5. Implement approved improvements
6. Update memory

---

## Process Flow

```mermaid
graph TD
    A[Workflow Complete] --> B[Collect Session Data]
    B --> C[Analyze Patterns]
    C --> D{Meaningful Patterns?}
    D -->|No| E[Document: Clean Session]
    D -->|Yes| F[Classify Patterns]
    F --> G[Present to User]
    G --> H{User Approves?}
    H -->|Yes| I[Implement Changes]
    H -->|No| J[Document: User Declined]
    H -->|Partial| K[Implement Approved Only]
    I --> L[Update Memory]
    J --> L
    K --> L
    E --> L
    L --> M[Done]
```

---

## Step 1: Collect Session Data

Run the session copy script to extract messages:
```bash
python3 ~/.config/opencode/nso/scripts/copy_session.py
```

**Input:** `~/.local/share/opencode/storage/message/`
**Output:** `.opencode/logs/session.json`

The script:
- Reads OpenCode message storage
- Filters to current project (auto-detected from git/directory)
- Skips already-reviewed messages (tracked in `reviewed_sessions.json`)
- Outputs structured JSON

---

## Step 2: Pattern Detection

Analyze the session data for meaningful patterns. This combines rule-based detection with LLM understanding.

### Pattern Categories

#### Real Issues (Flag for Action)

| Pattern | Severity | Detection Rule | Suggested Action |
|---|---|---|---|
| `repeated_failure` | HIGH | Same file modified 5+ times with similar changes | Add to patterns.md, suggest refactoring |
| `context_loss` | HIGH | Agent starts work without reading requirements | Add gate to agent prompt |
| `validation_gap` | HIGH | Moved to closure without running tests | Flag for process improvement |
| `missing_approval` | HIGH | Oracle phases without user approval messages | Flag gate violation |
| `workflow_bypass` | MEDIUM | Jumped phases (e.g., no Architecture before Implementation) | Flag, may be intentional |
| `tool_errors` | MEDIUM | Consistent tool failures in session | Investigate tool configuration |
| `3_fix_escalation` | MEDIUM | 3+ fix attempts for same issue | Add to patterns.md as gotcha |

#### Normal Development (Don't Flag)

| Pattern | Why It's Normal | Note |
|---|---|---|
| `rapid_iteration` | Consecutive build calls during feature work | Healthy TDD cycle |
| `exploration` | Trying different approaches | Learning/discovery phase |
| `refactoring` | Multiple changes to same file, improving quality | Part of GREEN→REFACTOR |
| `model_switch` | Different models used | Document but don't flag |

#### System Health (Informational)

| Pattern | What It Shows | Action |
|---|---|---|
| `session_duration` | How long workflows take | Track in trends.json |
| `agent_effectiveness` | Which agents succeed/fail most | Track for tuning |
| `phase_duration` | Time per phase | Identify bottlenecks |

### Detection Implementation

The Librarian analyzes `session.json` using these rules:

```python
def detect_patterns(session_data):
    patterns = []
    
    # Rule 1: Repeated failures (same file, 5+ changes)
    file_changes = count_file_modifications(session_data)
    for file, count in file_changes.items():
        if count >= 5:
            patterns.append({
                "type": "repeated_failure",

From lshtram/nso, MIT.

More from lshtram/nso