Anchor-Based Context Recovery Skill

Anchor-Based Context Recovery

When to Use

ALWAYS use when:

Starting work on a feature/bug after context compaction
Switching between different features in same session
User says "work on feature X" or "fix bug Y"
About to modify code you haven't read in current context

DO NOT use when:

You just read the relevant files in current conversation
Working on trivial changes (<10 lines)
User is asking general questions, not requesting implementation

The Problem

After context compaction or in new sessions:

Claude loses track of what files were already modified
Must re-read 500+ line files to understand architecture
Forgets critical constraints and validation rules
Wastes context re-learning project structure

The Solution: Searchable Anchors

Projects embed HTML comment anchors in their documentation:

<!-- anchor: validation-rules -->
## Validation Architecture
- Foreign language: Warning only
- AP Calculus: Hard block
- Located: App.jsx:229-474

<!-- anchor: state-management -->
## Core State Structure
- courses array: Primary schedule data
- Located: App.jsx:285-290

Key principle: Anchors survive file splits and refactoring. Code locations change, but anchor names remain stable.

Phase 1: Discover Relevant Anchors

Step 1: Search for anchor documentation

# Find all anchor files
find docs/ -name "*anchor*" -o -name "architecture.md" -o -name "context-map.md" 2>/dev/null

# Or search all docs for anchors
grep -r "<!-- anchor:" docs/ 2>/dev/null | head -20

Step 2: Search for task-specific anchors

If working on feature F012:

grep -r "anchor:.*F012" docs/ 2>/dev/null
grep -r "anchor:.*refactor" docs/ 2>/dev/null

If working on validation bug:

grep -r "anchor:.*validation" docs/ 2>/dev/null
grep -r "anchor:.*rules" docs/ 2>/dev/null

Step 3: List all available anchors

grep -r "<!-- anchor:" docs/ 2>/dev/null | sed 's/.*anchor: //' | sed 's/ -->.*//' | sort -u

Phase 2: Collect Context

Step 1: Read anchor sections ONLY

Do NOT read entire files. Use grep with context:

# Read validation anchor + 20 lines after
grep -A 20 "<!-- anchor: validation-rules -->" docs/architecture/core.md

# Or read multiple related anchors
grep -A 15 "<!-- anchor: state-management -->" docs/architecture/core.md
grep -A 15 "<!-- anchor: credit-calculation -->" docs/architecture/core.md

Step 2: Find related code locations

Anchors should reference exact file locations. Extract them:

<!-- anchor: validation-rules -->
Located: App.jsx:229-474
Related: SchedulingEngine.js:150-200

Then use Read tool with those specific line ranges, or use Grep to find the relevant sections.

Step 3: Search for related patterns

Based on anchor info, search for related code:

# If anchor mentions "validation rules", find all validators
grep -r "validate.*course" src/ --include="*.js"

# Find related hooks
grep -r "use.*Validation" src/hooks/

Phase 3: Verify Understanding

Before making changes, verify:

Architecture constraints from anchors
- File size limits?
- Required patterns?
- Validation rules?
Current state from code search
- Where is the relevant code?
- What are the dependencies?
- Are there existing tests?
Related components from anchor links
- What else might be affected?
- Are there anchor references to related features?

Phase 4: Document Your Changes (Optional)

When adding new patterns, suggest anchor additions:

If you extract validation logic to a new file:

<!-- anchor: course-validator -->
## Course Validator Module
- Extracted from: App.jsx:229-474 (Nov 2024)
- Located: src/domain/validators/courseValidator.js
- Used by: App.jsx, SchedulingEngine.js
- Related: validation-rules anchor (original pattern)

When modifying existing patterns, note anchor updates needed:

Suggest updating the anchor documentation when you make significant changes to referenced code.

Anchor Naming Conventions

Good anchor names:

 - Describes the concept
 - References feature ID
 - Clear, searchable
 - References constraint

Bad anchor names:

 - Too vague
 - Not searchable
 - Implies temporary
 - Meaningless number

Expected Workflow Example

# User says: "Fix the foreign language validation bug"

# Phase 1: Find anchors
grep -r "anchor:.*validation" docs/
# Result: <!-- anchor: validation-rules --> in docs/architecture/core.md

# Phase 2: Collect context
grep -A 30 "<!-- anchor: validation-rules -->" docs/architecture/core.md
# Reads: Validation rules are in App.jsx:229-474

# Use Grep to find the exact code
grep -n "foreign.*language" src/App.jsx

# Phase 3: Verify understanding
# - Rule: Foreign language validation is WARNING only (from anchor)
# - Location: App.jsx:229-293 (from anchor)
# - Current behavior: Need to check implementation

# Phase 4: Make the fix with full context
# - Know where the code is
# - Know the expected pattern
# - Know related constraints from anchors

Benefits

Compared to re-reading full files:

940-line file → 50 lines of anchor context (95% reduction)
Survives refactoring (anchors update when files split)
Searchable by concept, not by file path
Works across sessions and compaction

Compared to manual summarization:

Consistent structure across features
Easy to update when code changes
Machine-readable (grep-able)
No information loss from summarization

Common Anchor Patterns

Pattern 1: Feature Development

<!-- anchor: F012-refactor-plan -->
## Feature F012: Extract Validation Logic
- Status: in_progress
- Files to modify: App.jsx (reduce 940→300 lines)
- Extract to: src/domain/validators/
- Tests: tests/validators/
- Related: validation-rules, 300-line-enforcement anchors

Pattern 2: Bug Fixes

<!-- anchor: bug-foreign-language-validation -->
## Bug: Foreign Language Prerequisites Not Checking
- Reported: 2024-11-27
- Expected: Warning when skipping levels
- Actual: No warning shown
- Root cause: TBD
- Related: validation-rules anchor

Pattern 3: Architecture Constraints

<!-- anchor: 300-line-rule -->
## Architecture Constraint: File Size Limit
- Hard limit: 300 lines per file
- Enforcement: .github/workflows/architecture-check.yml
- Current violations: App.jsx (940 lines)
- Refactor priority: HIGH
- Related: F012-refactor-plan

Checklist

Before claiming you've used this skill:

[ ] Searched for relevant anchors (grep -r "anchor:.*keyword" docs/)
[ ] Read ONLY anchor sections (not full files)
[ ] Found code locations from anchor references
[ ] Searched for related patterns in codebase
[ ] Verified architecture constraints from anchors
[ ] Ready to implement without re-reading full context

Anti-Patterns to Avoid

DON'T:

Read entire files when anchors exist
Assume anchor content from previous sessions
Skip anchor search because "I remember this"
Create anchors for trivial code (<20 lines)
Use anchors as TODO lists (use feature roadmap instead)

DO:

Search for anchors at start of EVERY task
Reference exact file locations in anchors
Link related anchors together
Keep anchor descriptions concise (20-50 lines)
Update anchor docs when making significant changes

Agent Skills: Anchor-Based Context Recovery

Install this agent skill to your local

Skill Files