Context Map Generation

Purpose

Create a high-level, token-efficient overview of the system (.agent/map.md) to allow reasoning about the whole project without reading every file.

Confidence-Based Staleness Thresholds

Map freshness requirements scale with confidence level:

Staleness Check

When invoked (or before low confidence work):

📍 CONTEXT MAP STALENESS CHECK

Map file: .agent/map.md
Last updated: {date} ({N} days ago)
Confidence level: {confidence}
Max age for confidence: {threshold}

{If stale:}
⚠️ Context map is STALE for {confidence} confidence work.

For LOW confidence, understanding the codebase is critical.
Refreshing map before proceeding...

{If fresh:}
✅ Context map is current ({N} days old, threshold: {threshold} days)

Low Confidence Refresh Requirements

For LOW confidence work:

1. Check map age — if > 24 hours, refresh is MANDATORY
2. Check for recent changes — git diff since last map update
3. Partial refresh option — focus on affected areas if full refresh is expensive

🔄 LOW CONFIDENCE CONTEXT MAP REFRESH

Affected areas for {ISSUE-ID}:
- src/services/ (target of changes)
- src/models/ (dependencies)
- tests/services/ (test coverage)

Refresh options:
1. Full refresh (entire codebase)
2. Partial refresh (affected areas only)
3. Skip (NOT RECOMMENDED for low confidence)

Proceeding with partial refresh...

Procedure

1. Scan the file structure (limit to 2-3 levels of depth).
2. Identify key architectural elements:
   • Critical configuration files (package.json, pyproject.toml, docker-compose, etc.)
   • Entry points (main.py, index.js, App.tsx)
   • Core modules and their responsibilities.
3. Summarize architecture patterns and data flow.
4. Write/Update .agent/map.md with the following structure:
   • System Overview: One paragraph summary of purpose and stack.
   • Key Components: List of major modules/folders and what they do.
   • Patterns: Architectural decisions (e.g., MVC, Repository pattern, Event-driven).
   • Key Files: Table of critical files and their specific role.
   • Last Updated: Timestamp for staleness tracking.
5. Constraint: Keep the file concise (target < 150 lines). It is a map, not a territory.

Map Header Template

Include this header in map.md for staleness tracking:

# Context Map

**Generated**: {YYYY-MM-DD HH:MM}
**Scope**: {full | partial: areas}
**Confidence**: {confidence level that triggered refresh}

---