Review Chamber

Table of Contents

• Overview
• Room Structure
• Workflow Phases
• Phase 1: Knowledge Detection
• Knowledge Detection Checklist
• Phase 2: Classification
• Phase 3: Capture
• Decision Title
• Decision
• Context (from PR discussion))
• Captured Knowledge
• Connected Concepts
• Phase 4: Integration
• Usage Examples
• Capture After PR Review
• Search Past Decisions
• Surface Relevant Knowledge
• Relevant Review Knowledge
• Integration Points
• With sanctum:pr-review
• With knowledge-intake
• With knowledge-locator
• Evaluation Rubric
• Worth Capturing (Score ≥ 60))
• Skip (Score < 60))
• CLI Reference
• Best Practices

PR Review Chamber Skill

Capture, organize, and retrieve knowledge from PR reviews within project memory palaces.

When To Use

• Capturing PR review knowledge for future reference
• Building review pattern libraries from past reviews

When NOT To Use

• Quick self-reviews of trivial changes
• Automated CI checks that cover the review scope

Overview

The Review Chamber is a dedicated room within each project palace that stores valuable knowledge extracted from PR reviews. It transforms ephemeral PR discussions into persistent, searchable institutional memory.

Room Structure

review-chamber/
├── decisions/      # Architectural choices from PR discussions
├── patterns/       # Recurring issues and their solutions
├── standards/      # Quality bar examples and coding conventions
└── lessons/        # Post-mortems and learnings

Verification: Run the command with --help flag to verify availability.

Workflow Phases

Phase 1: Knowledge Detection

After a PR review completes, evaluate findings for knowledge capture:

## Knowledge Detection Checklist

For each finding from sanctum:pr-review, evaluate:

- [ ] **Novelty**: Is this a new pattern or first occurrence?
- [ ] **Applicability**: Will this affect future PRs in this area?
- [ ] **Durability**: Is this architectural (capture) or tactical (skip)?
- [ ] **Connectivity**: Does it link to existing palace rooms?

Verification: Run the command with --help flag to verify availability.

Phase 2: Classification

Route findings to appropriate subrooms:

Phase 3: Capture

Create structured entry with:

---
source_pr: "#42 - Add authentication"
date: 2025-01-15
participants: [author, reviewer1, reviewer2]
palace_location: review-chamber/decisions
related_rooms: [workshop/auth-patterns, library/security-adr]
tags: [authentication, jwt, security]
---

## Decision Title

### Decision
Chose JWT tokens over server-side sessions.

### Context (from PR discussion)
- Reviewer asked: "Why not use sessions?"
- Author explained: stateless scaling requirements
- Discussion refined: added refresh token rotation

### Captured Knowledge
- **Pattern**: JWT + refresh tokens for stateless auth
- **Tradeoff**: Complexity vs. horizontal scaling
- **Application**: Use for all API authentication

### Connected Concepts
- [[auth-patterns]] - Updated with JWT best practices
- [[security-adr-003]] - Referenced this decision

Verification: Run the command with --help flag to verify availability.

Phase 4: Integration

After capture, update related palace rooms:

1. Add bidirectional links to related entries 2. Update tags in project palace index 3. Notify if this contradicts existing entries

Usage Examples

Capture After PR Review

# Automatic: sanctum:pr-review triggers capture
/pr-review 42
# → Review posted to GitHub
# → Knowledge capture evaluates findings
# → Significant decisions stored in review-chamber

# Manual: Explicitly capture from PR
/review-room capture 42 --room decisions

Verification: Run the command with --help flag to verify availability.

Search Past Decisions

# Find authentication decisions
/review-room search "authentication" --room decisions

# Find patterns in a specific area
/review-room search "error handling" --room patterns --tags api

# List recent entries
/review-room list --limit 10 --room standards

Verification: Run the command with --help flag to verify availability.

Surface Relevant Knowledge

When starting work in a code area:

## Relevant Review Knowledge

Starting work in `auth/` directory...

**Past Decisions:**
- [#42] JWT token decision → decisions/jwt-over-sessions
- [#67] Rate limiting pattern → patterns/api-throttling

**Quality Standards:**
- [#55] Error response format → standards/api-errors

**Known Patterns:**
- [#38] Token refresh edge case → patterns/token-refresh-race

Verification: Run the command with --help flag to verify availability.

Integration Points

With sanctum:pr-review

The review-chamber integrates after Phase 6 (Generate Report):

**Verification:** Run the command with `--help` flag to verify availability.
Phase 6: Generate Report
    ↓
[HOOK] Evaluate findings for knowledge capture
    ↓
    For each significant finding:
    ├── Classify into room type
    ├── Create ReviewEntry
    ├── Add to project palace
    └── Update connections
    ↓
Phase 7: Post to GitHub

Verification: Run the command with --help flag to verify availability.

With knowledge-intake

Uses the same evaluation framework:

With knowledge-locator

Extends search to include review-chamber:

python scripts/palace_manager.py search "authentication" \
  --palace project-name \
  --room review-chamber \
  --type semantic

Verification: Run python --version to verify Python environment.

Evaluation Rubric

Worth Capturing (Score ≥ 60)

• Architectural decisions with documented rationale
• Recurring patterns seen in 2+ PRs
• Security/performance critical findings
• Domain knowledge that explains business logic
• Convention changes that affect future code

Skip (Score < 60)

• One-off tactical fixes
• Style preferences without rationale
• Obvious bugs without pattern
• External dependency issues
• Temporary workarounds

CLI Reference

# Capture knowledge from PR
/review-room capture <pr_number> [--room <room_type>] [--tags <tags>]

# Search review chamber
/review-room search "<query>" [--room <room_type>] [--tags <tags>]

# List entries
/review-room list [--room <room_type>] [--limit N]

# View entry details
/review-room view <entry_id>

# Export for documentation
/review-room export [--format markdown|json] [--room <room_type>]

# Statistics
/review-room stats [--palace <palace_id>]

Verification: Run the command with --help flag to verify availability.

Best Practices

1. Capture decisions immediately - Context is freshest right after review 2. Link related entries - Build the knowledge graph 3. Use consistent tags - Enable cross-project discovery 4. Review periodically - Prune outdated entries 5. Surface proactively - Show relevant knowledge when starting related work

Module Reference

• See modules/capture-workflow.md for detailed capture process
• See modules/evaluation-criteria.md for knowledge worth assessment
• See modules/search-patterns.md for query optimization

Capture Workflow Module

Detailed workflow for capturing PR review knowledge into the review chamber.

Trigger Points

Knowledge capture can be triggered:

1. Automatically: After sanctum:pr-review completes Phase 6 2. Manually: Via /review-room capture command 3. Retroactively: From existing PR review threads

Automatic Capture Flow

graph TD
    A[PR Review Completed] --> B{Has BLOCKING findings?}
    B -->|Yes| C[Evaluate each finding]
    B -->|No| D{Has IN-SCOPE findings?}
    D -->|Yes| C
    D -->|No| E[Skip capture]

    C --> F{Score ≥ 60?}
    F -->|Yes| G[Classify room type]
    F -->|No| E

    G --> H[Create ReviewEntry]
    H --> I[Add to project palace]
    I --> J[Update connections]
    J --> K[Report captured entries]

Finding Evaluation

For each PR finding, compute a capture score:

Novelty Check (25 points max)

def evaluate_novelty(finding, existing_entries):
    """Check if finding represents new knowledge."""

    # Search existing entries for similar content
    similar = search_similar(finding.content, existing_entries)

    if not similar:
        return 25  # Completely novel

    best_match = similar[0]
    if best_match.similarity < 0.5:
        return 20  # Mostly novel
    elif best_match.similarity < 0.8:
        return 10  # Partial overlap - may add context
    else:
        return 0   # Duplicate - skip

Applicability Check (30 points max)

def evaluate_applicability(finding, project_context):
    """Estimate future relevance."""

    score = 0

    # Affects common code paths
    if finding.file in project_context.hot_paths:
        score += 15

    # Relates to core domain
    if finding.category in project_context.core_domains:
        score += 10

    # Has broad applicability
    if len(finding.affected_files) > 3:
        score += 5

    return min(30, score)

Durability Check (20 points max)

def evaluate_durability(finding):
    """Distinguish architectural from tactical."""

    # Architectural indicators
    architectural_keywords = [
        'architecture', 'design', 'pattern', 'convention',
        'security', 'performance', 'scalability', 'api'
    ]

    # Tactical indicators
    tactical_keywords = [
        'typo', 'formatting', 'temporary', 'workaround',
        'quick fix', 'hotfix', 'revert'
    ]

    content_lower = finding.content.lower()

    arch_matches = sum(1 for k in architectural_keywords if k in content_lower)
    tact_matches = sum(1 for k in tactical_keywords if k in content_lower)

    if arch_matches > tact_matches:
        return 20  # Architectural
    elif arch_matches == tact_matches:
        return 10  # Mixed
    else:
        return 0   # Tactical - skip

Connectivity Check (15 points max)

def evaluate_connectivity(finding, palace):
    """Check links to existing knowledge."""

    score = 0

    # Links to existing ADRs
    if finding.references_adr:
        score += 5

    # Links to workshop patterns
    if finding.references_pattern:
        score += 5

    # Would create new connections
    potential_links = find_potential_links(finding, palace)
    if len(potential_links) > 2:
        score += 5

    return score

Authority Check (10 points max)

def evaluate_authority(finding, participants):
    """Weight by reviewer expertise."""

    score = 0

    # Senior reviewer involved
    if any(is_senior(p) for p in participants):
        score += 5

    # Domain expert reviewed
    domain = extract_domain(finding)
    if any(is_domain_expert(p, domain) for p in participants):
        score += 5

    return score

Room Classification Logic

After evaluation, classify into appropriate room:

def classify_finding(finding, score):
    """Determine target room for finding."""

    if score < 60:
        return None  # Don't capture

    severity = finding.severity
    category = finding.category.lower()

    # Decisions: Architectural choices with rationale
    if severity == "BLOCKING" and any(k in category for k in [
        'architecture', 'design', 'security', 'api'
    ]):
        return "decisions"

    # Patterns: Recurring issues or solutions
    if is_recurring(finding) or any(k in category for k in [
        'pattern', 'recurring', 'common', 'best-practice'
    ]):
        return "patterns"

    # Standards: Quality examples
    if any(k in category for k in [
        'quality', 'style', 'convention', 'standard'
    ]):
        return "standards"

    # Lessons: Retrospective insights
    if any(k in category for k in [
        'lesson', 'learning', 'retrospective', 'insight'
    ]):
        return "lessons"

    # Default: High-severity findings as patterns
    if severity == "BLOCKING":
        return "patterns"

    return None

Entry Creation

Create structured entry from finding:

def create_review_entry(finding, pr_info, room_type):
    """Create ReviewEntry from finding."""

    return ReviewEntry(
        source_pr=f"#{pr_info.number} - {pr_info.title}",
        title=finding.title,
        room_type=room_type,
        content={
            "decision": finding.description,
            "context": extract_discussion_context(finding),
            "captured_knowledge": {
                "severity": finding.severity,
                "category": finding.category,
                "file": finding.file,
                "line": finding.line,
                "fix": finding.suggested_fix,
            },
            "connected_concepts": find_related_concepts(finding),
        },
        participants=pr_info.participants,
        related_rooms=find_related_rooms(finding),
        tags=extract_tags(finding),
    )

Post-Capture Actions

After adding entry to palace:

1. Update bidirectional links - Add backlinks from related entries 2. Refresh palace index - Update tags and search index 3. Check for contradictions - Alert if new entry conflicts with existing 4. Generate summary - Report what was captured

def post_capture_actions(entry, palace):
    """Actions after successful capture."""

    # Add backlinks
    for related in entry.related_rooms:
        add_backlink(palace, related, entry.id)

    # Check contradictions
    contradictions = find_contradictions(entry, palace)
    if contradictions:
        alert_contradiction(entry, contradictions)

    # Return summary
    return {
        "entry_id": entry.id,
        "room": f"review-chamber/{entry.room_type}",
        "title": entry.title,
        "tags": entry.tags,
        "related": entry.related_rooms,
    }

Evaluation Criteria Module

Detailed criteria for evaluating whether PR review findings are worth capturing.

Evaluation Framework

Based on memory-palace:knowledge-intake, adapted for PR reviews.

Scoring Summary

Capture Thresholds

Detailed Criteria

1. Novelty (25 points)

Question: Is this knowledge new to the project?

Examples:

## High Novelty (25 points)
- First authentication architecture decision
- New error handling pattern for async code
- Security vulnerability pattern not seen before

## Moderate Novelty (15 points)
- Alternative approach to existing pattern
- Additional context for documented decision
- Edge case for known pattern

## Low/No Novelty (0-5 points)
- Same bug found in different file
- Style preference already in standards
- Known limitation documented elsewhere

2. Applicability (30 points)

Question: Will this affect future development?

Indicators of High Applicability:

## High Applicability Signals
- Affects shared/core code paths
- Relates to API contracts
- Security or performance critical
- Multiple files/components affected
- Frequently modified code area

## Low Applicability Signals
- One-off migration code
- Deprecated feature
- External dependency quirk
- Test-only concern
- Configuration edge case

3. Durability (20 points)

Question: Is this architectural or tactical?

Classification Guide:

## Architectural (20 points)
- Technology choices (JWT vs sessions)
- API design decisions
- Data model structures
- Security architecture
- Performance strategies

## Semi-permanent (15 points)
- Coding conventions
- Error handling patterns
- Testing strategies
- Documentation standards

## Tactical (0-5 points)
- Bug fixes without pattern
- Formatting changes
- Temporary workarounds
- Dependency updates
- Revert commits

4. Connectivity (15 points)

Question: Does this link to other knowledge?

Connection Types:

## Strong Connections (15 points)
- References existing ADR
- Extends documented pattern
- Contradicts (needs resolution!) existing entry
- Builds on prior PR decision

## Moderate Connections (10 points)
- Related to existing topic
- Same code area as prior entries
- Similar category/tags

## Weak/No Connections (0-5 points)
- New domain area
- No related entries exist
- Standalone utility

5. Authority (10 points)

Question: Who provided this knowledge?

Authority Signals:

## High Authority (10 points)
- Code owner reviewed
- Domain expert participated
- Tech lead approved
- Security team involved (for security findings)

## Moderate Authority (5-7 points)
- Experienced team member
- Prior contributor to area
- Cross-team reviewer

## Lower Authority (0-3 points)
- New team member (may still be valid!)
- External contributor
- Bot/automated review

Special Cases

Always Capture

Some findings should always be captured regardless of score:

## Mandatory Capture
- Security vulnerabilities with fix
- Breaking API changes
- Performance regression causes
- Data loss scenarios
- Production incident learnings

Never Capture

Some findings should never be captured:

## Skip Always
- Typo fixes
- Import ordering
- Whitespace changes
- Dependency version bumps (unless significant)
- Auto-formatter changes

Human Override

Allow manual override of scoring:

## Force Capture
/review-room capture 42 --force --room decisions
# Captures even if score < 60

## Force Skip
/review-room capture 42 --skip "duplicate of #38"
# Explicitly skip with reason

Scoring Examples

Example 1: JWT Authentication Decision

Finding:
  title: "Chose JWT over server-side sessions"
  severity: BLOCKING
  category: security/architecture
  context: "Reviewer asked about sessions, author explained scaling needs"

Scoring:
  novelty: 25  # First auth architecture decision
  applicability: 30  # Affects all auth code
  durability: 20  # Architectural choice
  connectivity: 10  # Links to security ADR
  authority: 10  # Tech lead + security reviewer

Total: 95/100 → Capture to decisions/ (Evergreen)

Example 2: Missing Null Check

Finding:
  title: "Add null check before array access"
  severity: IN-SCOPE
  category: bug
  context: "Could cause NPE in edge case"

Scoring:
  novelty: 5   # Common pattern
  applicability: 10  # Specific function
  durability: 5   # Tactical fix
  connectivity: 0   # Isolated
  authority: 5   # Regular reviewer

Total: 25/100 → Skip (tactical fix)

Example 3: Error Response Pattern

Finding:
  title: "Standardize API error response format"
  severity: IN-SCOPE
  category: api/convention
  context: "Third time we've discussed this, let's document"

Scoring:
  novelty: 20  # Formalizing informal convention
  applicability: 25  # All API endpoints
  durability: 15  # Convention, may evolve
  connectivity: 10  # Links to API docs
  authority: 7   # Domain expert

Total: 77/100 → Capture to standards/ (Valuable)

Search Patterns Module

Patterns for searching and retrieving knowledge from the review chamber.

Search Modalities

The review chamber supports multiple search approaches, building on knowledge-locator patterns.

1. Semantic Search

Find entries by meaning, not just keywords.

# Find decisions about authentication
/review-room search "how do we handle user authentication" --type semantic

# Returns entries about JWT, sessions, OAuth even if those exact words not used

Implementation:

def semantic_search(query, entries):
    """Search by meaning using embeddings or keyword expansion."""

    # Expand query with related terms
    expanded = expand_query(query)
    # "authentication" → ["auth", "login", "session", "jwt", "oauth"]

    results = []
    for entry in entries:
        score = compute_semantic_similarity(expanded, entry.content)
        if score > 0.3:  # Threshold
            results.append((entry, score))

    return sorted(results, key=lambda x: x[1], reverse=True)

2. Spatial Search

Navigate by room and location in the palace.

# Browse decisions room
/review-room list --room decisions

# Find entries in patterns room with specific tags
/review-room list --room patterns --tags api,error-handling

Room Navigation:

review-chamber/
├── decisions/     → Architectural choices
│   └── jwt-auth.md
│   └── api-versioning.md
├── patterns/      → Recurring solutions
│   └── retry-logic.md
│   └── error-responses.md
├── standards/     → Quality examples
│   └── code-review-checklist.md
└── lessons/       → Learnings
    └── outage-2025-01.md

3. Temporal Search

Find entries by time or PR timeline.

# Recent entries
/review-room search --since "2025-01-01"

# Entries from specific PR range
/review-room search --pr-range 40-50

# Most accessed entries
/review-room search --sort-by access_count

4. Associative Search

Follow connections between entries.

# Find entries related to specific entry
/review-room related <entry_id>

# Explore connection graph
/review-room graph --start jwt-auth --depth 2

Connection Types:

• related_rooms - Links to other palace rooms
• connected_concepts - Bidirectional concept links
• source_pr - Link back to GitHub PR
• tags - Shared tag connections

5. Contextual Search

Surface relevant entries based on current work context.

# When in auth/ directory
/review-room context auth/

# Returns:
# - Past decisions about authentication
# - Known patterns in this code area
# - Relevant standards to follow

Search Filters

By Room Type

/review-room search "query" --room decisions
/review-room search "query" --room patterns
/review-room search "query" --room standards
/review-room search "query" --room lessons

By Tags

# Single tag
/review-room search "query" --tags security

# Multiple tags (AND)
/review-room search "query" --tags security,api

# Multiple tags (OR)
/review-room search "query" --tags-any security,performance

By Participants

# Entries from reviews by specific person
/review-room search "query" --participant @username

# Entries where specific reviewer participated
/review-room search "query" --reviewer @techleader

By Source PR

# From specific PR
/review-room search --pr 42

# From PR range
/review-room search --pr-range 40-50

By Time

# Since date
/review-room search "query" --since 2025-01-01

# Before date
/review-room search "query" --before 2025-06-01

# Date range
/review-room search "query" --since 2025-01-01 --before 2025-06-01

Proactive Surfacing

Automatically surface relevant knowledge at key moments.

On PR Creation

When creating a PR in a code area with relevant history:

## 📚 Relevant Review Knowledge

Your PR touches files in `auth/`. Here's relevant knowledge:

### Past Decisions
| PR | Decision | Room |
|----|----------|------|
| #42 | JWT over sessions | decisions/jwt-auth |
| #67 | Token refresh pattern | patterns/token-refresh |

### Quality Standards
- API error format: See standards/api-errors
- Auth test coverage: See standards/auth-testing

### Known Patterns
- Token refresh race condition: patterns/token-refresh-race

On Code Review

When reviewing code in area with history:

## 💡 Review Context

This PR modifies authentication code. Consider:

### Prior Decisions
- JWT tokens chosen for stateless scaling (#42)
- Refresh tokens must be rotated (#67)

### Common Issues
- Token validation bypass (seen in #38)
- Missing rate limiting (pattern #12)

On Bug Investigation

When investigating bugs in documented areas:

## 🔍 Related Knowledge

Debugging issue in auth flow. Review chamber has:

### Lessons Learned
- Outage from token expiry misconfiguration (lessons/auth-outage-2025)
- Race condition in refresh (patterns/token-refresh-race)

### Related Decisions
- Why we use JWT: decisions/jwt-auth

Search Result Format

Summary View (Default)

## Search Results: "authentication"

Found 5 entries in review-chamber:

| Room | Title | PR | Date |
|------|-------|-----|------|
| decisions | JWT over sessions | #42 | 2025-01-15 |
| patterns | Token refresh pattern | #67 | 2025-02-20 |
| patterns | Rate limiting | #55 | 2025-01-28 |
| standards | Auth testing | #48 | 2025-01-20 |
| lessons | Token expiry outage | #89 | 2025-03-01 |

Detail View

## Entry: decisions/jwt-auth

**Source PR:** #42 - Add user authentication
**Date:** 2025-01-15
**Participants:** @alice, @bob, @securityteam
**Tags:** authentication, jwt, security, architecture

### Decision
Chose JWT tokens over server-side sessions for stateless scaling.

### Context
- Reviewer asked about session persistence
- Author explained horizontal scaling requirements
- Security team approved with refresh token requirement

### Captured Knowledge
- **Pattern:** JWT + refresh tokens for stateless auth
- **Tradeoff:** Complexity vs. horizontal scaling
- **Application:** All API authentication

### Connected
- [[auth-patterns]] - Workshop patterns
- [[security-adr-003]] - Library ADR
- patterns/token-refresh - Related pattern

CLI Integration

palace_manager.py Extension

# Search review chamber
python scripts/palace_manager.py search "authentication" \
  --palace <project_id> \
  --room review-chamber \
  --subroom decisions \
  --type semantic

# List with filters
python scripts/palace_manager.py list-reviews \
  --palace <project_id> \
  --room patterns \
  --tags api \
  --since 2025-01-01

# Export for documentation
python scripts/palace_manager.py export-reviews \
  --palace <project_id> \
  --format markdown \
  --output docs/review-decisions.md

Performance Considerations

Indexing

# Maintain search indexes
- Tag index: tag → [entry_ids]
- Room index: room → [entry_ids]
- Temporal index: date → [entry_ids]
- Participant index: user → [entry_ids]
- Embedding index: entry_id → vector (optional)

Caching

# Cache frequently accessed entries
- LRU cache for recent searches
- Pre-compute hot entry summaries
- Background index updates

Limits

# Search result limits
MAX_RESULTS = 50  # Per search
MAX_DEPTH = 3     # For graph traversal
TIMEOUT = 5000    # ms for search operations