feat: Add review_pr standard job with expert-driven PR review

- Add new review_pr job with 3 steps: check_relevance, deep_review, improve_and_rereview
- Use inline bash completion $(gh pr diff) for efficient token usage in expert prompts
- Experts focus only on their domain expertise for specialized feedback
- Iterative improvement cycles until all experts approve or 3 max iterations
- Add learnings: domain focus in expert prompts, efficiency improvements
- Code cleanup: remove redundant try/except and unused context variables
- Include PR review output files from workflow execution

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: nhorton

.deepwork/experts/experts/learnings/expert_prompts_must_emphasize_domain_focus.md

@@ -0,0 +1,42 @@
+---
+name: Expert prompts must emphasize domain focus
+last_updated: 2026-02-01
+summarized_result: |
+  When invoking experts for tasks like PR review, prompts must explicitly tell
+  experts to ONLY comment on their domain and not provide generic feedback.
+  Without this, experts provide overlapping generic reviews instead of unique
+  specialized perspectives.
+---
+
+## Context
+
+During a PR review using the `/review_pr` job, both the `deepwork-jobs` and `experts` experts were invoked to review changes to the experts system implementation. The expectation was that each expert would bring their unique domain knowledge to identify issues that generalist reviewers might miss.
+
+## Problem
+
+Both experts provided similar generic code review feedback. They identified the same issues (redundant exception handling, unused variables) rather than focusing on aspects specific to their domains:
+
+- The `deepwork-jobs` expert should have focused on how the experts system integrates with jobs, skill generation patterns, and hook systems
+- The `experts` expert should have focused on expert.yml schema design, topic/learning structure, and evolution strategies
+
+Instead, both provided overlapping feedback on general code quality issues.
+
+## Resolution
+
+Updated the expert prompts in the `review_pr` job steps to explicitly emphasize domain focus:
+
+```
+IMPORTANT: Only comment on aspects that fall within your area of expertise.
+Do not provide general code review feedback on things outside your domain -
+other experts will cover those areas. Use your specialized knowledge to
+identify issues that a generalist reviewer might miss.
+```
+
+Also added:
+- "Your domain: [brief description from discovery_description]" to remind experts of their focus
+- Request for feedback "from your expert perspective" throughout the prompt
+- Quality criteria including "Feedback is focused on each expert's specific domain of expertise"
+
+## Key Takeaway
+
+When designing job steps that invoke experts, the prompt must explicitly constrain experts to their domain. Without this, experts default to providing generic assistance rather than specialized insight. The value of the experts system comes from each expert contributing unique perspective - overlapping generic reviews wastes the multi-expert approach.

.deepwork/experts/experts/learnings/review_pr_efficiency_improvements.md

@@ -0,0 +1,74 @@
+---
+name: Review PR job efficiency improvements
+last_updated: 2026-02-01
+summarized_result: |
+  The review_pr job used excessive tokens by sending full file contents to all
+  experts instead of using the per-expert file segmentation from the relevance
+  step. Also, quality validation sub-agents add overhead that may not be needed
+  for simple checklist verification.
+---
+
+## Context
+
+During execution of the `/review_pr` job on PR #192, the workflow completed successfully but used significantly more tokens and time than necessary.
+
+## Problems Identified
+
+### 1. Ignored per-expert file segmentation
+
+The `check_relevance` step correctly identified which files each expert should review:
+- deepwork-jobs: schema, parser, generator, CLI, templates, tests
+- experts: same files (significant overlap in this case)
+
+But the `deep_review` step ignored this segmentation and sent ALL files to BOTH experts. Each expert received ~1000+ lines of code when they should have received only their relevant subset.
+
+### 2. Full file contents vs. targeted excerpts
+
+Experts received full file contents when often they only needed:
+- The diff (what changed)
+- Specific sections relevant to their domain
+- Perhaps function signatures for context
+
+Sending full test files (500+ lines) to review production code changes is wasteful.
+
+### 3. Quality validation sub-agent overhead
+
+Each step spawned a Haiku sub-agent purely to verify a checklist of 3-5 criteria. This adds:
+- Network round-trip latency
+- Token overhead for the sub-agent context
+- Complexity
+
+For simple boolean criteria checks, the main agent could self-verify.
+
+### 4. Redundant data fetching
+
+The PR diff was fetched separately in both `check_relevance` and `deep_review` steps instead of being passed along or cached.
+
+## Recommendations
+
+### For step instructions:
+
+1. **Use inline bash completion `$(command)`**: Instead of the orchestrating agent reading
+   data and passing it to sub-agents, embed commands directly in prompts:
+   ```
+   $(gh pr diff)
+   $(gh pr diff --name-only)
+   ```
+   This executes when the sub-agent spawns, avoiding token overhead in the main conversation.
+
+2. **Use relevance segmentation**: The deep_review step should explicitly use the "Relevant files" list from each expert's relevance assessment to scope what content is sent to each expert.
+
+3. **Prefer diffs over full files**: For review tasks, send the diff plus minimal context (function signatures, class definitions) rather than entire files.
+
+4. **Skip validation sub-agents for simple criteria**: If quality criteria are simple boolean checks (e.g., "output file exists", "all experts invoked"), the main agent can verify these directly.
+
+### For job design:
+
+1. **Let sub-agents fetch their own data**: Using `$(command)` in prompts means sub-agents
+   get fresh data directly without the orchestrator reading and forwarding it.
+
+2. **Consider expert-specific prompts**: Generate different prompts for each expert containing only their relevant files, rather than one massive prompt for all.
+
+## Key Takeaway
+
+The experts system's value comes from specialized, focused review. Sending all content to all experts defeats this purpose and wastes tokens. Job steps that invoke multiple experts should segment the workload based on each expert's declared relevance.

CHANGELOG.md

@@ -8,6 +8,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
+- New `review_pr` standard job for expert-driven PR review
+  - Three-step workflow: check_relevance, deep_review, improve_and_rereview
+  - Uses inline bash completion `$(gh pr diff)` for efficient token usage
+  - Experts focus only on their domain of expertise for specialized feedback
+  - Iterative improvement cycles until all experts approve or max 3 iterations
 - Concurrent steps support in workflow definitions
   - Workflows can now specify nested arrays of step IDs to indicate steps that can run in parallel
   - Example: `steps: [setup, [task_a, task_b, task_c], finalize]` runs task_a/b/c concurrently

pr_review/deepwork-jobs/review.md

@@ -0,0 +1,149 @@
+# deepwork-jobs Expert Review
+
+**PR**: #192 - feat: Add experts system for auto-improving domain knowledge
+**Date**: 2026-02-01
+**Reviewer**: deepwork-jobs expert
+
+## Summary
+
+The experts system is a well-designed addition to DeepWork that follows established patterns from the jobs system. The architecture cleanly separates concerns across schema definition (`expert_schema.py`), parsing (`experts_parser.py`), generation (`experts_generator.py`), and CLI (`experts.py`). The use of dynamic command embedding (`$(deepwork topics ...)`) in the generated agent template is an elegant solution for keeping expert agents up-to-date without regenerating them.
+
+From a DeepWork Jobs perspective, this integration is solid. The experts system complements jobs by providing domain knowledge that can be leveraged during job execution. The sync command properly handles both jobs and experts, and the naming conventions (`dwe_` prefix for expert agents) avoid conflicts with job-generated skills.
+
+## Issues Found
+
+### Issue 1
+- **File**: `src/deepwork/schemas/expert_schema.py`
+- **Line(s)**: 22, 50, 75
+- **Severity**: Minor
+- **Issue**: The `additionalProperties: False` constraint on all three schemas is strict and may cause friction when evolving the schema. For example, if users want to add custom metadata fields to topics or learnings (like `author`, `tags`, or `priority`), they would get validation errors.
+- **Suggestion**: Consider whether this strictness is intentional. If extensibility is desired, either remove `additionalProperties: False` or document clearly that custom fields are not supported. The jobs schema (`JOB_SCHEMA`) also uses `additionalProperties: False`, so this is consistent with existing patterns.
+
+### Issue 2
+- **File**: `src/deepwork/core/experts_parser.py`
+- **Line(s)**: 377-379, 387-389
+- **Severity**: Minor
+- **Issue**: The exception handling for topic/learning parsing re-raises `ExpertParseError` with a bare `raise`. This works but loses context about which file caused the error. The error message is already set in `parse_topic_file`/`parse_learning_file`, but the pattern is unusual.
+- **Suggestion**: Consider either removing the try/except entirely (letting errors propagate naturally) or adding file context to the error message.
+
+### Issue 3
+- **File**: `src/deepwork/core/experts_generator.py`
+- **Line(s)**: 77-78
+- **Severity**: Suggestion
+- **Issue**: The `_build_expert_context` method includes `topics_count` and `learnings_count` but these are not used in the template (`agent-expert.md.jinja`). This is dead code that could confuse future maintainers.
+- **Suggestion**: Either remove these unused context variables or add them to the template if there is a future use case (e.g., showing counts in agent description).
+
+### Issue 4
+- **File**: `src/deepwork/templates/claude/agent-expert.md.jinja`
+- **Line(s)**: 14
+- **Severity**: Minor
+- **Issue**: The `truncate(200)` filter is applied after `replace('\n', ' ')`, which means the 200-character limit includes any spaces that replaced newlines. A multiline description might get truncated unexpectedly short if it has many newlines.
+- **Suggestion**: This is likely acceptable behavior, but consider if `truncate(200, killwords=False, end='...')` would be better for cleaner truncation at word boundaries.
+
+### Issue 5
+- **File**: `src/deepwork/cli/sync.py`
+- **Line(s)**: (expert agent generation section)
+- **Severity**: Minor
+- **Issue**: Expert agent generation is hardcoded to only run for Claude (`adapter.name == "claude"`). The comment says "agents live in .claude/agents/" but this should be abstracted through the adapter if/when other platforms support agents.
+- **Suggestion**: Consider adding an `adapter.supports_agents` property or similar abstraction so this check is not a string comparison. However, this is acceptable for now given Claude is the only platform with agent support.
+
+### Issue 6
+- **File**: `src/deepwork/core/experts_parser.py`
+- **Line(s)**: 61
+- **Severity**: Minor
+- **Issue**: The frontmatter regex pattern allows optional trailing content after the closing `---` on the same line, but then requires the closing `---` to be at the start of a line. This could cause parsing issues with edge cases.
+- **Suggestion**: The current pattern works correctly for well-formed files. Consider adding a test case for edge cases like trailing whitespace after the closing `---`.
+
+### Issue 7
+- **File**: `src/deepwork/standard/experts/deepwork_jobs/expert.yml`
+- **Line(s)**: 151
+- **Severity**: Suggestion
+- **Issue**: The expert documentation mentions "Claude Code currently only supports script hooks. Prompt hooks are parsed but not executed (documented limitation)." This is valuable but might become stale if prompt hooks are implemented.
+- **Suggestion**: The learning file `prompt_hooks_not_executed.md` already exists in learnings/ which is the right approach. Consider referencing it or adding a note about checking current platform capabilities.
+
+## Code Suggestions
+
+### Suggestion 1: Remove unused context variables
+
+**File**: `src/deepwork/core/experts_generator.py`
+
+Before:
+```python
+def _build_expert_context(self, expert: ExpertDefinition) -> dict:
+    return {
+        "expert_name": expert.name,
+        "discovery_description": expert.discovery_description,
+        "full_expertise": expert.full_expertise,
+        "topics_count": len(expert.topics),
+        "learnings_count": len(expert.learnings),
+    }
+```
+
+After:
+```python
+def _build_expert_context(self, expert: ExpertDefinition) -> dict:
+    return {
+        "expert_name": expert.name,
+        "discovery_description": expert.discovery_description,
+        "full_expertise": expert.full_expertise,
+    }
+```
+
+### Suggestion 2: Simplify redundant exception handling
+
+**File**: `src/deepwork/core/experts_parser.py`
+
+Before:
+```python
+for topic_file in topics_dir.glob("*.md"):
+    try:
+        topic = parse_topic_file(topic_file)
+        topics.append(topic)
+    except ExpertParseError:
+        raise
+```
+
+After:
+```python
+for topic_file in topics_dir.glob("*.md"):
+    topic = parse_topic_file(topic_file)
+    topics.append(topic)
+```
+
+The try/except here adds no value since it just re-raises. The `parse_topic_file` function already includes the filename in its error messages.
+
+### Suggestion 3: Add platform abstraction for agent support
+
+**File**: `src/deepwork/core/adapters.py` (add property to `AgentAdapter` base class):
+
+```python
+@property
+def supports_agents(self) -> bool:
+    """Whether this platform supports expert agents."""
+    return False
+
+# In ClaudeAdapter:
+@property
+def supports_agents(self) -> bool:
+    return True
+```
+
+Then in `sync.py`:
+```python
+if experts and adapter.supports_agents:
+```
+
+## Approval Status
+
+**APPROVED**: No blocking issues
+
+The experts system is well-implemented and follows DeepWork's established patterns. The issues identified are minor improvements that do not block merging. The system correctly:
+
+1. Defines clear schemas for expert, topic, and learning validation
+2. Parses expert definitions including nested topics and learnings
+3. Generates agent files with dynamic command embedding for up-to-date content
+4. Integrates with the sync command to generate expert agents alongside job skills
+5. Provides CLI commands (`deepwork topics`, `deepwork learnings`) for dynamic content retrieval
+6. Has comprehensive test coverage across unit and integration tests
+
+The architecture cleanly separates the experts system from jobs while allowing them to coexist and complement each other.