context-health-monitor

allowed-tools	["Read","Write","Grep","Glob","Bash"]
description	Use when debugging fails 3 times, same approach repeats, or context usage exceeds 60% to trigger state dump and recovery.
name	context-health-monitor
trigger	컨텍스트 상태 확인, 세션 덤프, 3-strike 발동, 세션 인수인계, context health, session handoff, 컨텍스트 압축, context compact, 세션 일시중지, session pause, 순환 감지, circular detection, 불확실성 로깅, uncertainty logging, 컨텍스트 회전, context rot, 패턴 추출, pattern extraction, 상태 저장, state dump, 3 strike rule, circular detection, context window full, token limit

Quick Reference

• 3-Strike Rule: 동일 이슈 3회 실패 → STOP → STATE.md 저장 → fresh session 권장
• Circular Detection: 동일 접근 2회 반복 → 근본적 대안 제안 또는 /pause
• Uncertainty: 명확하지 않을 시 추측 금지 → DECISIONS.md 기록 후 사용자 확인
• Context >60%: 토큰 사용량 60% 초과 시 즉시 /compact 실행 (80% 자동 전)
• Pattern Extraction: 핵심 학습 시 PATTERNS.md 저장 (2KB/20개 이내 유지)

Purpose

Prevent "Context Rot" — the quality degradation that occurs as the agent processes more information in a single session.

When This Skill Activates

The agent should self-monitor for these warning signs:

Warning Signs

Signal	Threshold	Action
Repeated debugging	3+ failed attempts	Trigger state dump
Going in circles	Same approach tried twice	Stop and reassess
Confusion indicators	"I'm not sure", backtracking	Document uncertainty
Context window filling	>60% token usage	Run /compact proactively
Session length	Extended back-and-forth	Recommend /pause or /handoff

Behavior Rules

Rule 1: The 3-Strike Rule

If debugging the same issue fails 3 times:

1. STOP attempting fixes
2. Document in .hxsk/STATE.md:
   • What was tried
   • What errors occurred
   • Current hypothesis
3. Recommend user start fresh session
4. Do NOT continue with more attempts

Rule 2: Circular Detection

If the same approach is being tried again:

1. Acknowledge the repetition
2. List what has already been tried
3. Propose a fundamentally different approach
4. Or recommend /pause for fresh perspective

Rule 3: Uncertainty Logging

When uncertain about an approach:

1. State the uncertainty clearly
2. Document in .hxsk/DECISIONS.md:
   • The uncertain decision
   • Why it's uncertain
   • Alternatives considered
3. Ask user for guidance rather than guessing

Rule 4: Proactive Compaction

When context window usage exceeds ~60%:

1. Run /compact before auto-compaction kicks in (~80%)
2. If task is nearly done: finish first, then compact
3. If task is complex with much remaining work: compact now to preserve budget
4. If context is beyond recovery (repeated compactions, degrading quality): use /handoff and start fresh

Pattern Memory

Prerequisites

• .hxsk/memories/ directory structure must exist

Purpose

Detect recurring failure patterns across sessions. Store health events for trend analysis so systemic issues are surfaced early.

On 3-Strike Trigger

Check if the same issue has recurred, then store the event:

Grep(pattern: "3-strike|{issue}", path: ".hxsk/memories/health-event/", output_mode: "files_with_matches")

bash .hxsk/hooks/md-store-memory.sh \
  "3-Strike: {issue}" \
  "{approaches tried, errors seen, current hypothesis}" \
  "health,3-strike,{component}" \
  "health-event"

If the search reveals the same issue appeared before, flag it as a recurring problem in the state dump.

On Circular Detection

Check if the same loop pattern was seen before, then store:

Grep(pattern: "circular|{approach}", path: ".hxsk/memories/health-event/", output_mode: "files_with_matches")

bash .hxsk/hooks/md-store-memory.sh \
  "Circular: {approach}" \
  "{what repeated, why it looped}" \
  "health,circular,{component}" \
  "health-event"

On Session Handoff

Persist session context for the next session:

bash .hxsk/hooks/md-store-memory.sh \
  "Handoff: {reason}" \
  "{current state, recommendations for next session}" \
  "health,handoff" \
  "session-handoff"

Proactive Check

When this skill activates, scan recent memory files for failure trends:

Glob(pattern: ".hxsk/memories/health-event/*.md")

Read the most recent files and review for clusters of 3-strike, circular, or blocked keywords. If a trend is detected (2+ similar events), warn the user proactively before beginning work.

---

State Dump Format

When triggered, write to .hxsk/STATE.md:

## Context Health: State Dump

**Triggered**: [date/time]
**Reason**: [3 failures / circular / uncertainty]

### What Was Attempted
1. [Approach 1] — Result: [outcome]
2. [Approach 2] — Result: [outcome]
3. [Approach 3] — Result: [outcome]

### Current Hypothesis
[Best guess at root cause]

### Recommended Next Steps
1. [Fresh perspective action]
2. [Alternative approach to try]

### Files Involved
- [file1.ext] — [what state it's in]
- [file2.ext] — [what state it's in]

Pattern Extraction

When valuable patterns are discovered during a session, extract to .hxsk/PATTERNS.md:

What to Extract

Category	Examples
Architecture	"jose > jsonwebtoken for Edge runtime"
Conventions	"API routes: src/app/api/{resource}/route.ts"
Gotchas	"httpOnly cookies require HTTPS even on localhost"
Integrations	"Stripe webhooks need raw body parser disabled"

Extraction Protocol

1. During task completion, identify reusable learnings
2. Check current count: grep -c "^-" .hxsk/PATTERNS.md
3. If < 20 items: Append new pattern
4. If >= 20 items: Replace oldest (least referenced) pattern
5. Size check: Keep under 2KB

# Check PATTERNS.md size
wc -c .hxsk/PATTERNS.md  # Should be < 2048

Pattern Format

## {Category}
- {Concise pattern description} — {file:line if applicable}

---

Context File Management

Active Layer (Read Every Session)

File	Size Limit	Purpose
PATTERNS.md	2KB	Core learnings
CURRENT.md	1KB	Session context
prd-active.json	3KB	Pending tasks

Archive Layer (Don't Read Routinely)

File/Folder	Purpose
JOURNAL.md	Session history
CHANGELOG.md	Change history
prd-done.json	Completed tasks
reports/	Analysis reports
research/	Research docs
archive/	Monthly archives

---

Integration

This skill integrates with:

• /compact — Proactive context compaction (Rule 4)
• /handoff — Lightweight session transfer when context is beyond recovery
• /pause — Full HXSK session handoff with state archival
• /resume — Loads the state dump context
• PATTERNS.md — Pattern extraction on session end
• .gemini/GEMINI.md Rule 3 (Context Hygiene) — After 3 failed debug attempts: STOP, summarize to STATE.md, document blocker in DECISIONS.md, recommend fresh session

Scripts

• .hxsk/hooks/compact-context.sh: Archive old entries, prune PATTERNS.md to 2KB limit

Iron Laws

NO CONTINUE DEBUGGING WITHOUT STATE.md DUMP FIRST (After 3 failures) NO REPEAT APPROACH WITHOUT ALTERNATIVE PROPOSAL OR /pause FIRST (After 2 loops) NO EXCEED 80% CONTEXT WITHOUT /compact FIRST (Trigger at 60%) NO APPEND TO PATTERNS.md WITHOUT SIZE/COUNT CHECK FIRST (Max 2KB, 20 items) NO GUESS SOLUTION WITHOUT USER GUIDANCE FIRST (When uncertain) NO STORE MEMORY WITHOUT .hxsk/memories/ DIRECTORY FIRST NO RECOMMEND FRESH SESSION WITHOUT DOCUMENTING STATE FIRST NO COMPACT MID-FINISH WITHOUT COMPLETING TASK FIRST (If task is nearly done)