edumips64/edumips64/retro-enforcement

Skill: Retro Enforcement

Purpose

Ensure retrospectives happen on schedule and that their action items are tracked in GitHub Issues — not markdown checklists.

This skill addresses a specific, measured failure mode: 0% completion rate on markdown retro action items across 6 consecutive retrospectives. GitHub Issues have an 85%+ completion rate in the same squad. The format was the problem, not the people.

Core Function: Test-RetroOverdue

function Test-RetroOverdue {
    param(
        [string]$LogDir    = ".squad/log",
        [int]$WindowDays   = 7,
        [string]$Pattern   = "*retrospective*"
    )
 
    $cutoff = (Get-Date).AddDays(-$WindowDays)
 
    $retroLogs = Get-ChildItem -Path $LogDir -Filter $Pattern -ErrorAction SilentlyContinue |
                 Where-Object { $_.LastWriteTime -ge $cutoff }
 
    return ($retroLogs.Count -eq 0)
}

Returns

• $true — No retro log found within the window. Retro is overdue. Block other work.
• $false — At least one retro log found within the window. Proceed normally.

Detection Logic

The function checks .squad/log/ for any file matching *retrospective* dated within the last $WindowDays days (default: 7). If none is found, the retro is overdue.

File naming convention: .squad/log/{ISO8601-timestamp}-retrospective.md

Example: .squad/log/2026-03-24T14-45-00Z-retrospective.md

Coordinator Integration

Call Test-RetroOverdue at the start of every round, before building the work queue.

# At round start — before any work queue construction
if (Test-RetroOverdue -LogDir ".squad/log" -WindowDays 7) {
    Write-Host "[RETRO] Retrospective overdue. Running before other work."
 
    # Spawn retro facilitator
    Invoke-RetroSession -Mode "catch-up"
 
    # Wait for retro log to be written
    # Then resume normal round
}
 
# Proceed with normal work queue
$workQueue = Get-PendingIssues | Sort-Object -Property Priority

Blocking Semantics

When Test-RetroOverdue returns $true:

1. Do not start any other work until the retro completes
2. Spawn the facilitator agent (Scribe or designated) with retro mode
3. Wait for the log file to be written to .squad/log/
4. Verify action items were created as GitHub Issues (not markdown)
5. Resume normal round after retro log confirmed

Action Item Enforcement

Every retro action item MUST become a GitHub Issue. The facilitator agent is responsible for this. The coordinator verifies.

Verification Check

function Test-RetroActionItemsCreated {
    param([string]$RetroLogPath)
 
    $content = Get-Content $RetroLogPath -Raw
 
    # Check for Issue references (e.g., #1478, https://github.com/.../issues/1478)
    $issueRefs = [regex]::Matches($content, '(?:#\d{3,}|issues/\d{3,})')
 
    # Check for unclosed markdown checkboxes (bad pattern)
    $openCheckboxes = [regex]::Matches($content, '- \[ \]')
 
    if ($openCheckboxes.Count -gt 0) {
        Write-Warning "[RETRO] Found $($openCheckboxes.Count) markdown checkboxes — convert to Issues"
        return $false
    }
 
    return ($issueRefs.Count -gt 0)
}

Why Not Markdown Checklists

From production data in tamirdresher/tamresearch1:

Root cause: Markdown checklists have no assignee, no notifications, no close event, and no query surface. They are invisible to every workflow that drives completion.

Cadence Enforcement

Recommended schedule

• Weekly squads: window = 7 days
• Bi-weekly squads: window = 14 days

Ralph integration example

# ralph-watch.ps1 — round start hook
function Invoke-RoundStart {
    # 1. Always check retro first
    if (Test-RetroOverdue -LogDir "$RepoRoot/.squad/log" -WindowDays 7) {
        Write-Host "[RALPH] Retro overdue — enforcing before work queue"
        Invoke-RetroSession
        return  # Re-enter round after retro completes
    }
 
    # 2. Normal work queue
    $issues = Get-ReadyIssues
    foreach ($issue in $issues) {
        Invoke-WorkItem -Issue $issue
    }
}

Skill Metadata