Pre Flight Check

Name: Pre Flight Check
Author: pskoett

pskoett/pskoett-skills

6 installs
272 repo stars
Updated June 12, 2026
pskoett/pskoett-skills

Helps with ai & agent building tasks.

About

pre-flight-check is a Claude Code skill for ai & agent building. It helps solo builders move faster with AI-assisted development.

pre-flight-check
AI & Agent Building
AI-coding skill

Pre Flight Check by the numbers

6 all-time installs (skills.sh)
Ranked #12,825 of 16,546 AI & Agent Building skills by installs in the Skillselion catalog
Data as of Aug 4, 2026 (Skillselion catalog sync)

npx skills add https://github.com/pskoett/pskoett-skills --skill pre-flight-check

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

[![Listed on Skillselion](https://skillselion.com/badge/skills/pskoett/pskoett-skills/pre-flight-check.svg)](https://skillselion.com/skills/pskoett/pskoett-skills/pre-flight-check)

Installs	6
repo stars	★ 272
Last updated	June 12, 2026
Repository	pskoett/pskoett-skills ↗

What it does

Helps with ai & agent building tasks.

Files

SKILL.mdMarkdownGitHub ↗

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 the harness-updater plugin agent, or a human applying the gap report when the plugin isn't installed)
Does not run evals (that's eval-creator)
Does not block execution — it surfaces information, the agent decides what to act on

#!/bin/bash
set -e

# Pre-flight check hook — surfaces accumulated learning signals at session start.
# Outputs nothing if there are no signals (zero overhead for clean projects).

LEARNINGS_DIR=".learnings"
EVALS_DIR=".evals"
HANDOFF_DIR=".context-surfing"

# Count learning entries
if [ -f "$LEARNINGS_DIR/LEARNINGS.md" ]; then
  learning_count=$(grep -c '^\## \[LRN-' "$LEARNINGS_DIR/LEARNINGS.md" 2>/dev/null) || learning_count=0
else
  learning_count=0
fi

# Count error entries
if [ -f "$LEARNINGS_DIR/ERRORS.md" ]; then
  error_count=$(grep -c '^\## \[ERR-' "$LEARNINGS_DIR/ERRORS.md" 2>/dev/null) || error_count=0
else
  error_count=0
fi

# Count VERIFIED heals on file (filed by self-healing). Only `Status: verified`
# entries count — `pending-verify` / `abandoned` heals are NOT known-good fixes
# and must not be surfaced as such. Surfaced so the agent applies a proven fix
# before reinventing one.
if [ -f "$LEARNINGS_DIR/HEALS.md" ]; then
  heal_count=$(grep -cE '^\*\*Status\*\*:[[:space:]]*verified' "$LEARNINGS_DIR/HEALS.md" 2>/dev/null) || heal_count=0
else
  heal_count=0
fi

# Count promotion-ready patterns: entries whose Recurrence-Count has reached the
# promotion threshold (>= 3). No skill writes a "promotion_ready" status, so
# readiness is computed from the Recurrence-Count field that self-improvement and
# self-healing actually record. Scans both LEARNINGS.md and HEALS.md.
promo_count=0
for f in "$LEARNINGS_DIR/LEARNINGS.md" "$LEARNINGS_DIR/HEALS.md"; do
  if [ -f "$f" ]; then
    n=$(grep -oiE 'Recurrence-Count[^0-9]*[0-9]+' "$f" 2>/dev/null | grep -oE '[0-9]+$' | awk '$1>=3' | wc -l | tr -d ' ')
    promo_count=$((promo_count + ${n:-0}))
  fi
done

# Count failed evals
if [ -f "$EVALS_DIR/EVAL_INDEX.md" ]; then
  eval_fail_count=$(grep -c '| fail |' "$EVALS_DIR/EVAL_INDEX.md" 2>/dev/null) || eval_fail_count=0
else
  eval_fail_count=0
fi

# Count handoff files
if [ -d "$HANDOFF_DIR" ]; then
  handoff_count=$(find "$HANDOFF_DIR" -name "handoff-*.md" -type f 2>/dev/null | wc -l | tr -d ' ')
else
  handoff_count=0
fi

# Calculate total signals
signals=$((learning_count + error_count + heal_count + promo_count + eval_fail_count + handoff_count))

# Only output if there are signals
if [ "$signals" -gt 0 ]; then
  echo "<pre-flight-check>"
  echo "Active learnings: $learning_count | Recent errors: $error_count | Verified heals: $heal_count | Promotion-ready: $promo_count | Failed evals: $eval_fail_count | Handoffs: $handoff_count"

  # Surface high-priority items
  if [ "$promo_count" -gt 0 ]; then
    echo ""
    echo "Promotion-ready patterns exist — consider running /learning-aggregator."
  fi

  if [ "$eval_fail_count" -gt 0 ]; then
    echo "Failed evals detected — consider running /eval-creator run before starting new work."
  fi

  if [ "$handoff_count" -gt 0 ]; then
    echo "Unread handoff files from previous sessions — read before starting new work."
  fi

  if [ "$heal_count" -gt 0 ]; then
    echo "Verified heals on file in HEALS.md — check for a known fix before reinventing one."
  fi

  echo "</pre-flight-check>"
fi