context-guardian

## Overview

A context guardian that preserves critical data before automatic compaction. Snapshots, integrity verification and zero information loss.

## When to Use This Skill

- When the user mentions "context compaction" or related topics
- When the user mentions "context loss" or related topics
- When the user mentions "context snapshot" or related topics
- When the user mentions "preserve context" or related topics
- When the user mentions "critical context" or related topics
- When the user mentions "before compacting" or related topics

## Do Not Use This Skill When

- The task is unrelated to context guardian
- A simpler, more specific tool can handle the request
- The user needs general-purpose assistance without domain expertise

## How It Works

A context-integrity system that protects complex technical projects against
information loss during Claude Code's automatic compaction. While the
`context-agent` acts AFTER sessions (save/load), context-guardian acts DURING
the session, detecting when compaction is near and running preservation
protocols with redundant verification.

## Why This Exists

Claude Code automatically compacts old messages when the context approaches
the window limit. That compaction is heuristic — it summarizes messages to
free up space, but inevitably loses detail. For simple projects, it works
fine. But for heavy technical projects (like ecosystems with 21+ skills,
security audits, architecture refactors), losing a single detail can cause
regressions, rework, or serious inconsistencies.

Context-guardian solves this by creating a pre-compaction protection layer:
it extracts, classifies, verifies and persists all critical information BEFORE
automatic compaction destroys it.

## Location

```
C:\Users\renat\skills\context-guardian\
├── SKILL.md                          # This file
├── references/
│   ├── extraction-protocol.md        # Detailed extraction protocol
│   └── verification-checklist.md     # Verification and redundancy checklist
└── scripts/
    └── context_snapshot.py           # Automatic snapshot script
```

## Integration With The Ecosystem

```
context-guardian (PRE-compaction)     context-agent (POST-session)
         │                                    │
         ├── Detects large context            ├── Saves a summary at the end
         ├── Extracts critical data           ├── Updates ACTIVE_CONTEXT.md
         ├── Verifies integrity               ├── Syncs MEMORY.md
         ├── Saves a verified snapshot        ├── Indexes FTS5 search
         └── Generates a transition briefing  └── Archives old sessions
```

context-guardian and context-agent are complementary:
- **context-guardian**: real-time protection, DURING the session
- **context-agent**: persistence between sessions, AFTER the session

## Automatic Activation (Claude Should Start On Its Own)

1. **Context limit**: when you notice you've already consumed ~60-70% of the
   context window (indicators: messages starting to be summarized, a compaction warning)
2. **Heavy projects**: sessions with many files edited, many tool calls,
   or projects with complex dependencies between components
3. **Before long tasks**: when an upcoming task may produce extensive output
   that would push the context past the limit

## Manual Activation (User Requests It)

- "save the state before compacting"
- "make a checkpoint"
- "snapshot the context"
- "I don't want to lose anything from this session"
- "get ready for compaction"
- "the context is getting big, protect it"

## Phase 1: Structured Extraction

Go through the entire conversation so far and extract critical categories.
For each category, classify by priority (P0 = fatal loss, P1 = serious loss,
P2 = tolerable loss).

**P0 — Fatal Loss (preserve with triple redundancy)**

| Category | What to extract | Example |
|-----------|--------------|---------|
| Technical decisions | Choices of architecture, pattern, technology AND the reason | "We use parameterized queries because f-strings cause SQL injection" |
| Task state | What was done, what's left, dependencies | "18/18 match OK, ZIP remaining" |
| Applied fixes | Bug, root cause, exact solution, affected files | "instagram/db.py: SQL injection via f-string → ? placeholders" |
| Generated/modified code | Exact path, changed lines, nature of the change | "match_skills.py:40-119: added 5 categories" |
| Errors found | Exact message, relevant stack trace, how it was fixed | "TypeError at line 45 → cast to int" |
| Commands that worked | The complete command that produced the correct result | "python verify_zips.py → 22/22 OK" |

**P1 — Serious Loss (preserve with verification)**

| Category | What to extract |
|-----------|--------------|
| Discovered patterns | Conventions, code patterns observed |
| Dependencies between components | "scan_registry.py AND match_skills.py must have identical categories" |
| User preferences | Language, style, level of detail, preferred workflow |
| Project context | Directory structure, key files, purpose |
| Open questions | Unanswered questions, unresolved ambiguities |

**P2 — Tolerable Loss (compact summary)**

| Category | What to extract |
|-----------|--------------|
| History of attempts | "I tried X, it didn't work because of Y, so Z" |
| Progress metrics | Counters, times, sizes |
| Exploratory discussions | Brainstorming, options considered and discarded |

## Phase 2: Integrity Verification

After extracting, verify that NOTHING critical was omitted.

**Verification Checklist (run mentally for each item):**

```
□ Each modified file has: path, nature of the change, reason
□ Each fixed bug has: symptom, root cause, solution, file
□ Each decision has: what, why, discarded alternatives
□ Each pending task has: description, priority, dependencies
□ Each pattern/convention has: rule, reason, examples
□ No information in one section contradicts another
□ Cross-references are consistent (e.g., "18 queries tested" appears in
  multiple places with the same number)
□ File paths are complete (absolute, not relative)
```

If any item fails, go back to Phase 1 and re-extract the missing information.

For details on advanced verification, read `references/verification-checklist.md`.

## Phase 3: Redundant Persistence

Save the extracted information in 3 layers of redundancy:

**Layer 1 — Structured snapshot (.md file)**

```bash
python C:\Users\renat\skills\context-guardian\scripts\context_snapshot.py save
```

Generates `C:\Users\renat\skills\context-guardian\data\snapshot-YYYYMMDD-HHMMSS.md` with
all the extracted information in a structured format.

If the script isn't available, create the file manually following the format
described in `references/extraction-protocol.md`.

**Layer 2 — Updated MEMORY.md**

Update `C:\Users\renat\.claude\projects\C--Users-renat-Skill-JUD\memory\MEMORY.md`
with the most critical P0 information in an ultra-compact format. MEMORY.md is loaded
automatically in every new session, so it is the last line of defense.

**Layer 3 — Context-agent save**

```bash
python C:\Users\renat\skills\context-agent\scripts\context_manager.py save
```

Triggers context-agent to save the complete session with FTS5 indexing.

## Phase 4: Transition Briefing

Generate a formatted text block that serves as a "business card" for the Claude
that continues after compaction. This briefing should be the LAST thing written before
compaction, so it stays at the top of the compacted context.

**Briefing format:**

```markdown

## Current State

- Project: [name]
- Phase: [current phase]
- Progress: [X/Y tasks complete]

## What Was Done This Session

1. [task 1 — result]
2. [task 2 — result]
...

## What Remains To Be Done

1. [pending task — priority] [dependency if any]
2. ...

## Critical Decisions (Do Not Change Without A Reason)

- [decision 1]: [reason]
- [decision 2]: [reason]

## Applied Fixes (Do Not Revert)

- [file]: [fix] — [reason]

## Important Paths

- [path 1]: [purpose]
- [path 2]: [purpose]

## Alerts

- [any trap, edge case, or special care]

## Where To Recover More Information

- Snapshot: C:\Users\renat\skills\context-guardian\data\snapshot-[timestamp].md
- MEMORY.md: loaded automatically
- Context-agent: `python context_manager.py load`
- Historical search: `python context_manager.py search "term"`
```

## Fast Protocol (When Time Is Short)

If compaction is imminent and there's no time for the full 4-phase protocol:

1. **30 seconds** — Write a mini-briefing with: pending tasks, critical
   decisions, paths of modified files
2. **1 minute** — Update MEMORY.md with P0 information
3. **2 minutes** — Run context-agent save

Even the fast protocol is better than no protection.

## Post-Compaction Completeness Check

When a session continues after compaction, verify that the preserved context
is complete:

1. Read MEMORY.md (it will already be loaded automatically)
2. If available, read the most recent snapshot in `data/`
3. Compare with the transition briefing (if visible in the compacted context)
4. If you find gaps, run:
   ```bash
   python C:\Users\renat\skills\context-agent\scripts\context_manager.py load
   ```
5. If gaps remain, search by term:
   ```bash
   python C:\Users\renat\skills\context-agent\scripts\context_manager.py search "term"
   ```

## Real-World Usage Example

**Scenario**: A long session creating advogado-especialista (46KB), fixing match_skills
(5 new categories), auditing security (10 vulnerabilities), generating 22 ZIPs.

**Without context-guardian**:
Compaction summarizes everything into "created a legal skill, fixed bugs, generated zips".
The next Claude doesn't know which categories were added, which vulnerabilities
were fixed, the state of each ZIP, or why certain decisions were made.
Result: rework, inconsistencies, regressions.

**With context-guardian**:
Before compaction, it runs the full protocol:
- Snapshot with the 5 new categories listed (legal, auction, security, image-generation, monitoring)
- 10 vulnerabilities cataloged with file, type, and exact fix
- 22 ZIPs verified with checksums
- Decisions documented ("removed 'health' from monitoring because it caused a false positive")
- Transition briefing at the top of the context
The next Claude continues with full precision, zero rework.

## Performance Considerations

- The full protocol takes 2-5 minutes of Claude's work
- For simple projects, use only the fast protocol
- Don't activate it for short sessions or casual conversations
- Persistence across 3 layers (snapshot + MEMORY.md + context-agent) ensures that
  even if one layer fails, the other two preserve the information
- Old snapshots (>10) can be pruned manually

## Best Practices

- Provide clear, specific context about your project and requirements
- Review all suggestions before applying them to production code
- Combine with other complementary skills for comprehensive analysis

## Common Pitfalls

- Using this skill for tasks outside its domain expertise
- Applying recommendations without understanding your specific context
- Not providing enough project context for accurate analysis

## Related Skills

- `context-agent` - Complementary skill for enhanced analysis