Add retrospective enforcement gate to ADR-033

[rjmurillo-bot]

Summary

Add a routing-level enforcement gate (per ADR-033) that forces invocation of the retrospective agent at session end, milestones, and significant events.

Parent Story

#615 (Phase 2: SHOULD Skills)

Why Gate, Not Skill

Aspect	Skill Approach	Gate + Agent Approach
Problem addressed	Format inconsistency	Retrospective gets skipped entirely
Root cause	Format drift	Protocol bypass under pressure
Evidence	Some retros missing phases	PR #226: No retro despite major failure
ADR-033 alignment	Wrong layer (skill-internal)	Correct layer (routing-level)

The retrospective agent already works well when invoked. The failure mode is:

Retrospective doesn't happen at all - not that it happens poorly.

This is exactly the ADR-033 "Do Router" pattern:

"Over-routing is cheap. Under-routing compounds."

Gate Specification

Trigger Conditions

Trigger	Detection	Gate Action
Session end	git push after session work	Block until retrospective section exists
Milestone completion	PR merge to main	Block until retrospective for milestone
Significant event	Major failure detected	Force retrospective routing

Implementation

Add to Invoke-RoutingGates.ps1:

# Gate: Session End Retrospective
$SessionEndTriggers = @("git push")
$RequiresRetrospective = $SessionEndTriggers | Where-Object { $Command -like "*$_*" }

if ($RequiresRetrospective) {
    $SessionLog = Get-TodaySessionLog
    if ($SessionLog) {
        $Content = Get-Content $SessionLog.FullName -Raw
        
        # Check for retrospective section OR retrospective file reference
        $HasRetrospective = $Content -match "## Retrospective" -or 
                           $Content -match "\.agents/retrospective/"
        
        if (-not $HasRetrospective) {
            $Output = @{
                decision = "deny"
                reason = @"
RETROSPECTIVE GATE: Session retrospective required before push.

Run: Task(subagent_type='retrospective', prompt='Analyze this session for learnings')

Or document retrospective in session log with ## Retrospective section.
"@
            }
            $Output | ConvertTo-Json -Compress
            exit 0
        }
    }
}

Gate Bypass Conditions

Allow bypass when:

• Session is documentation-only (no code changes)
• Session is trivial (<10 minutes, single file change)
• Retrospective file already exists for today

# Check for existing retrospective file
$RetroDir = ".agents/retrospective"
$Today = Get-Date -Format "yyyy-MM-dd"
$ExistingRetro = Get-ChildItem -Path $RetroDir -Filter "$Today*.md" -ErrorAction SilentlyContinue

if ($ExistingRetro) {
    # Retrospective already done today, allow push
    exit 0
}

Integration with ADR-033

This gate fits into the ADR-033 gate architecture:

flowchart TB
    subgraph Gates["PreToolUse Hook Layer"]
        G1["Gate: Session Protocol"]
        G2["Gate: QA Validation"]
        G3["Gate: Critic Review"]
        G4["Gate: ADR Existence"]
        G5["Gate: Retrospective"]
    end
    
    G5 -->|"git push"| Check{Retrospective exists?}
    Check -->|Yes| Allow[Allow push]
    Check -->|No| Block["Block + suggest retrospective agent"]

Loading

Acceptance Criteria

• Gate added to Invoke-RoutingGates.ps1
• Triggers on git push commands
• Checks for retrospective section in session log OR retrospective file
• Provides clear guidance message when blocked
• Bypass logic for trivial sessions
• Integration tested with deliberate violation

Definition of Done

• Gate implemented in PowerShell (per ADR-005)
• Hook configuration updated in .claude/settings.local.json
• Gate documented in ADR-033 Implementation Notes
• Test: Attempt git push without retrospective → blocked
• Test: Attempt git push with retrospective → allowed

Relationship to Retrospective Agent

The retrospective AGENT remains unchanged:

• 6-phase workflow (Data Gathering → Insights → Diagnosis → Decide → Extract → Close)
• Five Whys, Fishbone, Force Field analysis
• Atomicity scoring, SMART validation
• Structured handoff output

This gate ENFORCES that the agent gets invoked, not changes what it does.

References

• ADR-033: Routing-Level Enforcement Gates
• Retrospective agent: src/claude/retrospective.md
• Real retrospectives: .agents/retrospective/
• PR feat(workflows): add static PR and issue labeling workflows #226 failure: Retrospective skipped despite major process failure

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

---

🔗 Similar Issues

Possible Duplicates

• [P1] Implement Technical Guardrails for Autonomous Agent Execution #230

Related Issues

• agent/implementer: Add pre-PR validation checklist to prevent premature PR opening #257
• agent/qa: Add mandatory pre-PR quality gate enforcement #258

🔗 Related PRs

#59 - feat: MCP config sync, session protocol enforcement, and platform prioritization [merged]
#246 - docs: Local Guardrails analysis consolidated into Issue #230 [merged]
#332 - docs: add feature request review workflow planning artifacts [merged]
#355 - feat(agents): install ai-agents multi-agent system [merged]
#467 - feat(agents): add BLOCKING gate for automatic ADR review [merged]

👤 Suggested Assignees

• rjmurillo-bot

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[github-actions]

AI Triage Summary

Note

This issue has been automatically triaged by AI agents

What is AI Triage?

This issue was analyzed by AI agents:

• Analyst Agent: Categorizes the issue and suggests appropriate labels
• Roadmap Agent: Aligns the issue with project milestones and priorities
• Explainer Agent (if escalated): Generates comprehensive PRD

Triage Results

Property	Value
Category	enhancement
Labels	["enhancement","agent-orchestrator","agent-retrospective","area-workflows"]
Priority	P1
Milestone	v1.1

Categorization Analysis

```json
{
  "labels": ["enhancement", "agent-orchestrator", "agent-retrospective", "area-workflows"],
  "category": "enhancement",
  "confidence": 0.95,
  "reasoning": "Issue requests a new routing-level enforcement gate for retrospective agent invocation, affecting orchestrator routing and workflow automation"
}

</details>

<details>
<summary>Roadmap Alignment</summary>

```json
Based on the roadmap context and issue analysis:

**Issue Analysis:**
- Parent: #615 (Phase 2: SHOULD Skills) 
- Scope: Add routing-level enforcement gate per ADR-033
- Purpose: Force retrospective agent invocation at session end
- Implementation: Modify `Invoke-RoutingGates.ps1` PowerShell script
- Clear specification with code samples, acceptance criteria, and DoD

**Framework Assessment:**
- **KANO**: Must-Be (retrospective protocol compliance is expected, not optional)
- **RICE**: Reach=3 users/quarter, Impact=2 (High), Confidence=80%, Effort=0.25 person-months = Score 19.2
- **Rumsfeld**: Known Knowns (clear implementation path, ADR-033 pattern established)
- **Eisenhower**: Important + Not Urgent (process improvement, not blocking current work)

**Alignment**: No exact epic match, but aligns with agent orchestration and workflow enforcement infrastructure.

```json
{
  "milestone": "v1.1",
  "priority": "P1",
  "epic_alignment": "",
  "confidence": 0.85,
  "reasoning": "Aligns with v1.1 maintainability goals; enforcement gate has clear implementation path per ADR-033 pattern",
  "escalate_to_prd": false,
  "escalation_criteria": [],
  "complexity_score": 0
}

</details>

---

<sub>Powered by [AI Issue Triage](https://github.com/rjmurillo/ai-agents) workflow</sub>