feat: Error Classification & Recovery + OODA-Optimized Memory Prefetch Skills

[rjmurillo-bot]

Overview

Two skill proposals to improve agent resilience and responsiveness, designed to work with both Copilot CLI and Claude Code.

---

Skill 1: Error Classification & Recovery

Problem

Agents fail in predictable ways but lack systematic recovery strategies. Failures cascade instead of self-correcting.

Research Basis

• 39% loop recovery rate with classification + hint injection
• 85% precision in failure type detection
• Antifragility: systems that get stronger from failures

Error Taxonomy

Type	Detection Signal	Recovery Strategy
Tool Failure	Non-zero exit, API error	Retry with backoff, fallback tool
Reasoning Drift	Output diverges from intent	Re-anchor with original prompt
Infinite Loop	Repeated tool calls (3+)	Break loop, summarize progress, escalate
Scope Creep	Task expands beyond original	Checkpoint, confirm with user
Context Overflow	Token limit warnings	Compress context, archive old turns

Implementation

1. Error Observer Hook

Wrap tool execution to classify failures:

# .agents/hooks/error_observer.py
def classify_error(tool_name: str, exit_code: int, stderr: str) -> ErrorType:
    if "rate limit" in stderr.lower():
        return ErrorType.TRANSIENT
    if exit_code == 2:  # Config error (ADR-035)
        return ErrorType.CONFIG
    if is_repeated_call(tool_name, count=3):
        return ErrorType.LOOP
    return ErrorType.LOGIC

2. Recovery Hint Injection

Store failure→recovery mappings:

# .agents/recovery-hints.yaml
tool_failures:
  gh:
    - pattern: "GraphQL: Could not resolve"
      hint: "Issue/PR number may not exist. Verify with `gh issue list`."
    - pattern: "HTTP 403"
      hint: "Rate limited. Wait 60s or use `gh api --cache`."
      
reasoning_drift:
  - signal: "Let me also add..."
    hint: "STOP. Check if this is in scope. Original task was: {original_task}"

3. Integration Points

Copilot CLI:

• Hook into copilot-cli wrapper script
• Log errors to .agents/sessions/errors.jsonl
• Inject hints via system prompt modification

Claude Code:

• Use CLAUDE.md pre-tool hook pattern
• Error classification runs post-tool-execution
• Recovery hints added to next turn context

4. Pattern Learning

After recovery, log what worked:

{"timestamp": "2026-02-26T22:00:00Z", "error_type": "LOOP", "tool": "gh", "recovery": "break_and_summarize", "success": true}

Graduate patterns with 3+ successful recoveries to MEMORY.md.

---

Skill 2: OODA-Optimized Memory Prefetch

Problem

Agents waste the "Orient" phase of OODA gathering context that's predictable. Research shows 88-99% cycle time reduction is possible.

Research Basis

• OODA loop optimization: fastest cycle wins
• Edge deployment principle: precompute, don't fetch on demand
• Predictable context: git status, open PRs, recent sessions are almost always needed

Prefetch Targets

Context	Trigger	Cache Duration
Git status + branch	Session start	5 min
Open PRs (assigned)	Session start	15 min
Recent commits (5)	Session start	15 min
CI status (last run)	Session start	10 min
Open issues (assigned)	Session start	30 min
Last session summary	Session start	Until next session
HEARTBEAT.md tasks	Heartbeat poll	1 min

Implementation

1. Prefetch Script

# .agents/hooks/session_prefetch.py
import subprocess
import json
from pathlib import Path

CACHE_DIR = Path(".agents/cache")

def prefetch_context():
    """Run at session start, cache results."""
    context = {
        "git_branch": run("git branch --show-current"),
        "git_status": run("git status --short"),
        "open_prs": run("gh pr list --author @me --json number,title,url --limit 5"),
        "recent_commits": run("git log --oneline -5"),
        "ci_status": run("gh run list --limit 1 --json status,conclusion,name"),
    }
    
    cache_path = CACHE_DIR / "session_context.json"
    cache_path.write_text(json.dumps(context, indent=2))
    return context

2. Context Injection

Copilot CLI:

• Prefetch runs in .copilot/hooks/pre-session.sh
• Results injected via environment variable or temp file
• CLI reads cache before first prompt

Claude Code:

• Prefetch runs in CLAUDE.md session init block
• Results added to passive context (high in prompt)
• Cache invalidation on git operations

3. Smart Invalidation

# Invalidate on relevant operations
INVALIDATION_TRIGGERS = {
    "git_*": ["git commit", "git push", "git pull", "git checkout"],
    "open_prs": ["gh pr create", "gh pr merge", "gh pr close"],
    "ci_status": ["gh workflow run", "git push"],
}

4. Latency Targets

Metric	Before	After	Target
Time to first tool call	3-5s	<1s	80% reduction
Context gathering turns	2-3	0	Eliminate
Redundant API calls	5+/session	1 (prefetch)	80% reduction

---

Shared Infrastructure

Both skills share:

1. .agents/cache/ - Ephemeral context cache
2. .agents/hooks/ - Pre/post execution hooks
3. .agents/sessions/errors.jsonl - Error pattern log
4. MEMORY.md graduation - Patterns with 3+ occurrences

---

Success Criteria

Error Classification & Recovery

• Error taxonomy implemented with 5 types
• Recovery hints for top 10 failure patterns
• Loop detection breaks 80% of infinite loops
• Pattern graduation to MEMORY.md working

OODA-Optimized Prefetch

• Session start prefetches 5 context types
• Cache invalidation on relevant git/gh ops
• Measured 50%+ reduction in "Orient" phase time
• Works in both Copilot CLI and Claude Code

---

Open Questions

1. Should error classification run synchronously (blocking) or async (background)?
2. How to handle prefetch in offline/air-gapped environments?
3. Should recovery hints be agent-specific or shared across all agents?

---

References

• MEMORY.md: OODA Loop Optimization (2026-02-23)
• MEMORY.md: Multi-Agent Self-Correction (2026-02-25)
• MEMORY.md: Behavioral Drift Detection (2026-02-25)
• ADR-035: Exit codes (0=success, 1=logic, 2=config, 3=external, 4=auth)

[traycerai]

Plan

Implementation Plan: Error Classification & Recovery + OODA-Optimized Memory Prefetch Skills

Observations

The repository has a mature Claude Code hook infrastructure in .claude/hooks/ organized by hook type subdirectories (PreToolUse, PostToolUse, SessionStart, etc.), registered in .claude/settings.json. Hook utilities are available at .claude/lib/hook_utilities/ with guards.py and utilities.py providing common patterns. Skills live in .claude/skills/{name}/ with scripts in scripts/ subdirectories. The .agents/cache/ directory does not yet exist. Python 3.10+ is required; PyYAML is already in pyproject.toml. The memory system uses .serena/memories/ (not yet created in this repo). ADR-035 defines exit codes (0=success, 1=logic, 2=config, 3=external, 4=auth).

Approach

Implement both skills as first-class Claude Code hook + skill pairs, following the exact patterns of existing hooks (e.g., invoke_routing_gates.py, invoke_session_start_memory_first.py). Shared cache infrastructure is created first. Error classification runs as a PostToolUse/Bash hook; prefetch runs as a SessionStart hook. Both fail gracefully (never block the agent). Pattern graduation writes directly to .serena/memories/ using standard memory file format. All Python scripts follow ADR-042 (Python 3.12 target, ruff/mypy compliance).

---

Implementation Steps

Step 1 — Shared Cache Infrastructure

Create .agents/cache/ directory structure:

• .agents/cache/.gitkeep — keeps the directory tracked in git
• .agents/cache/.gitignore — excludes runtime files (*.json, *.jsonl) so cache files are never committed

Create .agents/sessions/ directory if not present (for errors.jsonl log file).

---

Step 2 — Error Classification & Recovery: Recovery Hints Config

Create .agents/recovery-hints.yaml with the full error taxonomy. Structure as a YAML mapping of error_type → list of {pattern, hint} entries, plus a top-level loop_threshold: 3 key. Include entries for:

Section	Key patterns
tool_failures.gh	"GraphQL: Could not resolve", "HTTP 403", "HTTP 422", "rate limit"
tool_failures.git	"not a git repository", "nothing to commit", "rejected"
tool_failures.python	"ModuleNotFoundError", "SyntaxError"
reasoning_drift	"Let me also add", "While I'm at it", "I'll also fix"
context_overflow	"token limit", "context length"
scope_creep	"expand", "also update", "while we're here"

Each hint entry references the original task anchor: "STOP. Check scope. Original task: {original_task}".

---

Step 3 — Error Classification & Recovery: Skill Module

Create .claude/skills/error-recovery/scripts/classify_error.py as an importable Python module (not a standalone script). Define:

• ErrorType — an enum.Enum with values: TRANSIENT, CONFIG, LOOP, LOGIC, SCOPE_CREEP, CONTEXT_OVERFLOW
• classify_error(tool_name, exit_code, stderr, command, cache_dir) — returns ErrorType. Uses ADR-035 exit codes (2=config, 3=external/transient, 4=auth) as primary signals; falls back to stderr pattern matching against recovery-hints.yaml
• is_repeated_call(tool_name, command_hash, cache_dir, threshold=3) — reads .agents/cache/tool-call-history.json, counts occurrences of (tool_name, command_hash) within the current session window; returns True if count ≥ threshold
• record_tool_call(tool_name, command_hash, cache_dir) — appends to .agents/cache/tool-call-history.json with ISO timestamp; prunes entries older than 1 hour
• find_recovery_hint(error_type, tool_name, stderr, hints_path) — loads recovery-hints.yaml (using PyYAML), matches patterns against stderr, returns the first matching hint string or None
• log_error_event(error_type, tool_name, recovery_hint, success, log_path) — appends a JSONL record to .agents/sessions/errors.jsonl

All file I/O uses try/except OSError with graceful fallback (never raises).

---

Step 4 — Error Classification & Recovery: Pattern Graduation Script

Create .claude/skills/error-recovery/scripts/graduate_patterns.py as a standalone Python script. It:

1. Reads .agents/sessions/errors.jsonl
2. Groups records by (error_type, tool_name, recovery_hint)
3. Finds groups with success=true count ≥ 3
4. For each qualifying group, writes a new Serena memory file to .serena/memories/error-recovery-{error_type}-{tool_name}.md using the standard memory format (Statement, Context, Evidence, Details sections)
5. Appends a row to .serena/memories/skills-error-recovery-index.md (creating the index file if absent, following the | Keywords | File | table format)
6. Exits with code 0 on success, 1 on logic error (ADR-035)

This script is invoked manually or by the retrospective agent — not as a hook.

---

Step 5 — Error Classification & Recovery: Skill Documentation

Create .claude/skills/error-recovery/SKILL.md with YAML front matter:

---
name: error-recovery
description: Classifies tool failures and injects recovery hints. Detects loops, reasoning drift, scope creep, and context overflow. Graduates successful recovery patterns to Serena memory.
tools:
  - Read
  - Bash
---

Document the error taxonomy table, the five recovery strategies, the loop detection mechanism, the JSONL log format, and how to invoke graduate_patterns.py.

---

Step 6 — Error Classification & Recovery: PostToolUse Hook

Create .claude/hooks/PostToolUse/invoke_error_observer.py:

• Hook type: PostToolUse, matcher: Bash
• Reads JSON from stdin: tool_name, tool_input.command, tool_response.output, tool_response.exit_code
• Calls skip_if_consumer_repo("error-observer") from hook_utilities.guards
• Resolves cache_dir and hints_path relative to project root via get_project_directory()
• Calls record_tool_call() on every Bash invocation (for loop tracking)
• If exit_code != 0 or stderr contains known patterns: calls classify_error(), then find_recovery_hint()
• If a hint is found: prints a formatted recovery block to stdout (Claude receives it as context)
• Calls log_error_event() with success=False (success is updated by a follow-up call when the agent recovers — or left as False for graduation threshold purposes)
• Always exits with code 0 (PostToolUse hooks must not block)

---

Step 7 — OODA Prefetch: Core Script

Create .claude/skills/session-prefetch/scripts/session_prefetch.py as both an importable module and a runnable script (if __name__ == "__main__"). Define:

• PREFETCH_TARGETS — a dict mapping context key → {command, ttl_seconds}:

Key	Command	TTL
git_branch	git branch --show-current	300
git_status	git status --short	300
open_prs	gh pr list --author @me --json number,title,url --limit 5	900
recent_commits	git log --oneline -5	900
ci_status	gh run list --limit 1 --json status,conclusion,name	600
open_issues	gh issue list --assignee @me --json number,title --limit 5	1800

• run_command(cmd, timeout=10) — runs via subprocess.run, returns (stdout, success) tuple; never raises; returns ("", False) on any error (offline/air-gapped safety)
• is_cache_valid(cache_path, ttl_seconds) — checks mtime of the cache file against ttl_seconds; returns False if file absent
• load_cache(cache_path) — reads and parses JSON; returns {} on any error
• save_cache(cache_path, data) — writes JSON atomically (write to .tmp then rename); creates parent dirs
• prefetch_context(cache_dir, force_refresh=False) — iterates PREFETCH_TARGETS, skips entries whose cache is still valid (unless force_refresh), runs commands for stale entries, merges with cached data, saves updated cache, returns the full context dict
• format_context_output(context) — returns a markdown-formatted string suitable for Claude's context window (prefixed with ## Session Context (Prefetched))
• invalidate_on_trigger(cache_dir, command) — checks command against INVALIDATION_TRIGGERS dict and deletes matching cache keys from the JSON file

INVALIDATION_TRIGGERS:

git_branch/git_status → git commit, git push, git pull, git checkout, git switch
open_prs             → gh pr create, gh pr merge, gh pr close
ci_status            → gh workflow run, git push
open_issues          → gh issue create, gh issue close

---

Step 8 — OODA Prefetch: Skill Documentation

Create .claude/skills/session-prefetch/SKILL.md with YAML front matter:

---
name: session-prefetch
description: OODA-optimized context prefetch. Runs at session start to cache git status, open PRs, recent commits, CI status, and open issues. Eliminates Orient-phase latency. Cache TTL-based with trigger invalidation.
tools:
  - Bash
  - Read
---

Document the prefetch targets table, TTL values, invalidation triggers, offline behavior, and how to force-refresh with python3 .claude/skills/session-prefetch/scripts/session_prefetch.py --force.

---

Step 9 — OODA Prefetch: SessionStart Hook

Create .claude/hooks/SessionStart/invoke_session_prefetch.py:

• Hook type: SessionStart
• Calls skip_if_consumer_repo("session-prefetch")
• Resolves cache_dir = project_root / ".agents" / "cache"
• Calls prefetch_context(cache_dir) from the skill module
• Calls format_context_output(context) and prints to stdout
• Wraps everything in try/except Exception — any failure prints a one-line warning to stderr and exits 0 (session start must never be blocked)
• Exits 0 always

---

Step 10 — Register Hooks in .claude/settings.json

Add two entries to the existing settings.json:

SessionStart — append after the existing invoke_adr_change_detection.py entry:

{
  "type": "command",
  "command": "python3 -u .claude/hooks/SessionStart/invoke_session_prefetch.py",
  "statusMessage": "Prefetching session context (OODA Orient phase)"
}

PostToolUse / Bash — append to the existing Bash matcher block:

{
  "type": "command",
  "command": "python3 -u .claude/hooks/PostToolUse/invoke_error_observer.py",
  "statusMessage": "Classifying tool errors and injecting recovery hints"
}

Also add a cache invalidation call inside the same Bash PostToolUse block by having invoke_error_observer.py call invalidate_on_trigger() from the prefetch module — this avoids a separate hook entry.

---

Step 11 — Update .agents/AGENTS.md Skill Catalog

In .agents/AGENTS.md, update the Skill-First Checkpoint table (or create if absent) to add:

Operation	Skill
Classify tool errors	error-recovery
Prefetch session context	session-prefetch

---

Step 12 — Create Serena Memory Index Files

Create .serena/memories/skills-error-recovery-index.md with the standard two-column table format:

| Keywords | File |
|----------|------|
| error recovery loop classification hint retry | error-recovery-skill |

Create .serena/memories/skills-session-prefetch-index.md:

| Keywords | File |
|----------|------|
| prefetch session context ooda orient cache git pr ci | session-prefetch-skill |

Add rows for both new index files to .serena/memories/memory-index.md under the appropriate task keyword columns (create .serena/memories/memory-index.md if absent).

---

Step 13 — Create .agents/sessions/errors.jsonl Placeholder

Create .agents/sessions/errors.jsonl as an empty file (or with a comment header line) so the directory structure is committed and the log file path is predictable. Add it to .gitignore if runtime error logs should not be committed, or keep it tracked if the graduation mechanism depends on committed history.

---

Success Criteria

Error Classification & Recovery

• Error taxonomy implemented with 5 types
• Recovery hints for top 10 failure patterns
• Loop detection breaks 80% of infinite loops
• Pattern graduation to Serena memory working

OODA-Optimized Prefetch

• Session start prefetches 5 context types
• Cache invalidation on relevant git/gh ops
• Measured 50%+ reduction in "Orient" phase time
• Works in both Copilot CLI and Claude Code

---

Testing Strategy

1. Unit tests for classify_error.py and session_prefetch.py in tests/ directory
2. Integration tests for hook registration and cache file I/O
3. Manual testing of prefetch output and error hint injection
4. Graduation script validation with mock error logs

Import In IDE

🤖 Prompt for AI Agents

# Implementation Plan: Error Classification & Recovery + OODA-Optimized Memory Prefetch Skills

## Observations

The repository has a mature Claude Code hook infrastructure in `.claude/hooks/` organized by hook type subdirectories (PreToolUse, PostToolUse, SessionStart, etc.), registered in `.claude/settings.json`. Hook utilities are available at `.claude/lib/hook_utilities/` with `guards.py` and `utilities.py` providing common patterns. Skills live in `.claude/skills/{name}/` with scripts in `scripts/` subdirectories. The `.agents/cache/` directory does not yet exist. Python 3.10+ is required; PyYAML is already in `pyproject.toml`. The memory system uses `.serena/memories/` (not yet created in this repo). ADR-035 defines exit codes (0=success, 1=logic, 2=config, 3=external, 4=auth).

## Approach

Implement both skills as first-class Claude Code hook + skill pairs, following the exact patterns of existing hooks (e.g., `invoke_routing_gates.py`, `invoke_session_start_memory_first.py`). Shared cache infrastructure is created first. Error classification runs as a `PostToolUse/Bash` hook; prefetch runs as a `SessionStart` hook. Both fail gracefully (never block the agent). Pattern graduation writes directly to `.serena/memories/` using standard memory file format. All Python scripts follow ADR-042 (Python 3.12 target, ruff/mypy compliance).

---

## Implementation Steps

### Step 1 — Shared Cache Infrastructure

Create `.agents/cache/` directory structure:
- `.agents/cache/.gitkeep` — keeps the directory tracked in git
- `.agents/cache/.gitignore` — excludes runtime files (`*.json`, `*.jsonl`) so cache files are never committed

Create `.agents/sessions/` directory if not present (for `errors.jsonl` log file).

---

### Step 2 — Error Classification & Recovery: Recovery Hints Config

Create `.agents/recovery-hints.yaml` with the full error taxonomy. Structure as a YAML mapping of `error_type → list of {pattern, hint}` entries, plus a top-level `loop_threshold: 3` key. Include entries for:

| Section | Key patterns |
|---|---|
| `tool_failures.gh` | `"GraphQL: Could not resolve"`, `"HTTP 403"`, `"HTTP 422"`, `"rate limit"` |
| `tool_failures.git` | `"not a git repository"`, `"nothing to commit"`, `"rejected"` |
| `tool_failures.python` | `"ModuleNotFoundError"`, `"SyntaxError"` |
| `reasoning_drift` | `"Let me also add"`, `"While I'm at it"`, `"I'll also fix"` |
| `context_overflow` | `"token limit"`, `"context length"` |
| `scope_creep` | `"expand"`, `"also update"`, `"while we're here"` |

Each hint entry references the original task anchor: `"STOP. Check scope. Original task: {original_task}"`.

---

### Step 3 — Error Classification & Recovery: Skill Module

Create `.claude/skills/error-recovery/scripts/classify_error.py` as an importable Python module (not a standalone script). Define:

- `ErrorType` — an `enum.Enum` with values: `TRANSIENT`, `CONFIG`, `LOOP`, `LOGIC`, `SCOPE_CREEP`, `CONTEXT_OVERFLOW`
- `classify_error(tool_name, exit_code, stderr, command, cache_dir)` — returns `ErrorType`. Uses ADR-035 exit codes (2=config, 3=external/transient, 4=auth) as primary signals; falls back to stderr pattern matching against `recovery-hints.yaml`
- `is_repeated_call(tool_name, command_hash, cache_dir, threshold=3)` — reads `.agents/cache/tool-call-history.json`, counts occurrences of `(tool_name, command_hash)` within the current session window; returns `True` if count ≥ threshold
- `record_tool_call(tool_name, command_hash, cache_dir)` — appends to `.agents/cache/tool-call-history.json` with ISO timestamp; prunes entries older than 1 hour
- `find_recovery_hint(error_type, tool_name, stderr, hints_path)` — loads `recovery-hints.yaml` (using `PyYAML`), matches patterns against stderr, returns the first matching hint string or `None`
- `log_error_event(error_type, tool_name, recovery_hint, success, log_path)` — appends a JSONL record to `.agents/sessions/errors.jsonl`

All file I/O uses `try/except OSError` with graceful fallback (never raises).

---

### Step 4 — Error Classification & Recovery: Pattern Graduation Script

Create `.claude/skills/error-recovery/scripts/graduate_patterns.py` as a standalone Python script. It:

1. Reads `.agents/sessions/errors.jsonl`
2. Groups records by `(error_type, tool_name, recovery_hint)`
3. Finds groups with `success=true` count ≥ 3
4. For each qualifying group, writes a new Serena memory file to `.serena/memories/error-recovery-{error_type}-{tool_name}.md` using the standard memory format (Statement, Context, Evidence, Details sections)
5. Appends a row to `.serena/memories/skills-error-recovery-index.md` (creating the index file if absent, following the `| Keywords | File |` table format)
6. Exits with code 0 on success, 1 on logic error (ADR-035)

This script is invoked manually or by the `retrospective` agent — not as a hook.

---

### Step 5 — Error Classification & Recovery: Skill Documentation

Create `.claude/skills/error-recovery/SKILL.md` with YAML front matter:

```yaml
---
name: error-recovery
description: Classifies tool failures and injects recovery hints. Detects loops, reasoning drift, scope creep, and context overflow. Graduates successful recovery patterns to Serena memory.
tools:
  - Read
  - Bash
---
```

Document the error taxonomy table, the five recovery strategies, the loop detection mechanism, the JSONL log format, and how to invoke `graduate_patterns.py`.

---

### Step 6 — Error Classification & Recovery: PostToolUse Hook

Create `.claude/hooks/PostToolUse/invoke_error_observer.py`:

- **Hook type**: `PostToolUse`, matcher: `Bash`
- Reads JSON from stdin: `tool_name`, `tool_input.command`, `tool_response.output`, `tool_response.exit_code`
- Calls `skip_if_consumer_repo("error-observer")` from `hook_utilities.guards`
- Resolves `cache_dir` and `hints_path` relative to project root via `get_project_directory()`
- Calls `record_tool_call()` on every Bash invocation (for loop tracking)
- If `exit_code != 0` or stderr contains known patterns: calls `classify_error()`, then `find_recovery_hint()`
- If a hint is found: prints a formatted recovery block to stdout (Claude receives it as context)
- Calls `log_error_event()` with `success=False` (success is updated by a follow-up call when the agent recovers — or left as False for graduation threshold purposes)
- Always exits with code 0 (PostToolUse hooks must not block)

---

### Step 7 — OODA Prefetch: Core Script

Create `.claude/skills/session-prefetch/scripts/session_prefetch.py` as both an importable module and a runnable script (`if __name__ == "__main__"`). Define:

- `PREFETCH_TARGETS` — a dict mapping context key → `{command, ttl_seconds}`:

| Key | Command | TTL |
|---|---|---|
| `git_branch` | `git branch --show-current` | 300 |
| `git_status` | `git status --short` | 300 |
| `open_prs` | `gh pr list --author @me --json number,title,url --limit 5` | 900 |
| `recent_commits` | `git log --oneline -5` | 900 |
| `ci_status` | `gh run list --limit 1 --json status,conclusion,name` | 600 |
| `open_issues` | `gh issue list --assignee @me --json number,title --limit 5` | 1800 |

- `run_command(cmd, timeout=10)` — runs via `subprocess.run`, returns `(stdout, success)` tuple; never raises; returns `("", False)` on any error (offline/air-gapped safety)
- `is_cache_valid(cache_path, ttl_seconds)` — checks `mtime` of the cache file against `ttl_seconds`; returns `False` if file absent
- `load_cache(cache_path)` — reads and parses JSON; returns `{}` on any error
- `save_cache(cache_path, data)` — writes JSON atomically (write to `.tmp` then rename); creates parent dirs
- `prefetch_context(cache_dir, force_refresh=False)` — iterates `PREFETCH_TARGETS`, skips entries whose cache is still valid (unless `force_refresh`), runs commands for stale entries, merges with cached data, saves updated cache, returns the full context dict
- `format_context_output(context)` — returns a markdown-formatted string suitable for Claude's context window (prefixed with `## Session Context (Prefetched)`)
- `invalidate_on_trigger(cache_dir, command)` — checks `command` against `INVALIDATION_TRIGGERS` dict and deletes matching cache keys from the JSON file

`INVALIDATION_TRIGGERS`:
```
git_branch/git_status → git commit, git push, git pull, git checkout, git switch
open_prs             → gh pr create, gh pr merge, gh pr close
ci_status            → gh workflow run, git push
open_issues          → gh issue create, gh issue close
```

---

### Step 8 — OODA Prefetch: Skill Documentation

Create `.claude/skills/session-prefetch/SKILL.md` with YAML front matter:

```yaml
---
name: session-prefetch
description: OODA-optimized context prefetch. Runs at session start to cache git status, open PRs, recent commits, CI status, and open issues. Eliminates Orient-phase latency. Cache TTL-based with trigger invalidation.
tools:
  - Bash
  - Read
---
```

Document the prefetch targets table, TTL values, invalidation triggers, offline behavior, and how to force-refresh with `python3 .claude/skills/session-prefetch/scripts/session_prefetch.py --force`.

---

### Step 9 — OODA Prefetch: SessionStart Hook

Create `.claude/hooks/SessionStart/invoke_session_prefetch.py`:

- **Hook type**: `SessionStart`
- Calls `skip_if_consumer_repo("session-prefetch")`
- Resolves `cache_dir = project_root / ".agents" / "cache"`
- Calls `prefetch_context(cache_dir)` from the skill module
- Calls `format_context_output(context)` and prints to stdout
- Wraps everything in `try/except Exception` — any failure prints a one-line warning to stderr and exits 0 (session start must never be blocked)
- Exits 0 always

---

### Step 10 — Register Hooks in `.claude/settings.json`

Add two entries to the existing `settings.json`:

**SessionStart** — append after the existing `invoke_adr_change_detection.py` entry:
```json
{
  "type": "command",
  "command": "python3 -u .claude/hooks/SessionStart/invoke_session_prefetch.py",
  "statusMessage": "Prefetching session context (OODA Orient phase)"
}
```

**PostToolUse / Bash** — append to the existing `Bash` matcher block:
```json
{
  "type": "command",
  "command": "python3 -u .claude/hooks/PostToolUse/invoke_error_observer.py",
  "statusMessage": "Classifying tool errors and injecting recovery hints"
}
```

Also add a cache invalidation call inside the same Bash PostToolUse block by having `invoke_error_observer.py` call `invalidate_on_trigger()` from the prefetch module — this avoids a separate hook entry.

---

### Step 11 — Update `.agents/AGENTS.md` Skill Catalog

In `.agents/AGENTS.md`, update the **Skill-First Checkpoint** table (or create if absent) to add:

| Operation | Skill |
|---|---|
| Classify tool errors | `error-recovery` |
| Prefetch session context | `session-prefetch` |

---

### Step 12 — Create Serena Memory Index Files

Create `.serena/memories/skills-error-recovery-index.md` with the standard two-column table format:

```
| Keywords | File |
|----------|------|
| error recovery loop classification hint retry | error-recovery-skill |
```

Create `.serena/memories/skills-session-prefetch-index.md`:

```
| Keywords | File |
|----------|------|
| prefetch session context ooda orient cache git pr ci | session-prefetch-skill |
```

Add rows for both new index files to `.serena/memories/memory-index.md` under the appropriate task keyword columns (create `.serena/memories/memory-index.md` if absent).

---

### Step 13 — Create `.agents/sessions/errors.jsonl` Placeholder

Create `.agents/sessions/errors.jsonl` as an empty file (or with a comment header line) so the directory structure is committed and the log file path is predictable. Add it to `.gitignore` if runtime error logs should not be committed, or keep it tracked if the graduation mechanism depends on committed history.

---

## Success Criteria

### Error Classification & Recovery
- [ ] Error taxonomy implemented with 5 types
- [ ] Recovery hints for top 10 failure patterns
- [ ] Loop detection breaks 80% of infinite loops
- [ ] Pattern graduation to Serena memory working

### OODA-Optimized Prefetch
- [ ] Session start prefetches 5 context types
- [ ] Cache invalidation on relevant git/gh ops
- [ ] Measured 50%+ reduction in "Orient" phase time
- [ ] Works in both Copilot CLI and Claude Code

---

## Testing Strategy

1. **Unit tests** for `classify_error.py` and `session_prefetch.py` in `tests/` directory
2. **Integration tests** for hook registration and cache file I/O
3. **Manual testing** of prefetch output and error hint injection
4. **Graduation script** validation with mock error logs

---

Execution Information

Branch: main
Commit: 2058fbe

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[rjmurillo]

Velocity Accelerator: 2 Opportunities Detected

Triage issue #1330: feat: Error Classification & Recovery + OODA-Optimized Memor

• Type: complexity_triage
• Priority: medium
• Suggested Agent: agent-security
• Issue labeled with medium complexity.
  Suggested agents: agent-security, agent-architect, agent-devops, agent-implementer, agent-qa, agent-analyst

Route issue #1330 to agent-security, agent-architect, agent-devops, agent-implementer, agent-qa, agent-analyst

• Type: agent_routing
• Priority: low
• Suggested Agent: agent-security
• Issue content suggests routing to: agent-security, agent-architect, agent-devops, agent-implementer, agent-qa, agent-analyst
  Complexity: medium

[coderabbitai]

🔗 Related PRs

#301 - docs: autonomous PR monitoring prompt and retrospective [merged]
#315 - feat(skill): add ADR review skill [merged]
#370 - fix(ci): RCA for Issue #357 + implement #338 retry logic [merged]
#546 - fix(agents): resolve platform drift in 3 agents [merged]
#1110 - feat: inject retrieval-led reasoning directives across all phases [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 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]

Product Requirements Document

Important

This PRD was automatically generated based on issue triage escalation.
Complexity Score: 8/12 (Detailed)
Escalation Criteria: feature_request,research_required,multi_phase_work,architectural_impact

About this PRD

This PRD was generated by the Explainer Agent after the issue was flagged
for detailed analysis. The document is designed to be self-contained - it can
be passed to a separate AI agent instance for implementation without additional
context.

PRD Depth Levels:

• Standard (4-6): Brief analysis, clear requirements
• Detailed (7-9): Research section, blocking questions
• Comprehensive (10-12): Phased implementation, risk analysis

---

The file path exists, so I need to use the edit tool to create a new file or output the PRD directly. Let me output the PRD content since the create failed.

PRD: Error Classification & Recovery + OODA-Optimized Memory Prefetch Skills

Executive Summary

This PRD addresses two complementary skills to improve agent resilience and responsiveness: Error Classification & Recovery (systematic failure handling) and OODA-Optimized Memory Prefetch (predictable context preloading). Both skills target inefficiencies identified in agent workflows where failures cascade and context gathering wastes valuable OODA cycle time.

Scope	Status	Blocker
Error Classification & Recovery	🟢 READY	None
OODA-Optimized Memory Prefetch	🟢 READY	None
Shared Infrastructure (.agents/cache/, hooks)	🟢 READY	None
Integration with Copilot CLI	🟡 PARTIAL	Requires hook wrapper script testing
Integration with Claude Code	🟢 READY	Existing hook infrastructure

Verdict: READY with minor testing validation needed for Copilot CLI integration.

---

Problem Statement

Current State

Component	Current Behavior	Gap
Error Handling	Ad-hoc retry or abort	No classification, no recovery hints
Loop Detection	None	Agents repeat failed tool calls indefinitely
Context Gathering	Fetched on-demand each session	2-3 turns wasted on predictable queries
Session Start	Manual git/gh queries	Redundant API calls across sessions
Pattern Learning	reflect skill captures post-session	No real-time error pattern capture

Gap Analysis

1. Error Classification Gap: Tools fail with exit codes, but agents lack taxonomy to route recovery strategies. ADR-035 defines exit codes (0=success, 1=logic, 2=config, 3=external, 4=auth), but no hook observes and classifies failures.

2. Recovery Hint Gap: Agents encounter the same failure patterns repeatedly without learning. The reflect skill captures learnings post-session, but real-time hint injection during failures is missing.

3. OODA Cycle Inefficiency: Research shows 88-99% cycle time reduction is possible with prefetch. Current agents waste "Orient" phase on predictable context (git status, open PRs, CI status).

4. Cache Infrastructure Gap: No .agents/cache/ directory exists. Ephemeral context has no storage location.

User Impact

User Type	Impact	Severity
Agent Operators	Failures cascade, requiring manual intervention	HIGH
Developers using agents	Slow session starts, redundant queries	MEDIUM
CI/CD pipelines	Agent loops cause job timeouts	HIGH

---

Research Findings

Primary Sources

ADR-035 Exit Code Standardization (CONFIRMED):

• Exit codes: 0=success, 1=logic, 2=config, 3=external, 4=auth
• Hook scripts exempt from ADR-035 (Claude interprets exit codes specially)
• JSON decision mode recommended for PreToolUse hooks

ADR-007 Memory-First Architecture (CONFIRMED):

• Memory retrieval MUST precede reasoning
• Serena is canonical, Forgetful is supplementary
• Pattern learning documented in memory, not executable scripts

ADR-008 Protocol Automation via Lifecycle Hooks (CONFIRMED):

• Lifecycle hooks enforce SESSION-PROTOCOL
• Hook types: session.start, session.end, task.pre, task.post, file.modify, commit.pre
• Existing PostToolUse and SessionStart hooks in .claude/hooks/

Existing Hook Infrastructure (CONFIRMED):

• .claude/hooks/PostToolUse/invoke_markdown_auto_lint.py: Pattern for post-tool processing
• .claude/hooks/SessionStart/invoke_session_initialization_enforcer.py: Pattern for session initialization
• Hook utilities in .claude/lib/hook_utilities/

Secondary Sources

Issue Research Basis (LIKELY):

• 39% loop recovery rate with classification + hint injection
• 85% precision in failure type detection
• 88-99% OODA cycle time reduction with prefetch

Reflect Skill Pattern (CONFIRMED):

• Confidence levels: HIGH (corrections), MEDIUM (preferences), LOW (notes)
• Pattern graduation after 3+ successful recoveries
• Storage in .serena/memories/{skill-name}-observations.md

---

Proposed Solution

Phase 1: Shared Infrastructure (Status: READY)

Estimated Effort: S (Small)
Blockers: None

Task	Description
1.1	Create .agents/cache/ directory with .gitignore for ephemeral files
1.2	Create .agents/recovery-hints.yaml schema for failure-to-recovery mappings
1.3	Create error logging structure .agents/sessions/errors.jsonl

Phase 2: Error Classification & Recovery (Status: READY)

Estimated Effort: M (Medium)
Blockers: None (depends on Phase 1)

Task	Description
2.1	Create error taxonomy enum (TOOL_FAILURE, REASONING_DRIFT, LOOP, SCOPE_CREEP, CONTEXT_OVERFLOW)
2.2	Implement error observer hook .claude/hooks/PostToolUse/invoke_error_classifier.py
2.3	Implement loop detection (3+ repeated tool calls)
2.4	Create recovery-hints.yaml with top 10 failure patterns
2.5	Implement hint injection into next turn context
2.6	Implement pattern graduation to Serena memory (3+ successful recoveries)

Phase 3: OODA-Optimized Memory Prefetch (Status: READY)

Estimated Effort: M (Medium)
Blockers: None (depends on Phase 1)

Task	Description
3.1	Create session prefetch script .agents/hooks/session_prefetch.py
3.2	Implement prefetch targets (git_branch, git_status, open_prs, recent_commits, ci_status)
3.3	Implement cache storage to .agents/cache/session_context.json
3.4	Integrate with SessionStart hook for context injection
3.5	Implement smart invalidation triggers
3.6	Add cache TTL management

Phase 4: Integration Testing (Status: DEPENDS)

Estimated Effort: S (Small)
Blockers: Phases 2 and 3 completion

Task	Description
4.1	Test error classification with simulated failures
4.2	Test loop detection breaks infinite loops
4.3	Test prefetch reduces session start time
4.4	Validate Copilot CLI integration
4.5	Validate Claude Code integration

---

Functional Requirements

FR-1: Error Classification

Priority: P1

ID	Requirement	Acceptance Criteria
FR-1.1	System MUST classify tool failures by exit code per ADR-035	Exit code 1→LOGIC, 2→CONFIG, 3→EXTERNAL, 4→AUTH
FR-1.2	System MUST detect reasoning drift when output diverges from original intent	Detection triggers on expansion phrases
FR-1.3	System MUST detect infinite loops (3+ repeated tool calls)	Loop broken within 5 seconds of detection
FR-1.4	System MUST detect scope creep when task expands	User prompted for confirmation before expansion
FR-1.5	System MUST detect context overflow warnings	Agent notified to compress context

FR-2: Recovery Hints

Priority: P1

ID	Requirement	Acceptance Criteria
FR-2.1	System MUST load recovery hints from YAML configuration	recovery-hints.yaml parsed on hook initialization
FR-2.2	System MUST match failure patterns to hints	Pattern matching via regex or substring
FR-2.3	System MUST inject hints into next turn context	Hint visible in Claude's context window
FR-2.4	System MUST log recovery attempts	JSON entry in errors.jsonl
FR-2.5	System MUST graduate patterns after 3+ successes	Pattern written to Serena memory

FR-3: Session Prefetch

Priority: P1

ID	Requirement	Acceptance Criteria
FR-3.1	System MUST prefetch git branch on session start	Branch name in session_context.json
FR-3.2	System MUST prefetch git status on session start	Status output in session_context.json
FR-3.3	System MUST prefetch open PRs (assigned to user)	PR list (max 5) in session_context.json
FR-3.4	System MUST prefetch recent commits (5)	Commit list in session_context.json
FR-3.5	System MUST prefetch CI status (last run)	CI status in session_context.json
FR-3.6	System MUST inject prefetched context into session	Context visible in first turn

FR-4: Cache Invalidation

Priority: P2

ID	Requirement	Acceptance Criteria
FR-4.1	Cache MUST invalidate on git commit/push/pull/checkout	Stale cache cleared within 1 second
FR-4.2	Cache MUST invalidate on gh pr create/merge/close	PR cache refreshed
FR-4.3	Cache MUST respect TTL (configurable, default 5-30 min)	Expired entries not returned
FR-4.4	Cache MUST support manual invalidation	--invalidate flag available

---

Technical Design

Directory Structure

.agents/
├── cache/                          # NEW: Ephemeral context cache
│   ├── .gitignore                  # Ignore all cache files
│   └── session_context.json        # Prefetched context
├── hooks/                          # NEW: Agent hooks (complements .claude/hooks)
│   └── session_prefetch.py         # Prefetch script
├── recovery-hints.yaml             # NEW: Failure-to-recovery mappings
└── sessions/
    └── errors.jsonl                # NEW: Error pattern log

.claude/
├── hooks/
│   └── PostToolUse/
│       └── invoke_error_classifier.py  # NEW: Error observer hook
└── skills/
    ├── error-classification/       # NEW: Skill documentation
    │   └── SKILL.md
    └── ooda-prefetch/              # NEW: Skill documentation
        └── SKILL.md

Error Observer Hook

# .claude/hooks/PostToolUse/invoke_error_classifier.py
"""Classify tool failures and inject recovery hints.

Hook Type: PostToolUse
Exit Codes (Claude Hook Semantics, exempt from ADR-035):
    0 = Always (non-blocking hook)
"""

from __future__ import annotations
import json
import sys
from enum import Enum
from pathlib import Path

class ErrorType(Enum):
    TOOL_FAILURE = "tool_failure"
    REASONING_DRIFT = "reasoning_drift"
    LOOP = "loop"
    SCOPE_CREEP = "scope_creep"
    CONTEXT_OVERFLOW = "context_overflow"
    TRANSIENT = "transient"

def classify_error(tool_name: str, exit_code: int, stderr: str) -> ErrorType:
    """Classify error based on ADR-035 exit codes and patterns."""
    if "rate limit" in stderr.lower():
        return ErrorType.TRANSIENT
    if exit_code == 2:
        return ErrorType.TOOL_FAILURE  # Config error
    if exit_code == 3:
        return ErrorType.TOOL_FAILURE  # External error
    if exit_code == 4:
        return ErrorType.TOOL_FAILURE  # Auth error
    if is_repeated_call(tool_name, count=3):
        return ErrorType.LOOP
    return ErrorType.TOOL_FAILURE

Recovery Hints Schema

# .agents/recovery-hints.yaml
version: "1.0"
description: "Failure pattern to recovery hint mappings"

tool_failures:
  gh:
    - pattern: "GraphQL: Could not resolve"
      hint: "Issue/PR number may not exist. Verify with `gh issue list`."
      confidence: HIGH
    - pattern: "HTTP 403"
      hint: "Rate limited. Wait 60s or use `gh api --cache 1h`."
      confidence: HIGH
  git:
    - pattern: "fatal: not a git repository"
      hint: "Not in a git repository. Check current directory."
      confidence: HIGH

reasoning_drift:
  - signal: "Let me also add..."
    hint: "STOP. Check if this is in scope. Original task was: {original_task}"

loop_detection:
  threshold: 3
  window_seconds: 60
  recovery: "break_and_summarize"

---

Risks and Mitigations

Risk	Likelihood	Impact	Mitigation
Hook overhead slows tool execution	Low	Medium	Async processing, <50ms target
False positive loop detection	Medium	Low	Configurable threshold, whitelist
Stale cache causes incorrect context	Medium	Medium	Aggressive TTL, invalidation triggers
Recovery hints mislead agent	Low	Medium	HIGH confidence hints only initially
Prefetch fails in offline mode	High	Low	Graceful degradation, empty values

---

Success Metrics

Metric	Target
Loop recovery rate	80% of detected loops broken successfully
Error classification accuracy	85% correct classification
Session start time reduction	50% reduction in "Orient" phase
Redundant API calls per session	Reduce from 5+ to 1 (prefetch only)
Pattern graduation to memory	5+ patterns graduated in first month

---

Open Questions (Non-Blocking)

1. Synchronous vs Asynchronous: Start synchronous with <50ms target
2. Offline Handling: Graceful degradation with empty values
3. Agent-Specific Hints: Shared hints with optional agent-specific overrides

---

Appendices

Appendix A: Research Sources

• ADR-035: Exit Code Standardization
• ADR-007: Memory-First Architecture
• ADR-008: Protocol Automation via Lifecycle Hooks
• reflect skill SKILL.md
• Existing PostToolUse and SessionStart hook examples

Appendix B: Error Taxonomy Reference

Type	Detection Signal	ADR-035 Code	Recovery Strategy
TOOL_FAILURE	Non-zero exit, API error	1, 3, 4	Retry with backoff, fallback tool
REASONING_DRIFT	Output diverges from intent	N/A	Re-anchor with original prompt
LOOP	Repeated tool calls (3+)	N/A	Break loop, summarize progress
SCOPE_CREEP	Task expands beyond original	N/A	Checkpoint, confirm with user
CONTEXT_OVERFLOW	Token limit warnings	N/A	Compress context, archive turns

---

[COMPLETE] PRD generated with comprehensive analysis of existing codebase patterns, ADR alignment, and implementation-ready specifications.

_{Generated by AI PRD Generation | View Workflow}

[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-memory", "area-infrastructure"]
Priority	P2
Milestone	v1.2
Feature Review	DEFER
PRD Escalation	Generated (see below)

Categorization Analysis

```json
{
  "labels": ["enhancement", "agent-memory", "area-infrastructure"],
  "category": "enhancement",
  "confidence": 0.95,
  "reasoning": "Feature proposal for two new skills (error classification/recovery and OODA-optimized prefetch) with detailed implementation plans and success criteria"
}

</details>

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

```json
Based on the roadmap analysis, this issue proposes two new skills for agent resilience (Error Classification & Recovery) and responsiveness (OODA-Optimized Memory Prefetch). This aligns with the Skill Management System epic in the backlog and represents significant new feature development.

**Analysis:**
- **Impact**: Medium-High (improves agent resilience across platforms)
- **Urgency**: Not immediate (enhancement, current functionality works)
- **Feature Request**: Yes (two new skills)
- **Research Required**: Yes (open questions listed)
- **Multi-Phase Work**: Yes (two distinct skills)
- **Architectural Impact**: Yes (hooks, caching, shared infrastructure in `.agents/`)

**Complexity Scoring:**
- Scope: System-wide (3) - affects hooks, caching, multiple agents
- Dependencies: Internal only (2) - builds on existing infrastructure
- Uncertainty: Some unknowns (2) - has open questions
- Stakeholders: Internal only (1)
- **Total: 8**

```json
{
  "milestone": "v1.2",
  "priority": "P2",
  "epic_alignment": "Skill Management System",
  "confidence": 0.80,
  "reasoning": "Aligns with Skill Management System backlog epic; significant new infrastructure but not blocking current v1.1 maintainability work",
  "escalate_to_prd": true,
  "escalation_criteria": ["feature_request", "research_required", "multi_phase_work", "architectural_impact"],
  "complexity_score": 8
}

</details>


<details>
<summary>Feature Request Review</summary>

I now have sufficient context to evaluate the feature request. Let me check one more relevant file for existing patterns.

I now have sufficient context to write a comprehensive feature request review.

## Thank You

Thank you for this detailed and well-researched proposal. The research basis with specific metrics (39% loop recovery rate, 85% precision, 88-99% cycle time reduction) and structured implementation plans demonstrates serious thought about agent resilience.

## Summary

This proposal contains two skills: (1) Error Classification & Recovery for systematic failure detection and self-correction using a 5-type taxonomy with recovery hint injection, and (2) OODA-Optimized Memory Prefetch for pre-computing context at session start to reduce "Orient" phase latency. Both target improved agent autonomy and reduced API calls.

## Evaluation

| Criterion | Assessment | Confidence |
|-----------|------------|------------|
| User Impact | High value for agent operators. Reduces manual intervention on failures and speeds up session start. | Medium |
| Implementation | Significant effort. Error observer requires PostToolUse hook integration. Prefetch requires new cache layer in `.agents/cache/`. Both require cross-platform (Copilot CLI + Claude Code) support. | High |
| Maintenance | Moderate. Recovery hints require curation. Cache invalidation logic adds complexity. Pattern graduation to MEMORY.md creates ongoing maintenance. | High |
| Alignment | Strong alignment with ADR-007 (memory-first architecture), ADR-008 (protocol automation hooks), ADR-035 (exit code standardization). References existing patterns. | High |
| Trade-offs | Cache staleness risk. Synchronous error classification adds latency. Potential duplication with existing `reflect` skill for pattern learning. | High |

## Research Findings

### What I Could Determine

- **Existing hooks infrastructure**: `.claude/hooks/PostToolUse/` exists with 2 hooks. SessionStart has 2 hooks including `invoke_session_initialization_enforcer.py`.
- **ADR-035 already defines exit codes**: 0=success, 1=logic, 2=config, 3=external, 4=auth. Error taxonomy in proposal aligns.
- **Reflect skill exists**: `.claude/skills/reflect/SKILL.md` already captures learnings with HIGH/MED/LOW confidence and graduates patterns to memory. Pattern graduation proposed here may duplicate.
- **Session prefetch partial exists**: `invoke_session_initialization_enforcer.py` already injects git branch and session status at session start (lines 89-100).
- **500+ session logs exist**: `.agents/sessions/` contains extensive history. Pattern learning has data source.
- **ADR-007 mandates memory-first**: Architecture supports the OODA prefetch concept. Memory retrieval before reasoning is already required.
- **No `.agents/cache/` directory exists**: Would be new infrastructure.
- **No `errors.jsonl` pattern exists**: New logging format proposed.

### What Requires Manual Research

- **UNKNOWN**: Actual loop recovery rates in production (39% cited from external research, not this repo)
- **UNKNOWN**: Current "time to first tool call" baseline to validate 80% reduction claim
- **UNKNOWN**: GitHub API rate limit impact of current vs. prefetched approach
- **UNKNOWN**: Whether Copilot CLI supports pre-session hooks (different architecture from Claude Code)

## Questions for Submitter

1. The `reflect` skill already handles pattern graduation with 3+ occurrences (SKILL.md lines 200-202). How does the proposed pattern learning differ, and should it integrate with `reflect` rather than duplicate?

2. The proposal references MEMORY.md for pattern storage, but this project uses Serena memories (`.serena/memories/`) per ADR-007. Should recovery hints integrate with the existing memory tier architecture?

3. For Copilot CLI integration, what hook mechanism do you propose? Claude Code uses `.claude/hooks/`; Copilot CLI does not appear to have equivalent pre-session hooks in this repository.

## Recommendation

**RECOMMENDATION: DEFER**

**Rationale**: Strong concept with good alignment to existing ADRs, but significant overlap with existing infrastructure (reflect skill, session initialization hook, ADR-035 exit codes). The proposal would benefit from an integration design that builds on existing patterns rather than parallel systems. Additionally, Copilot CLI hook architecture requires research before cross-platform claims can be validated.

## Suggested Actions

- **Assignees**: none suggested (requires design refinement)
- **Labels**: `needs-design`, `area-hooks`, `size-large`
- **Milestone**: backlog
- **Next Steps**:
  1. Author to clarify integration with existing `reflect` skill pattern graduation
  2. Research Copilot CLI hook mechanism viability before committing to cross-platform scope
  3. Propose incremental approach: start with Error Classification as PostToolUse hook, defer prefetch until error handling proves value
  4. Create design document showing how proposed components integrate with ADR-007 memory tiers and existing hook infrastructure

</details>

---

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