map-workflow

OCR Map Workflow

Complete 6-phase process for generating a Code Review Map.

> **CRITICAL**: You MUST call `ocr state advance` **BEFORE starting work** on each phase. Transition the `current_phase` and `phase_number` immediately when entering a new phase.

> **PREREQUISITE**: The `ocr` CLI must be installed (`npm install -g @open-code-review/cli`) or accessible via `npx`. Every phase transition calls `ocr state advance`, which requires the CLI.

---

Overview

The Code Review Map is a **human-facing navigation tool** for large, complex changesets. It uses multi-agent orchestration to analyze changes and produce a structured document that helps humans:

• Understand the overall approach and intent
• Navigate changes in logical order
• Track review progress with checkboxes
• See how changes map to requirements (if provided)

**Primary audience**: Humans (the last line of defense on code changes)

**When to use**: Extremely large changesets that would take multiple hours for human review.

---

Phase 0: Session State Verification

Before starting ANY work, verify the current session state.

Step 1: Check for existing session

# Get current branch and sanitize for filesystem (replace / with -)
BRANCH_RAW=$(git branch --show-current)
BRANCH=$(echo "$BRANCH_RAW" | tr '/' '-')
DATE=$(date +%Y-%m-%d)
SESSION_DIR=".ocr/sessions/${DATE}-${BRANCH}"

ls -la "$SESSION_DIR" 2>/dev/null

Step 2: If `--fresh` flag provided

Delete existing map artifacts and start fresh:

rm -rf "$SESSION_DIR/map"
mkdir -p "$SESSION_DIR/map/runs/run-1"

Step 3: Map Run Resolution

Determine which map run to use (parallel to review rounds):

MAP_DIR="$SESSION_DIR/map/runs"

if [ ! -d "$MAP_DIR" ]; then
  CURRENT_RUN=1
  mkdir -p "$MAP_DIR/run-1"
else
  HIGHEST=$(ls -1 "$MAP_DIR" | grep -E '^run-[0-9]+$' | sed 's/run-//' | sort -n | tail -1)
  HIGHEST=${HIGHEST:-0}

  if [ -f "$MAP_DIR/run-$HIGHEST/map.md" ]; then
    CURRENT_RUN=$((HIGHEST + 1))
    mkdir -p "$MAP_DIR/run-$CURRENT_RUN"
  else
    CURRENT_RUN=$HIGHEST
  fi
fi

Step 4: Initialize session state for map workflow

**CRITICAL**: Before proceeding, you MUST initialize the session in SQLite using `ocr state` commands.

If this is a **new session** (no prior review or map in this session):

ocr state begin \
  --session-id "$SESSION_ID" \
  --branch "$BRANCH" \
  --workflow-type map \
  --session-dir "$SESSION_DIR"

Then transition to the first map phase:

ocr state advance \
  --phase "map-context" \
  \
  --current-map-run $CURRENT_RUN

If this is an **existing session** (e.g., a map after a prior review), the session already exists in SQLite — just call `ocr state advance` to switch to the map workflow:

ocr state advance \
  --phase "map-context" \
  \
  --current-map-run $CURRENT_RUN

The CLI commands handle timestamp management automatically — `map_started_at` is set when transitioning to a map phase, ensuring `ocr progress` shows accurate elapsed time even if the session had a prior review workflow.

Step 5: Report to user

Session: {session_id}
Map run: {current_run}
Current phase: {current_phase}
Action: [Starting fresh | Resuming from Phase X]

---

State Tracking

At **every phase transition**, call `ocr state advance` with the `--current-map-run` flag:

ocr state advance \
  --phase "flow-analysis" \
  \
  --current-map-run $CURRENT_RUN

This updates the session in SQLite and logs an orchestration event.

**Map phase values**: `map-context`, `topology`, `flow-analysis`, `requirements-mapping`, `synthesis`, `complete`

---

Phase 1: Context Discovery (Shared with Review)

**Goal**: Build context from config + discovered files + user requirements.

**State**: Call `ocr state advance --phase "map-context" --current-map-run $CURRENT_RUN`

This phase is **identical** to the review workflow's context discovery. See `references/context-discovery.md` for the complete algorithm.

Steps

1. **Load OCR Configuration** — Read `.ocr/config.yaml` 2. **Pull OpenSpec Context** — If enabled, read specs and active changes 3. **Discover Reference Files** — AGENTS.md, CLAUDE.md, etc. 4. **Gather Requirements** — If user provided specs/proposals/tickets 5. **Merge Into discovered-standards.md**

Map-Specific: Load Redundancy Config

Read `code-review-map` section from `.ocr/config.yaml`:

code-review-map:
  agents:
    flow_analysts: 2         # Range: 1-10, default: 2
    requirements_mappers: 2  # Range: 1-10, default: 2

**Parsing Logic**: 1. Read `.ocr/config.yaml` 2. Extract `code-review-map.agents.flow_analysts` → store as `FLOW_ANALYST_COUNT` 3. Extract `code-review-map.agents.requirements_mappers` → store as `REQ_MAPPER_COUNT` 4. If section is missing or commented out, use defaults: `FLOW_ANALYST_COUNT=2`, `REQ_MAPPER_COUNT=2` 5. Clamp values to range 1-10

**Use these values** when spawning agents in Phase 3 and Phase 4.

Phase 1 Checkpoint

• [ ] `discovered-standards.md` written (or reused from existing session)
• [ ] If requirements provided: `requirements.md` written
• [ ] Agent redundancy config loaded
• [ ] `ocr state advance` called with `--phase "map-context"`

---

Phase 2: Topology Analysis (Map Architect)

**Goal**: Enumerate changed files and identify logical structure.

**State**: Call `ocr state advance --phase "topology" --current-map-run $CURRENT_RUN`

Steps

1. **Get the changeset** (determine target from user request):

| Target | Command | |--------|---------| | Staged changes (default) | `git diff --cached --name-only` | | Unstaged changes | `git diff --name-only` | | Specific commit | `git diff {commit}^ {commit} --name-only` | | Commit range | `git diff {from}..{to} --name-only` | | Branch vs main | `git diff main...{branch} --name-only` | | PR (via gh CLI) | `gh pr diff {number} --name-only` |

   # Default: staged changes
   git diff --cached --name-only