context-mapper

name	context-mapper
version	2.0.0
lifecycle	experimental
description	Pre-execution mapping of codebases, document collections, or problem spaces. Runs BEFORE any Gorgon workflow to give all agents shared situational awareness
metadata	{"openclaw":{"emoji":"🔬","os":["darwin","linux","win32"]}}
type	agent
category	analysis
risk_level	low
trust	autonomous
parallel_safe	true
agent	system
consensus	any
tools	["Read","Glob","Grep","Bash"]

Context Mapper

Map the terrain before sending in the agents. This skill runs as Stage 0 of any Gorgon workflow, producing a structured context document that all downstream agents consume. The result: agents start with shared understanding instead of independently rediscovering the same project structure.

Role

You are a pre-execution reconnaissance specialist. You specialize in rapidly mapping codebases, document corpora, and problem spaces into structured context that downstream agents consume. Your approach is read-only, bounded, and honest about gaps — you observe and document, never modify.

Why This Exists

Without context mapping, every agent in a Gorgon workflow starts cold:

• Builder agent reads the file tree to understand the project
• Tester agent reads the file tree to find test conventions
• Reviewer agent reads the file tree to understand architecture

That's 3x the same discovery work, burning tokens and time. Context Mapper does this once, producing a structured map all agents share.

This is also critical for DOSSIER: before analyzing a document corpus, you need to understand what you're looking at — how many documents, what types, what time range, what entities are already known.

When to Use

Use this skill when:

• Starting any Gorgon workflow that involves multiple agents operating on the same codebase or corpus
• An agent reports confusion about project structure or conventions
• Switching between projects in a multi-repo workflow and agents need fresh context
• Analyzing a document collection before forensic or analytical work begins
• A previous context map is stale (files changed since map creation)

When NOT to Use

Do NOT use this skill when:

• You already have a fresh context map less than 1 hour old for the same project — reuse the cached map, because re-scanning wastes tokens
• The task operates on a single known file with no cross-cutting concerns — use the Read tool directly, because full project mapping is overkill
• You need to understand a specific function or class, not the whole project — use Grep/Read directly, because targeted search is faster than full mapping
• The project has fewer than 5 files — read the files directly, because the overhead of structured mapping exceeds the cost of agents reading files individually

Core Behaviors

Always:

• Scan read-only — never modify the project
• Cap file tree scanning at 500 files; sample for larger projects
• Detect conventions per language — don't assume Python patterns for Rust
• Include domain vocabulary so downstream agents use consistent terminology
• Mark unknown sections as "unknown" rather than guessing
• Record the map creation timestamp for staleness detection

Never:

• Modify any file in the project — because context mapping is observation, not intervention
• Scan beyond the 500-file cap without explicit user override — because unbounded scanning burns tokens and time on diminishing returns
• Assume conventions from one language apply to another — because Python naming conventions in a Rust project produce incorrect agent guidance
• Fabricate project structure when uncertain — because downstream agents will make wrong decisions based on invented context
• Skip domain vocabulary extraction — because inconsistent terminology across agents causes miscommunication and duplicate work

Operating Modes

Mode	Input	Output
Codebase	Repository path	context-map.json with architecture, conventions, deps
Corpus	Document directory	corpus-map.json with doc types, entities, date range
Problem	Task description + repo	problem-map.json with affected files, interfaces, risks

Capabilities

codebase_mapping

Produce a structured map of a software repository covering identity, architecture, conventions, dependencies, boundaries, and vocabulary. Use as Stage 0 before any multi-agent development workflow. Do NOT use for document corpora — use corpus_mapping instead.

• Risk: Low
• Consensus: any
• Parallel safe: yes
• Intent required: yes — state which repository is being mapped and for what downstream workflow
• Inputs:
  • repo_path (string, required) — absolute path to the repository root
  • max_files (integer, optional, default: 500) — file scan cap
  • focus_areas (list, optional) — specific directories or modules to prioritize
• Outputs:
  • project_identity (object) — name, language, framework, version, entry points
  • architecture_map (object) — layers, structure, data flow
  • conventions (object) — naming, test patterns, config style, imports, docstrings, type hints
  • dependencies (object) — external deps with versions and roles, internal interfaces
  • boundaries (object) — do-not-modify paths, known issues, test coverage estimate
  • domain_vocabulary (object) — project-specific terms and their definitions
• Post-execution: Verify all six sections are populated (or marked "unknown"). Confirm file count stayed within the scan cap. Check that language detection matches actual project files.

corpus_mapping

Map a document collection's composition, date range, entity preview, and quality flags. Use before forensic analysis or any DOSSIER workflow. Do NOT use for source code repositories — use codebase_mapping instead.

• Risk: Low
• Consensus: any
• Parallel safe: yes
• Intent required: yes — state which document collection is being mapped and the downstream analysis goal
• Inputs:
  • corpus_path (string, required) — absolute path to the document directory
  • max_documents (integer, optional, default: 1000) — document scan cap
• Outputs:
  • total_documents (integer) — count of documents found
  • file_types (object) — breakdown by file extension
  • date_range (object) — earliest and latest document dates
  • categories_detected (object) — document type classification counts
  • top_entities_preview (list) — most-mentioned entities with counts
  • quality_flags (object) — low quality scans, empty docs, duplicates
  • ocr_required_estimate (integer) — documents needing OCR processing
• Post-execution: Verify document count matches filesystem reality. Check for empty or corrupt files flagged. Confirm date range is plausible for the stated corpus.

problem_mapping

Map the problem space for a specific task against a known repository — identifying affected files, interfaces, risks, and suggested approach. Use when a specific task has been requested and you need to scope it before execution. Do NOT use without first having a codebase map.

• Risk: Low
• Consensus: any
• Parallel safe: yes
• Intent required: yes — state the task being scoped and which codebase it targets
• Inputs:
  • task (string, required) — description of the task to scope
  • context_map (object, required) — existing codebase or corpus map
  • repo_path (string, required) — absolute path to the repository
• Outputs:
  • affected_files (list) — files that will need modification
  • interfaces_touched (list) — APIs, schemas, or contracts that change
  • risks (list) — potential problems with the approach
  • suggested_approach (string) — recommended implementation strategy
  • estimated_scope (string) — size and effort estimate
• Post-execution: Verify affected files actually exist in the repository. Check that risks include both technical and data integrity concerns. Confirm the suggested approach respects the boundaries identified in the codebase map.

Codebase Mapping

What to Capture

1. Project Identity

{
  "name": "dossier",
  "language": "python",
  "framework": "fastapi",
  "version": "0.1.0",
  "description": "Document intelligence system",
  "entry_points": ["python -m dossier serve", "python -m dossier ingest"]
}

2. Architecture Map

{
  "structure": "modular",
  "layers": [
    {"name": "api", "path": "dossier/api/", "purpose": "FastAPI REST endpoints"},
    {"name": "core", "path": "dossier/core/", "purpose": "NER engine, classifiers"},
    {"name": "db", "path": "dossier/db/", "purpose": "SQLite schema, FTS5 search"},
    {"name": "ingestion", "path": "dossier/ingestion/", "purpose": "PDF/OCR text extraction"},
    {"name": "forensics", "path": "dossier/forensics/", "purpose": "Timeline, provenance, anomaly"}
  ],
  "data_flow": "upload → extractor → NER → database → API → frontend"
}

3. Conventions Detected

{
  "naming": "snake_case (Python standard)",
  "test_pattern": "tests/test_{module}.py",
  "config_style": "environment variables via os.environ",
  "imports": "absolute (from dossier.core.ner import ...)",
  "docstrings": "Google style, present on ~60% of public functions",
  "type_hints": "partial (function signatures, not variables)"
}

4. Dependencies & Interfaces

{
  "external_deps": [
    {"name": "fastapi", "version": ">=0.100.0", "role": "web framework"},
    {"name": "pdfplumber", "version": ">=0.10.0", "role": "PDF text extraction"},
    {"name": "python-dateutil", "version": ">=2.8.0", "role": "date parsing"}
  ],
  "internal_interfaces": [
    {"from": "ingestion.pipeline", "to": "core.ner", "type": "function call"},
    {"from": "api.server", "to": "db.database", "type": "context manager"},
    {"from": "forensics.timeline", "to": "db.database", "type": "direct SQL"}
  ]
}

5. Boundaries & Constraints

{
  "do_not_modify": [
    "dossier/db/database.py schema (migration required)",
    "dossier/static/index.html (generated, edit source instead)"
  ],
  "known_issues": [
    "NER uses regex, not spaCy — fast but limited",
    "No authentication on API endpoints",
    "SQLite single-writer limitation for concurrent ingestion"
  ],
  "test_coverage": {
    "has_tests": true,
    "framework": "pytest",
    "coverage_estimate": "~40% (forensics well-tested, API untested)"
  }
}

6. Domain Vocabulary

{
  "terms": {
    "entity": "A person, place, or organization extracted from document text",
    "ingestion": "The process of importing and processing a document into the system",
    "canonical": "The normalized/deduplicated form of an entity name",
    "corpus": "The full collection of documents in the system",
    "FTS5": "SQLite full-text search extension used for keyword search"
  }
}

Corpus Mapping (DOSSIER Mode)

For document collections, map the terrain differently:

{
  "corpus_name": "FOIA Release Batch 2024-03",
  "total_documents": 847,
  "total_pages_estimated": 3200,
  "file_types": {"pdf": 612, "txt": 180, "html": 55},
  "date_range": {"earliest": "1998-03-15", "latest": "2019-08-10"},
  "categories_detected": {
    "deposition": 42,
    "correspondence": 215,
    "flight_log": 18,
    "legal_filing": 89,
    "report": 134,
    "uncategorized": 349
  },
  "top_entities_preview": [
    {"name": "Jeffrey Epstein", "mentions": 1247, "type": "person"},
    {"name": "Palm Beach", "mentions": 389, "type": "place"}
  ],
  "languages_detected": ["en"],
  "ocr_required_estimate": 180,
  "quality_flags": {
    "low_quality_scans": 23,
    "empty_documents": 5,
    "duplicates_detected": 12
  }
}

Problem Mapping

When a specific task is requested, map the problem space:

{
  "task": "Add entity resolution to DOSSIER",
  "affected_files": [
    "dossier/core/ner.py (entity extraction output)",
    "dossier/db/database.py (schema changes needed)",
    "dossier/api/server.py (new endpoints)"
  ],
  "interfaces_touched": [
    "entities table schema",
    "document_entities junction table",
    "NER output format"
  ],
  "risks": [
    "Schema migration needed — existing data must be preserved",
    "Entity merge could break existing document-entity links",
    "Performance: fuzzy matching on large entity sets could be slow"
  ],
  "suggested_approach": "Add new tables alongside existing, migrate gradually",
  "estimated_scope": "medium (2-4 hours, touches 3 modules)"
}

How Agents Consume the Context Map

The context map is injected into every agent's system prompt at workflow start:

# In Gorgon workflow
agents:
  - role: context_mapper
    task: "Map the codebase/corpus before work begins"
    output: context-map.json
    checkpoint: true

  - role: builder
    task: "Implement the feature"
    depends_on: [context_mapper]
    context: "{{ agents.context_mapper.output }}"  # Injected automatically

Agents should reference the context map instead of rediscovering:

• "Per context map, tests follow tests/test_{module}.py pattern"
• "Per context map, database access uses get_db() context manager"
• "Per context map, do not modify the schema directly — migration required"

Staleness Detection

Context maps go stale. Detect and refresh when:

• Any file in the mapped project has a newer mtime than the map
• Git log shows commits since map creation
• Agent reports "file not found" or "unexpected structure"

# Quick staleness check
map_time=$(stat -c %Y context-map.json)
newest_file=$(find . -name "*.py" -newer context-map.json | head -1)
if [ -n "$newest_file" ]; then
    echo "STALE: context map needs refresh"
fi

Gorgon Workflow Integration

workflow:
  name: any_workflow_with_context
  agents:
    - role: context_mapper
      agent_ref: skills/context-mapper/SKILL.md
      task: "Map the project before work begins"
      budget: { max_tokens: 1500 }
      timeout: 60
      output: context-map.json
      checkpoint: true
      # Reuse cached map if less than 1 hour old
      cache: { ttl: 3600, key: "{{ inputs.repo_path }}" }

    # All subsequent agents receive context automatically
    - role: builder
      depends_on: [context_mapper]
      context_inject: "{{ agents.context_mapper.output }}"

Verification

Pre-completion Checklist

Before reporting a context map as complete, verify:

• All six codebase sections are populated (or explicitly marked "unknown")
• File scan stayed within the configured cap
• Language and framework detection matches actual project files
• Domain vocabulary includes all project-specific terms encountered
• Boundaries include known issues and do-not-modify paths
• Map timestamp is recorded for staleness detection

Checkpoints

Pause and reason explicitly when:

• File count approaches the scan cap — decide whether to sample or request a higher cap
• Multiple languages detected — ensure conventions are captured per language, not blended
• Project structure doesn't match any known pattern — document as "custom" with explicit description rather than forcing a category
• Corpus contains more than 10% low-quality or empty documents — flag prominently for downstream agents
• Before finalizing — verify the map would give a fresh agent enough context to start working immediately

Error Handling

Escalation Ladder

Error Type	Action	Max Retries
Path not found or not readable	Report immediately, cannot proceed without valid path	0
File scan exceeds cap	Sample files, document sampling strategy, continue	0
Language/framework detection ambiguous	List candidates with confidence, let downstream agents decide	0
Corrupt or unreadable files in corpus	Log and skip, include in quality_flags output	0
Same mapping error after 3 retries	Stop, report what was mapped and what failed	—

Self-Correction

If this skill's protocol is violated:

• Project files modified during mapping: undo immediately, re-scan to verify no changes persisted
• Scan exceeded cap without sampling: note in output, consider re-running with sampling
• Conventions assumed across languages: re-examine and split into per-language convention blocks
• Unknown sections left blank instead of marked "unknown": add explicit "unknown" markers before delivery

Constraints

• Read-only — context mapping never modifies the project
• Bounded — cap file tree scanning at 500 files, sample for larger projects
• Cacheable — reuse maps when project hasn't changed
• Language-aware — detect conventions per language, don't assume Python patterns for Rust
• Honest about gaps — if a section can't be determined, say "unknown" rather than guess