session-files

Session File Manifest

> **This is the authoritative reference for session file naming.** All other documentation should reference this file for file names and structure.

Session Directory Structure

Every OCR session creates files in `.ocr/sessions/{session-id}/`:

.ocr/sessions/{YYYY-MM-DD}-{branch}/
├── discovered-standards.md # Merged project context (shared across rounds)
├── requirements.md         # User-provided requirements (if any, shared)
├── context.md              # Phase 2+3: Change summary + Tech Lead guidance (shared)
├── map/                    # Code Review Map artifacts (optional)
│   └── runs/
│       ├── run-1/          # First map generation
│       │   ├── topology.md         # File categorization and sections
│       │   ├── flow-analysis.md    # Dependency tracing results
│       │   ├── requirements-mapping.md  # Coverage matrix (if requirements)
│       │   ├── map-meta.json       # Structured map data (written by CLI via complete-map --stdin)
│       │   └── map.md              # Final map output (presentation artifact)
│       └── run-2/          # Subsequent runs (created on re-map)
│           └── ...         # Same structure as run-1
└── rounds/                 # All round-specific artifacts
    ├── round-1/            # First review round
    │   ├── reviews/        # Individual reviewer outputs
    │   │   ├── principal-1.md
    │   │   ├── principal-2.md
    │   │   ├── quality-1.md
    │   │   ├── quality-2.md
    │   │   ├── security-1.md   # (if security reviewer assigned)
    │   │   ├── testing-1.md    # (if testing reviewer assigned)
    │   │   ├── ephemeral-1.md  # (if --reviewer flag used)
    │   │   └── {type}-{n}.md   # (additional assigned custom reviewers)
    │   ├── discourse.md    # Cross-reviewer discussion for round 1
    │   ├── round-meta.json # Structured review data (written by CLI via complete-round --stdin)
    │   └── final.md        # Synthesized final review for round 1
    └── round-2/            # Subsequent rounds (created on re-review)
        ├── reviews/
        │   └── ...         # Same structure as round-1
        ├── discourse.md
        ├── round-meta.json
        └── final.md

Review Rounds

OCR uses a **round-first architecture** where all round-specific artifacts live under `rounds/round-{n}/`. This makes multi-round reviews a first-class concept.

**Round behavior**:

• First `/ocr-review` creates `rounds/round-1/` with `reviews/`, `discourse.md`, `final.md`
• Subsequent `/ocr-review` on same day/branch creates `rounds/round-{n+1}/`
• Previous rounds are preserved (never overwritten)
• Each round has its own `discourse.md` and `final.md`
• SQLite tracks `current_round` via `ocr state show`; round metadata derived from filesystem

**Shared vs per-round/run artifacts**: | Shared (session root) | Per-round (`rounds/round-{n}/`) | Per-run (`map/runs/run-{n}/`) | |----------------------|--------------------------------|-------------------------------| | `discovered-standards.md` | `reviews/*.md` | `topology.md` | | `requirements.md` | `discourse.md` | `flow-analysis.md` | | `context.md` | `final.md` | `requirements-mapping.md` | | | | `map.md` |

**When to use multiple rounds**:

• Author addresses feedback and requests re-review
• Scope changes mid-review
• Different reviewer team composition needed

Map Runs

OCR uses a **run-based architecture** for maps, parallel to review rounds.

**Run behavior**:

• First `/ocr-map` creates `map/runs/run-1/` with map artifacts
• Subsequent `/ocr-map` on same day/branch creates `map/runs/run-{n+1}/`
• Previous runs are preserved (never overwritten)
• Each run produces a complete `map.md`
• SQLite tracks `current_map_run` via `ocr state show`; run metadata derived from filesystem

**Map artifacts per run**: | File | Phase | Description | |------|-------|-------------| | `topology.md` | 2 | File categorization and section groupings | | `flow-analysis.md` | 3 | Upstream/downstream dependency tracing | | `requirements-mapping.md` | 4 | Requirements coverage matrix (if requirements provided) | | `map-meta.json` | 5 | Structured map data (written by CLI via `complete-map --stdin`) | | `map.md` | 5 | Final synthesized Code Review Map (presentation artifact) |

**When to use multiple runs**:

• Changeset has evolved since last map
• Different requirements context needed
• Fresh analysis desired after code updates

File Specifications

Required Files

| File | Phase | Description | Used By | |------|-------|-------------|---------| | `discovered-standards.md` | 1 | Merged project context from config + references | All reviewers | | `context.md` | 2 | Change summary, diff analysis, Tech Lead guidance | All reviewers | | `rounds/round-{n}/reviews/{type}-{n}.md` | 4 | Individual reviewer outputs | Discourse, Synthesis | | `rounds/round-{n}/discourse.md` | 6 | Cross-reviewer discussion results | Synthesis | | `rounds/round-{n}/round-meta.json` | 7 | Structured review data (written by CLI via `complete-round --stdin`) | Dashboard | | `rounds/round-{n}/final.md` | 7 | Synthesized final review | Show, Post commands |

Optional Files

| File | When Created | Description | |------|--------------|-------------| | `requirements.md` | Phase 1 | User-provided requirements, specs, or acceptance criteria |

Reviewer File Naming

**Pattern**: `{type}-{n}.md`

• `{type}`: One of `principal`, `quality`, `security`, `testing`, `ephemeral`, or custom reviewer name
• `{n}`: Sequential number starting at 1

**Examples** (for round 1):

rounds/round-1/reviews/principal-1.md
rounds/round-1/reviews/principal-2.md
rounds/round-1/reviews/quality-1.md
rounds/round-1/reviews/quality-2.md
rounds/round-1/reviews/security-1.md
rounds/round-1/reviews/testing-1.md
rounds/round-1/reviews/performance-1.md   # Custom reviewer
rounds/round-1/reviews/ephemeral-1.md     # Ephemeral reviewer (from --reviewer)
rounds/round-1/reviews/ephemeral-2.md     # Ephemeral reviewer (from --reviewer)