Domain Review Before Implementation

The Trigger

Use this skill when you're about to:

• Dispatch a Task() for implementation work
• Start coding from a plan or task description
• Send a prompt to a subagent that will write code

The prompt you write IS the brief. If you're about to send an implementation agent a task, that task description needs review first.

Ask yourself: "Am I about to have code written (by me or an agent)?" If yes → domain review first.

Overview

Core principle: Task briefs contain design flaws. Domain experts catch them before implementation, not code reviewers after.

Real-world data: Phase 4A Task 16 (RiverGraph serialization) - "straightforward" brief reviewed by domain expert found 8 issues (3 critical type safety bugs, 3 important design gaps, 2 minor improvements). Cost: 5 minutes review. Savings: hours of debugging and refactoring.

The Iron Law

NO IMPLEMENTATION WITHOUT DOMAIN REVIEW FIRST

If you have a written brief, as a separate file or within a larger plan, dispatch domain expert before any implementation. No exceptions.

Not for:

• "Simple additions" (simple briefs hide complex issues)
• "Just following the steps" (steps may be flawed)
• "Time pressure" (exactly when you need review most)
• Don't rationalize. Review means review.

When to Use

MANDATORY for:

• Any task with a written brief, spec, or implementation plan
• All tasks in subagent-driven-development workflow
• Tasks you're about to implement (even if they seem simple)

Especially critical when:

• Brief includes code examples (may have anti-patterns)
• Specialized domain (serialization, networking, security, concurrency, data modeling)
• You recognize the pattern (familiarity breeds assumptions)
• Time pressure (exactly when you need to catch issues early)

The Pattern

BEFORE This Skill

Read brief → Implement → Code review finds issues → Refactor
Cost: Implementation time + refactoring time + context switching

AFTER This Skill

Read brief → Domain experts review brief → Fix brief → Implement with corrections
Cost: 5 minutes review
Savings: Hours of rework

Implementation

Step 1: Dispatch Domain Expert

If you have Task tool available:

Use Task tool to dispatch domain-appropriate expert agents.

• If reviewing an implementation plan, dispatch multiple agents focused on different aspects (examples: alogrithmic correctness, architecture, api, tasks properly sized, ...)
• If reviewing a design, dispatch multiple agents focused on different aspects (examples: conceptual correctness, ui/ux, architecture, api, ...)
• If reviewing a task brief dispatch domain-appropriate expert agents to validate the prompt.

Dispatch the agents with a prompt similar to this format:

Task(subagent_type="general-purpose", prompt=f"""
**Role:** You are a [domain] expert specializing in [specific area].

**Task:** Review this task brief for technical correctness and design flaws.

**Brief location:** [path to brief]

**Review focus:**
1. [Domain-specific concerns - e.g., serialization format, data types, security, industry standards]
2. Edge cases and error handling
3. Performance implications
4. Best practices compliance
5. Integration considerations
6. Coherence with overall plan
7. Task complexity and whether it should be decomposed.

**Provide:**
1. List of issues (Critical/Important/Minor)
2. For each: what's wrong and recommended fix
3. Things done well
4. Overall: "Ready to implement" or "Needs revision"

**Note:** Review the BRIEF/DESIGN, not code. Focus on flaws that cause problems during implementation.
""")

If Task tool not available:

STOP and ask your human partner: "I need to have a domain expert review this brief before implementing. How should I dispatch a consulting agent in this environment?"

Don't skip review because tool isn't obvious. Escalate to get the right mechanism.

Step 2: Address Issues

• Fix all Critical issues in brief before implementing
• Fix Important issues (or document why skipping)
• Note Minor issues for cleanup

Step 3: Implement with Corrections

Now dispatch implementation agent with corrected brief.

Step 4: Code Review After Implementation

Use code-reviewer to catch implementation gaps.

Domain Expert Examples

Serialization tasks: "Data serialization expert specializing in format design, type safety, and versioning"

Security tasks: "Application security specialist focusing on OWASP Top 10, attack vectors, and secure design patterns"

Networking tasks: "Distributed systems expert specializing in protocols, error handling, and network reliability"

Database tasks: "Database architect specializing in schema design, indexing strategies, and query optimization"

Algorithm tasks: "Algorithm specialist focusing on complexity analysis, edge cases, and correctness proofs"

Concurrency tasks: "Concurrency expert specializing in race conditions, deadlocks, and synchronization patterns"

Common Rationalizations

Red Flags - You're Rationalizing

If you think ANY of these thoughts, STOP and dispatch domain expert:

• "Brief is well-specified, just implement it"
• "This is a standard pattern"
• "The examples look good"
• "We're in a hurry"
• "Domain review for this is overkill"
• "I'll catch issues during implementation"

All of these mean: Dispatch domain expert first. No exceptions.

Integration with Workflows

With subagent-driven-development

CRITICAL: If you're using subagent-driven-development, you MUST add domain review as mandatory step.

Original workflow (from that skill):

For each task:
  1. READ the task from plan
  2. Dispatch implementation subagent
  3. Code review
  4. Fix code review issues

REQUIRED modification - add domain review FIRST:

For each task:
  1. READ the task from plan
  2. DISPATCH DOMAIN EXPERT to review task brief  ← MANDATORY
  3. ADDRESS domain expert issues                 ← MANDATORY
  4. Dispatch implementation subagent
  5. Code review
  6. Fix code review issues

Why both reviews:

• Domain review: Catches design flaws in the BRIEF (wrong approach, anti-patterns, security issues)
• Code review: Catches implementation gaps in the CODE (missed requirements, bugs, style issues)

Skipping domain review = implementing flawed designs. Code review can't fix architectural problems.

With executing-plans

Add domain review as first step before parallel execution:

1. Load plan
2. For each task: Dispatch domain expert, collect issues
3. Review all domain feedback with human
4. Execute tasks in parallel with corrections applied

Why This Works

Prevention vs remediation:

• Domain review: 5 min, catches design flaws
• Implementation: 30 min with flawed brief
• Debugging: 2+ hours finding root cause
• Refactoring: 1+ hour fixing architecture

Cost comparison:

• With review: 5 + 30 = 35 minutes
• Without review: 30 + 120 + 60 = 210 minutes

6× time savings for 5 minutes of review.

Real-World Example

Task: "Implement RiverGraph serialization using NumPy npz format"

Without domain review:

• Implement using code from brief
• Tests pass ✓
• MyPy fails (numpy scalars vs Python types)
• Runtime errors (ID arrays not numpy arrays)
• Missing validation (corrupted files accepted)
• Refactor for 2+ hours

With domain review (actual Phase 4A data):

• 5 min domain review finds 8 issues
• Fix in brief before implementing
• Implementation takes 30 min
• Tests pass ✓
• MyPy passes ✓
• Code review finds 1 minor issue
• Fix in 5 min
• Done

The Bottom Line

Task briefs lie. Not maliciously - they're written without complete knowledge. Authors don't know every edge case, anti-pattern, or domain best practice.

Domain experts find the lies before they become bugs.

5 minutes. Every task. No exceptions.