@open-code-review/agents 1.3.1 → 1.5.0

package/skills/ocr/references/map-workflow.md

@@ -0,0 +1,717 @@
+# OCR Map Workflow
+
+Complete 6-phase process for generating a Code Review Map.
+
+> **CRITICAL**: You MUST call `ocr state transition` **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 transition`, 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
+
+```bash
+# 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:
+```bash
+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):
+
+```bash
+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):
+```bash
+ocr state init \
+  --session-id "$SESSION_ID" \
+  --branch "$BRANCH" \
+  --workflow-type map \
+  --session-dir "$SESSION_DIR"
+```
+
+Then transition to the first map phase:
+```bash
+ocr state transition \
+  --phase "map-context" \
+  --phase-number 1 \
+  --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 transition` to switch to the map workflow:
+```bash
+ocr state transition \
+  --phase "map-context" \
+  --phase-number 1 \
+  --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 transition` with the `--current-map-run` flag:
+
+```bash
+ocr state transition \
+  --phase "flow-analysis" \
+  --phase-number 3 \
+  --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 transition --phase "map-context" --phase-number 1 --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`:
+
+```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 transition` called with `--phase "map-context"`
+
+---
+
+## Phase 2: Topology Analysis (Map Architect)
+
+**Goal**: Enumerate changed files and identify logical structure.
+
+**State**: Call `ocr state transition --phase "topology" --phase-number 2 --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` |
+
+   ```bash
+   # Default: staged changes
+   git diff --cached --name-only
+
+   # Store canonical file list for completeness validation
+   git diff --cached --name-only > /tmp/ocr-canonical-files.txt
+   ```
+
+   **CRITICAL**: Store this canonical file list. It's used for completeness validation in Phase 5.
+
+2. **Categorize each file**:
+   - Entry points (routes, handlers, CLI, UI components)
+   - Core logic (business logic, services, domain)
+   - Infrastructure (config, utilities, shared)
+   - Tests
+   - Documentation
+
+3. **Identify logical sections**:
+   - Group by feature boundary
+   - Group by architectural layer
+   - Group by execution flow
+   - Group by concern (security, performance)
+
+4. **Determine review order** within sections:
+   - Entry points first
+   - Core implementations next
+   - Supporting files
+   - Tests last
+
+5. **Save topology to session**:
+   ```
+   .ocr/sessions/{id}/map/runs/run-{n}/topology.md
+   ```
+
+### Phase 2 Checkpoint
+
+- [ ] All changed files enumerated
+- [ ] Files categorized by type
+- [ ] Logical sections identified
+- [ ] `topology.md` written
+- [ ] `ocr state transition` called with `--phase "topology"`
+
+---
+
+## Phase 3: Flow Tracing (Flow Analysts)
+
+**Goal**: Trace upstream/downstream dependencies for each changed file.
+
+**State**: Call `ocr state transition --phase "flow-analysis" --phase-number 3 --current-map-run $CURRENT_RUN`
+
+### Steps
+
+1. **Spawn Flow Analysts** — spawn `FLOW_ANALYST_COUNT` agents (from config, default: 2)
+
+2. **Assign files** to each analyst (can overlap for coverage)
+
+3. **Each analyst traces**:
+   - Upstream: What calls this code?
+   - Downstream: What does this code call?
+   - Related: Tests, config, siblings
+
+4. **Collect findings** from all analysts
+
+5. **Aggregate with redundancy validation**:
+   - Findings from multiple analysts = high confidence
+   - Unique findings = lower confidence but still valid
+
+6. **Save flow analysis**:
+   ```
+   .ocr/sessions/{id}/map/runs/run-{n}/flow-analysis.md
+   ```
+
+### Spawning Flow Analysts
+
+For each analyst, provide:
+- Their persona (`references/map-personas/flow-analyst.md`)
+- Discovered standards
+- Assigned files to trace
+- Instructions to explore freely
+
+See `references/map-personas/flow-analyst.md` for persona details.
+
+### Phase 3 Checkpoint
+
+- [ ] Flow Analysts spawned (`FLOW_ANALYST_COUNT` from config)
+- [ ] All changed files have flow context
+- [ ] Findings aggregated
+- [ ] `flow-analysis.md` written
+- [ ] `ocr state transition` called with `--phase "flow-analysis"`
+
+---
+
+## Phase 4: Requirements Mapping (If Provided)
+
+**Goal**: Map changes to requirements and identify coverage.
+
+**State**: Call `ocr state transition --phase "requirements-mapping" --phase-number 4 --current-map-run $CURRENT_RUN`
+
+**Skip this phase** if no requirements were provided.
+
+### Steps
+
+1. **Spawn Requirements Mappers** — spawn `REQ_MAPPER_COUNT` agents (from config, default: 2)
+
+2. **Provide context**:
+   - Requirements from `requirements.md`
+   - Changed files and their purposes (from topology)
+   - Flow context (from Phase 3)
+
+3. **Each mapper**:
+   - Parses requirements into discrete items
+   - Maps each change to relevant requirements
+   - Identifies coverage status (full/partial/none)
+   - Notes gaps and deviations
+
+4. **Aggregate findings**:
+   - Consistent mappings = high confidence
+   - Divergent mappings = flag for human review
+
+5. **Save requirements mapping**:
+   ```
+   .ocr/sessions/{id}/map/runs/run-{n}/requirements-mapping.md
+   ```
+
+### Phase 4 Checkpoint
+
+- [ ] Requirements Mappers spawned (if requirements exist)
+- [ ] Coverage matrix created
+- [ ] Gaps identified
+- [ ] `requirements-mapping.md` written
+- [ ] `ocr state transition` called with `--phase "requirements-mapping"`
+
+---
+
+## Phase 5: Map Synthesis (Map Architect)
+
+**Goal**: Combine all findings into the final Code Review Map optimized for reviewer workflow.
+
+**State**: Call `ocr state transition --phase "synthesis" --phase-number 5 --current-map-run $CURRENT_RUN`
+
+### Template Structure (in order)
+
+1. **Executive Summary** — Context first
+2. **Questions & Clarifications** — Ambiguities to resolve with author
+3. **Requirements Coverage** — Coverage matrix (if requirements provided)
+4. **Critical Review Focus** — High-value areas for human judgment
+5. **Manual Verification** — Tests to run before/during review
+6. **File Review** — Per-section file tracking (main tracking area)
+7. **Section Dependencies** — Cross-section dependency graph data
+8. **File Index** — Alphabetical reference
+9. **Map Metadata** — Run info
+
+### Steps
+
+1. **Load all artifacts**:
+   - `topology.md` — Section structure
+   - `flow-analysis.md` — Dependency context
+   - `requirements-mapping.md` — Coverage annotations (if exists)
+
+2. **Construct Executive Summary**:
+   - 1-2 paragraph narrative hypothesis
+   - Key approaches observed
+   - Frame as hypothesis, not assertion
+
+3. **Gather Questions & Clarifications**:
+   - Extract ambiguities from requirements mapping
+   - List assumptions made during mapping
+   - Include questions about deferred work or unclear intent
+
+4. **Build Requirements Coverage** (if requirements provided):
+   - Coverage matrix with status indicators
+   - Note any gaps
+
+5. **Generate Critical Review Focus**:
+   - Identify areas where human judgment adds value
+   - Focus on: business logic, security, edge cases, architectural decisions
+   - Map each to requirement or concern
+   - Do NOT perform code review — just flag areas for attention
+
+6. **Generate Manual Verification**:
+   - **Critical Path**: Happy-path tests from requirements
+   - **Edge Cases & Error Handling**: From implementation analysis
+   - **Non-Functional**: Performance, security checks
+   - Omit only if changeset is purely docs/config
+
+7. **Build File Review sections**:
+   For each section from topology:
+   - Narrative hypothesis (1-2 sentences)
+   - File table with `Done` column (empty, reviewer marks `X`)
+   - Flow summary
+   - Requirements coverage
+   - **Review Suggestions** (only if key things to watch for):
+     - Specific areas mapped to requirements/concerns
+     - Do NOT do code review — just flag for reviewer attention
+
+8. **Generate Section Dependencies**:
+   - Review flow analysis cross-file flows to identify section-to-section call chains
+   - For each pair of sections with meaningful dependencies, add a table row
+   - Direction: caller section → callee section
+   - Relationship should be a 3-8 word description (e.g., "Auth middleware protects routes")
+   - If sections are independent, leave the table body empty (headers only)
+
+9. **Create File Index**:
+   - Alphabetical list of ALL changed files
+   - Section reference for each
+
+10. **Validate completeness**:
+   ```bash
+   EXPECTED=$(git diff --cached --name-only | wc -l)
+   MAPPED=$(grep -oE '\| `[^`]+` \|' map.md | wc -l)
+   [ "$EXPECTED" -ne "$MAPPED" ] && echo "ERROR: Missing files!"
+   ```
+
+11. **Save final map**:
+    ```
+    .ocr/sessions/{id}/map/runs/run-{n}/map.md
+    ```
+
+### Map Output Format
+
+See `references/map-template.md` for the complete template.
+
+### Phase 5 Checkpoint
+
+- [ ] Executive Summary with hypothesis
+- [ ] Questions & Clarifications populated
+- [ ] Requirements Coverage matrix (if applicable)
+- [ ] Critical Review Focus areas identified
+- [ ] Manual Verification tests generated (or omitted if docs-only)
+- [ ] All File Review sections with file tables
+- [ ] Review Suggestions per section (only where key things to flag)
+- [ ] Section Dependencies table generated
+- [ ] File Index complete
+- [ ] Completeness validated (all files appear in tables)
+- [ ] `map.md` written
+- [ ] `ocr state transition` called with `--phase "synthesis"`
+
+---
+
+## Phase 6: Present
+
+**Goal**: Display the map to the user.
+
+**State**: Call `ocr state transition --phase "complete" --phase-number 6 --current-map-run $CURRENT_RUN` after presenting.
+
+### Steps
+
+1. **Read the final map**:
+   ```bash
+   cat .ocr/sessions/{id}/map/runs/run-{n}/map.md
+   ```
+
+2. **Present to user** with summary:
+   ```
+   Code Review Map Generated
+
+   Session: {session_id}
+   Files mapped: {count}
+   Sections: {section_count}
+
+   The map is saved at: .ocr/sessions/{id}/map/runs/run-{n}/map.md
+
+   [Display map content]
+   ```
+
+3. **Update state**:
+   ```bash
+   ocr state transition \
+     --phase "complete" \
+     --phase-number 6 \
+     --current-map-run $CURRENT_RUN
+   ```
+
+   > **Note**: Map completion does NOT close the session — the session stays `active` so further reviews or maps can be run.
+
+### Phase 6 Checkpoint
+
+- [ ] Map presented to user
+- [ ] `ocr state transition` called with `--phase "complete"`
+
+---
+
+## Artifact Summary
+
+| Phase | Artifact Created |
+|-------|------------------|
+| 1 | `discovered-standards.md`, `requirements.md` (if provided) |
+| 2 | `map/runs/run-{n}/topology.md` |
+| 3 | `map/runs/run-{n}/flow-analysis.md` |
+| 4 | `map/runs/run-{n}/requirements-mapping.md` (if requirements) |
+| 5 | `map/runs/run-{n}/map.md` |
+| 6 | (presentation only) |
+
+---
+
+## Intermediate Artifact Templates
+
+### topology.md Format
+
+```markdown
+# Topology Analysis
+
+**Generated**: {timestamp}
+**Files**: {count} changed files
+
+## Canonical File List
+
+```
+{complete list from git diff --name-only}
+```
+
+## File Categorization
+
+### Entry Points
+| File | Type | Description |
+|------|------|-------------|
+| `api/auth.ts` | API Route | Authentication endpoints |
+| `cli/index.ts` | CLI Command | Main CLI entry |
+
+### Core Logic
+| File | Type | Description |
+|------|------|-------------|
+| `services/auth.service.ts` | Service | Auth business logic |
+
+### Infrastructure
+| File | Type | Description |
+|------|------|-------------|
+| `utils/helpers.ts` | Utility | Shared helpers |
+
+### Tests
+| File | Coverage For |
+|------|--------------|
+| `tests/auth.test.ts` | `services/auth.service.ts` |
+
+### Documentation
+| File | Description |
+|------|-------------|
+| `README.md` | Project readme |
+
+## Proposed Sections
+
+### Section 1: {Name}
+- **Purpose**: {what this section covers}
+- **Files**: `file1.ts`, `file2.ts`, `file3.ts`
+- **Entry Point**: `file1.ts`
+- **Review Order**: file1 -> file2 -> file3
+
+### Section 2: {Name}
+...
+
+## Unrelated Files
+
+Files that don't fit into logical sections:
+- `misc/cleanup.ts` — Opportunistic refactor, unrelated to main changes
+```
+
+### flow-analysis.md Format
+
+```markdown
+# Flow Analysis
+
+**Generated**: {timestamp}
+**Analysts**: {count} (redundancy: {n}x)
+
+## Aggregated Findings
+
+### File: `path/to/file1.ts`
+
+**Confidence**: High (found by 2/2 analysts)
+
+#### Upstream
+| Caller | Location | Context |
+|--------|----------|---------|
+| `handleRequest()` | `api/routes.ts:42` | API entry point |
+
+#### Downstream
+| Callee | Location | Context |
+|--------|----------|---------|
+| `validateToken()` | `auth/validator.ts:15` | Token validation |
+
+#### Related Files
+- `tests/file1.test.ts` — Unit tests
+- `config/auth.yaml` — Configuration
+
+#### Section Assignment
+**Proposed**: Section 1 (Authentication Flow)
+**Rationale**: Entry point for auth, calls auth services
+
+---
+
+### File: `path/to/file2.ts`
+...
+
+## Cross-File Flows
+
+### Flow 1: Authentication Request
+```
+api/auth.ts -> services/auth.service.ts -> utils/token.ts -> db/users.ts
+```
+
+### Flow 2: ...
+
+## Analyst Agreement
+
+| File | Analyst 1 Section | Analyst 2 Section | Final |
+|------|-------------------|-------------------|-------|
+| `file1.ts` | Auth Flow | Auth Flow | Auth Flow |
+| `file2.ts` | Auth Flow | API Layer | Auth Flow (majority) |
+```
+
+### requirements-mapping.md Format
+
+```markdown
+# Requirements Mapping
+
+**Generated**: {timestamp}
+**Mappers**: {count} (redundancy: {n}x)
+
+## Requirements Parsed
+
+| ID | Requirement | Source |
+|----|-------------|--------|
+| REQ-1 | User can log in via OAuth | spec.md:15 |
+| REQ-2 | Sessions expire after 24h | spec.md:22 |
+| REQ-3 | Failed logins are rate-limited | spec.md:28 |
+
+## Coverage Matrix
+
+| Requirement | Status | Files | Confidence |
+|-------------|--------|-------|------------|
+| REQ-1 | Full | `auth.ts`, `oauth.ts` | High (2/2) |
+| REQ-2 | Partial | `session.ts` | Medium (1/2) |
+| REQ-3 | None | — | High (2/2) |
+
+## Per-Section Coverage
+
+### Section 1: Authentication Flow
+- REQ-1: Full
+- REQ-2: Partial (missing cleanup)
+
+### Section 2: API Endpoints
+- REQ-3: Not addressed
+
+## Gaps
+
+### Unaddressed Requirements
+- **REQ-3**: Rate limiting not found in changeset
+
+### Partial Coverage Details
+- **REQ-2**: Session creation exists, but no expiry logic found
+
+## Mapper Agreement
+
+| Requirement | Mapper 1 | Mapper 2 | Final |
+|-------------|----------|----------|-------|
+| REQ-1 | Full | Full | Full |
+| REQ-2 | Partial | None | Partial (conservative) |
+```
+
+---
+
+## Aggregation Logic
+
+When multiple agents produce findings, aggregate as follows:
+
+### Flow Analyst Aggregation
+
+1. **Collect** all flow analyses from all analysts
+2. **Group** by file path
+3. **Merge** upstream/downstream findings:
+   - Union of all unique callers/callees
+   - If same relationship found by multiple analysts = **High confidence**
+   - If found by only one analyst = **Medium confidence** (still include)
+4. **Resolve** section assignments:
+   - If all analysts agree → use that section
+   - If disagreement → use majority, note dissent
+   - If no majority → Map Architect decides
+
+### Requirements Mapper Aggregation
+
+1. **Collect** all mappings from all mappers
+2. **Compare** coverage assessments per requirement:
+   - If all agree → use that status
+   - If disagree → use **most conservative** (None < Partial < Full)
+   - Note disagreements for human review
+3. **Merge** file-to-requirement mappings (union)
+4. **Compile** unified gaps list
+
+### Confidence Scoring
+
+| Agreement | Confidence |
+|-----------|------------|
+| All agents agree | High |
+| Majority agrees | Medium |
+| No agreement | Low (flag for review) |
+
+---
+
+## Error Handling
+
+### Incomplete Changeset
+
+If `git diff` returns empty:
+```
+WARNING: No changes detected. Please stage changes or specify a target.
+```
+
+### Missing Config
+
+If `.ocr/config.yaml` doesn't exist:
+```
+WARNING: OCR not configured. Run `ocr doctor` to check setup.
+```
+
+### Completeness Failure
+
+If map doesn't include all files:
+```
+ERROR: Map incomplete: {missing_count} files not mapped.
+Missing: [list files]
+
+Re-running synthesis to include missing files...
+```