pskoett/pre-flight-check

Pre-Flight Check

Surfaces relevant accumulated knowledge at the start of a session. This is the bridge that connects the outer loop back into the inner loop — it makes prior learnings visible before the agent starts work.

Without this, accumulated .learnings/ are invisible to new sessions. The agent repeats mistakes that were already captured because nobody told it to look.

When It Runs

• Automatically via SessionStart hook (lightweight scan, ~100-200 tokens)
• Manually before major tasks (deep scan with area filtering)

Hook Output (Automatic — Lightweight)

The SessionStart hook (scripts/pre-flight.sh) does a fast scan and outputs a brief reminder if there are relevant signals:

<pre-flight-check>
Active learnings: N entries in .learnings/
Recent errors (last 7 days): N
Promotion-ready patterns: N
Failed evals: N

High-priority items:
- [Pattern-Key]: [one-line summary] (seen N times)
- [Pattern-Key]: [one-line summary] (seen N times)

Consider running /learning-aggregator if promotion-ready count > 0.
</pre-flight-check>

If there are no signals (empty .learnings/, no failed evals), the hook outputs nothing — zero overhead.

Manual Deep Scan

When invoked explicitly, the pre-flight check does a deeper analysis:

Step 1: Scan .learnings/

Read .learnings/LEARNINGS.md, .learnings/ERRORS.md, .learnings/FEATURE_REQUESTS.md, and .learnings/HEALS.md (the last from self-healing — verified runtime fixes filed during prior sessions; surface these prominently so the agent applies known fixes before reinventing them).

For each entry, extract:

• Pattern-Key, Summary, Priority, Status, Area, Related Files, Recurrence-Count, Last-Seen
• For HEAL entries: also Active-Context, Trigger, and any Handoff block flagging promotion readiness

Step 2: Scan .evals/ (if exists)

Read .evals/EVAL_INDEX.md for any failed or stale evals.

Step 3: Check Context-Surfing Handoffs

Look for unread files in .context-surfing/ (same as handoff-checker.sh but integrated).

Step 4: Relevance Filter

If the user described the task area, filter learnings to:

• Entries whose Area matches the task
• Entries whose Related Files overlap with likely-touched files
• Entries with Priority: high/critical regardless of area
• Entries with Recurrence-Count >= 3 (promotion-ready by recurrence threshold — need attention)

Step 5: Output

## Pre-Flight Check

### Task Area: [inferred or stated]

### Relevant Learnings
| ID | Summary | Recurrence | Priority | Status |
|----|---------|-----------|----------|--------|
| LRN-... | ... | 3 | high | pending |
| ERR-... | ... | 2 | medium | pending |

### Key Warnings
- [Pattern-Key]: "Concise warning based on learning" — seen N times, last on YYYY-MM-DD
- [Pattern-Key]: "Concise warning based on learning" — seen N times, last on YYYY-MM-DD

### Failed Evals
| Eval ID | Pattern-Key | Last Failed | Recovery Action |
|---------|------------|-------------|-----------------|
| eval-... | ... | YYYY-MM-DD | ... |

### Handoff Files
- [filename] — from session on YYYY-MM-DD

### Recommendations
- [ ] Read handoff files before starting
- [ ] Run learning-aggregator (N promotion-ready patterns)
- [ ] Fix failed evals before starting new work
- [ ] Watch for [specific pattern] in [area]

Integration

Upstream (feeds from)

• .learnings/*.md — accumulated learning entries from self-improvement
• .evals/EVAL_INDEX.md — eval results from eval-creator
• .context-surfing/ — handoff files from context-surfing

Downstream (feeds into)

• Inner loop context — the agent starts work with awareness of known patterns
• learning-aggregator — if promotion-ready count is high, recommend running it
• eval-creator — if failed evals exist, recommend fixing before new work

The Compounding Effect

This is where the blog's compounding happens:

Outer loop improves harness → pre-flight surfaces improvements → inner loop starts stronger

Every learning captured, every rule promoted, every eval created becomes visible at the next session start. The knowledge gaps get smaller with every cycle.

Incremental Scanning (future enhancement)

The hook script can be extended to use a local cache file (.pre-flight-cache.json) storing last-known state — entry counts, scan date, high-priority items — so the next session start only re-scans entries newer than the cached state. This would enable delta reporting ("since your last session, 2 new errors were logged and 1 pattern crossed the promotion threshold") and keep the hook near-instant regardless of how large .learnings/ grows. Not implemented today — the current hook scans directly on every session start.

What This Skill Does NOT Do

• Does not modify .learnings/ files (read-only)
• Does not promote patterns (that's harness-updater)
• Does not run evals (that's eval-creator)
• Does not block execution — it surfaces information, the agent decides what to act on