OCR: Map

Usage

/ocr-map [target] [--fresh] [--requirements <path>]

Arguments

• target (optional): Branch, commit, or file to map. Defaults to staged changes.
• --fresh (optional): Clear any existing map for today's session and start from scratch.
• --requirements (optional): Path to requirements document (spec, proposal, ticket).

Examples

/ocr-map                           # Map staged changes
/ocr-map --fresh                   # Clear existing map and regenerate
/ocr-map HEAD~5                    # Map last 5 commits
/ocr-map feature/big-refactor      # Map branch vs main
/ocr-map --requirements spec.md    # Map with requirements context

When to Use

The map command is for extremely large changesets that would take multiple hours for a human to review. It produces a structured navigation document with:

• Section-based grouping of related changes
• Checkboxes for tracking review progress
• Flow context (upstream/downstream dependencies)
• Requirements coverage (if requirements provided)

For most changesets, /ocr-review is sufficient. Use /ocr-map when you need a navigation aid for overwhelming changes.

Steps

1. Run Setup Guard (MANDATORY - validates OCR is properly configured)

• Read and execute .ocr/skills/references/setup-guard.md
• If validation fails → STOP and show error
• If validation passes → continue

1. Session State Check (verify existing session state)
2. Load the OCR skill from .ocr/skills/SKILL.md
3. Execute the 6-phase map workflow defined in .ocr/skills/references/map-workflow.md
4. Store results in .ocr/sessions/{date}-{branch}/map/runs/run-{n}/

Session State Check (Phase 0)

Before starting any map work, verify the current session state:

Step 1: Check for existing session

# Find today's session directory
ls -la .ocr/sessions/$(date +%Y-%m-%d)-* 2>/dev/null

Step 2: Check for existing map runs

# Find existing map runs
ls -la .ocr/sessions/{id}/map/runs/ 2>/dev/null

Step 3: Check current state

ocr state show

Step 4: Determine action

• If --fresh flag: Delete the map directory and start from run-1
• If map exists and complete: Start new run (run-{n+1})
• If map exists but incomplete: Resume from current phase
• If no map exists: Start from run-1

CRITICAL: Required Artifacts (Must Create In Order)

> See references/map-workflow.md for the complete workflow.

You MUST create these files sequentially:

.ocr/sessions/{YYYY-MM-DD}-{branch}/
├── discovered-standards.md # Phase 1: merged project standards (shared)
├── requirements.md         # Phase 1: user requirements (if provided, shared)
└── map/
    └── runs/
        └── run-1/          # Map run (increments on re-map)
            ├── topology.md         # Phase 2: file categorization
            ├── flow-analysis.md    # Phase 3: dependency tracing
            ├── requirements-mapping.md  # Phase 4: coverage (if requirements)
            └── map.md              # Phase 5: final map output

State is managed via ocr state CLI commands (stored in SQLite at .ocr/data/ocr.db).

State Management Commands

Prefer the atomic, invariant-checked verbs (v2.0). finish refuses to close a map whose current run was never finalized.

> v2.0.0 retired ocr state init / transition / round-complete / map-complete / close — use the atomic verbs above. Calling a retired verb exits 2 with a pointer to its replacement.

Checkpoint Rules

1. Before Phase 2 (Topology): discovered-standards.md MUST exist
2. Before Phase 3 (Flow Tracing): topology.md MUST exist
3. Before Phase 4 (Requirements): flow-analysis.md MUST exist
4. Before Phase 5 (Synthesis): All prior artifacts MUST exist
5. NEVER write map.md without completing Phases 1-4

Configuration

The map workflow reads redundancy settings from .ocr/config.yaml:

code-review-map:
  agents:
    flow_analysts: 2         # Default: 2 (range: 1-10)
    requirements_mappers: 2  # Default: 2 (range: 1-10)

If not configured, defaults are used.

Output

The final map.md contains:

• Executive Summary: Narrative hypothesis about changeset intent
• Sections: Logical groupings with checkboxes for each file