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:

1. Architecture constraints from anchors

   • File size limits?
   • Required patterns?
   • Validation rules?

2. Current state from code search

   • Where is the relevant code?
   • What are the dependencies?
   • Are there existing tests?

3. 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:

• <!-- anchor: validation-rules --> - Describes the concept
• <!-- anchor: F012-refactor-plan --> - References feature ID
• <!-- anchor: state-management --> - Clear, searchable
• <!-- anchor: 300-line-enforcement --> - References constraint

Bad anchor names:

• <!-- anchor: important --> - Too vague
• <!-- anchor: app-stuff --> - Not searchable
• <!-- anchor: temp-notes --> - Implies temporary
• <!-- anchor: section-3 --> - 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