Imported from majiayu000/claude-skill-registry-data (design/design-synthesizer-matteocervelli-llms/SKILL.md). Install upstream with npx skills add majiayu000/claude-skill-registry-data --skill design-synthesizer-matteocervelli-llms. Copyright stays with the author.

Purpose

The design-synthesizer skill provides structured methods for integrating outputs from multiple parallel sub-agents into a cohesive design. It ensures consistency across architecture, library documentation, and dependencies while identifying and resolving conflicts or gaps.

When to Use

This skill auto-activates when you:

Integrate outputs from multiple parallel sub-agents
Synthesize architecture design with library documentation
Align dependencies with architectural requirements
Check consistency across design documents
Resolve conflicts between sub-agent outputs
Identify gaps or missing information in design
Prepare integrated design for PRP generation

Provided Capabilities

1. Output Integration

Load Multiple Documents: Read and parse outputs from all sub-agents
Extract Key Information: Identify critical design elements from each output
Cross-Reference: Link related elements across different outputs
Merge Content: Combine information into unified design

2. Consistency Checking

Architecture-Library Alignment: Verify architecture uses documented library features
Data Model Validation: Ensure data models match library APIs
API Contract Verification: Check API designs align with library patterns
Version Compatibility: Validate library versions match dependency analysis
Naming Consistency: Ensure consistent terminology across outputs

3. Conflict Resolution

Identify Mismatches: Find inconsistencies between sub-agent outputs
Version Conflicts: Resolve dependency version incompatibilities
Architecture Adjustments: Modify architecture to meet library constraints
Trade-off Analysis: Document compromises and decisions
Priority Resolution: Apply priority rules for conflicting requirements

4. Gap Identification

Missing Documentation: Flag undocumented library features
Incomplete Dependencies: Identify missing or unresolved dependencies
Architecture Gaps: Find components without implementation paths
Unresolved Issues: List conflicts or ambiguities requiring attention

5. Coherent Design Narrative

Unified Story: Create cohesive narrative across design elements
Traceability: Link design decisions to requirements
Rationale Documentation: Explain why specific approaches were chosen
Implementation Path: Define clear path from design to code

Usage Guide

Step 1: Load Sub-Agent Outputs

Read outputs from all 3 parallel sub-agents:

# Architecture Designer output
/docs/implementation/design/architecture-{issue-number}.md

# Documentation Researcher output
/docs/implementation/design/libraries-{issue-number}.md

# Dependency Manager output
/docs/implementation/design/dependencies-{issue-number}.md

Parse Each Output:

Architecture: Components, data models, API contracts, data flow, error handling
Libraries: Library versions, API references, code examples, integration patterns
Dependencies: Dependency tree, versions, compatibility, installation order

Step 2: Extract Key Information

Create structured summary of each output:

From Architecture Designer:

### Architecture Summary
**Components**:
- Component A: [Purpose and responsibilities]
- Component B: [Purpose and responsibilities]

**Data Models**:
- Model X: [Fields, validations, relationships]
- Model Y: [Fields, validations, relationships]

**API Contracts**:
- Endpoint 1: [Method, path, request/response]
- Endpoint 2: [Method, path, request/response]

**Data Flow**:
- Flow 1: [Source → Transform → Destination]

**Error Handling**:
- Strategy: [Approach and patterns]

From Documentation Researcher:

### Library Documentation Summary
**Library A (v1.2.3)**:
- Purpose: [What it does]
- Key APIs: [Main functions/classes]
- Code Example: [Integration pattern]
- Best Practices: [Recommended usage]

**Library B (v2.0.0)**:
- Purpose: [What it does]
- Key APIs: [Main functions/classes]
- Code Example: [Integration pattern]
- Known Issues: [Caveats and workarounds]

From Dependency Manager:

### Dependency Summary
**Dependency Tree**:
├── library-a==1.2.3
│   ├── dep-x>=2.0
│   └── dep-y<3.0
└── library-b==2.0.0
    └── dep-z~=1.5

**Conflicts**: [List of version conflicts]
**Resolution**: [How conflicts were resolved]
**Installation Order**: [Sequence of installation]

Step 3: Cross-Reference Design Elements

Map architecture components to libraries and dependencies:

Use synthesis-guide.md for detailed cross-referencing methodology.

Architecture → Libraries Mapping:

### Component A
- **Uses**: Library A (v1.2.3)
- **APIs**: Library A's `ClassX` and `FunctionY`
- **Pattern**: Documented in libraries-{issue-number}.md, section 2.3
- **Code Example**: [Link to example in library docs]

### Data Model X
- **Validation**: Uses Library A's `ValidationMixin`
- **Serialization**: Uses Library B's `Serializer`
- **Storage**: Requires dependency: `database-driver>=3.0`

Libraries → Dependencies Mapping:

### Library A (v1.2.3)
- **Required Dependencies**: dep-x>=2.0, dep-y<3.0
- **Optional Dependencies**: dep-optional (for feature Z)
- **Compatibility**: Python 3.9+
- **Conflicts**: None identified

Cross-Reference Matrix:

Component	Library	Version	Dependencies	Documented
Component A	Library A	1.2.3	dep-x, dep-y	✅
Component B	Library B	2.0.0	dep-z	✅
Data Model X	Library A	1.2.3	dep-x	✅

Step 4: Check Consistency

Validate alignment across all outputs:

Architecture-Library Consistency:

✅ All architecture components reference documented libraries
✅ All library APIs used in architecture are documented
✅ All data models align with library expectations
✅ All API contracts follow library patterns
⚠️ Warning: Component C uses undocumented Library API (flag for review)

Library-Dependency Consistency:

✅ All libraries have resolved dependencies
✅ All dependency versions are compatible
✅ No circular dependencies detected
⚠️ Conflict: Library A requires dep-x>=2.0, but Library B requires dep-x<2.5 (resolved to 2.4.0)

Naming and Terminology Consistency:

✅ Component names consistent across documents
✅ Data model names match architecture diagrams
⚠️ Inconsistency: Architecture calls it "UserProfile", libraries call it "Profile" (standardize to "UserProfile")

Version Consistency:

✅ Library versions match dependency analysis
✅ All version constraints satisfied
⚠️ Note: Library C has newer version (3.0.0) available, but using 2.8.5 for stability

Step 5: Resolve Conflicts

Use synthesis-guide.md conflict resolution strategies:

Conflict Type 1: Version Incompatibility

**Conflict**: Library A requires dep-x>=2.0, Library B requires dep-x<2.5
**Analysis**: Both constraints can be satisfied with dep-x==2.4.0
**Resolution**: Pin dep-x to 2.4.0 in requirements
**Trade-off**: Cannot use dep-x 2.5+ features until Library B updates
**Risk**: Low - 2.4.0 is stable and well-tested

Conflict Type 2: Architecture-Library Mismatch

**Conflict**: Architecture designs async API, but Library C only supports sync
**Analysis**: Need to wrap Library C with async adapter or redesign
**Options**:
  1. Use asyncio.to_thread() to wrap Library C (simpler, slight overhead)
  2. Replace Library C with async alternative (more work, better performance)
**Resolution**: Use asyncio.to_thread() wrapper (priority: speed of implementation)
**Trade-off**: 5-10% performance overhead vs. 2-3 days rewrite
**Mitigation**: Profile performance, optimize if needed

Conflict Type 3: Missing Documentation

**Conflict**: Architecture uses Library D feature, but no documentation found
**Analysis**: Feature exists in Library D source code but undocumented
**Resolution**:
  1. Add note in PRP about undocumented feature
  2. Include code example from Library D source
  3. Flag for testing during implementation
**Risk**: Medium - undocumented features may change without notice
**Mitigation**: Pin Library D version, add comprehensive tests

Step 6: Identify Gaps

Document missing information or unresolved issues:

Gap Analysis:

### Missing Documentation
- Library E's `advanced_feature()` used in architecture but not documented
- Library F's error handling patterns unclear from documentation

### Incomplete Dependencies
- Component G requires database driver, but version not specified
- Testing framework not included in dependency analysis

### Architecture Gaps
- Component H has no implementation path (needs design detail)
- Error handling for API endpoint 3 not specified

### Unresolved Ambiguities
- Data Model Z validation rules conflict with Library requirements
- Performance target not specified for async operations

Step 7: Create Cohesive Design Narrative

Synthesize all information into unified design:

Use design-patterns.md for common patterns and structures.

Synthesized Design Structure:

## Synthesized Design

### Overview
[High-level description of integrated design]

### Component Architecture
[Unified component diagram with library annotations]

**Component A** (uses Library A v1.2.3)
- **Responsibilities**: [What it does]
- **Implementation**: Uses `Library A.ClassX` for [purpose]
- **Dependencies**: dep-x>=2.0, dep-y<3.0
- **Integration**: [How it connects to other components]

**Component B** (uses Library B v2.0.0)
- **Responsibilities**: [What it does]
- **Implementation**: Uses `Library B.ServiceY` for [purpose]
- **Dependencies**: dep-z~=1.5
- **Integration**: [How it connects to other components]

### Data Models (Pydantic Schemas)

**UserProfile Model**
```python
from library_a import ValidationMixin
from pydantic import BaseModel

class UserProfile(BaseModel, ValidationMixin):
    id: int
    name: str
    email: EmailStr  # From library_a
    # ... fields with library-specific validations

API Contracts

Endpoint 1: POST /api/users

Implementation: Uses Library A's create_user() method
Request: UserProfile schema
Response: UserProfile with generated ID
Error Handling: Library A's exceptions mapped to HTTP status codes

Library Integration Strategy

Library A (v1.2.3): User management and validation

Integration Point: Component A, Data Model UserProfile
Code Pattern: [Example from documentation]
Error Handling: Catch LibraryAException, return 400/500

Library B (v2.0.0): Background task processing

Integration Point: Component B
Code Pattern: [Example from documentation]
Configuration: [Settings required]

Dependency Resolution

Final Dependency Tree:

library-a==1.2.3
├── dep-x==2.4.0  # Pinned to resolve conflict
├── dep-y==2.8.0
library-b==2.0.0
├── dep-z==1.5.3
└── dep-x==2.4.0  # Shared with library-a

Installation Commands:

pip install library-a==1.2.3
pip install library-b==2.0.0
pip install -r requirements.txt

Implementation Path

Phase 1: Foundation

Install dependencies (in order above)
Create data models with Library A validations
Set up Library B configuration

Phase 2: Core Components

Implement Component A using Library A patterns
Implement Component B using Library B patterns
Test components independently

Phase 3: Integration

Connect Component A → Component B
Implement error handling across components
Integration testing

Phase 4: Validation

Unit tests for each component
Integration tests for component interactions
Performance testing

Design Decisions

Decision 1: Async Wrapper for Library C

Rationale: Library C only supports sync, but architecture requires async
Approach: Use asyncio.to_thread() wrapper
Trade-off: 5-10% performance overhead vs. 2-3 days to rewrite with async library
Risk: Low - overhead is acceptable for current scale

Decision 2: Pin dep-x to 2.4.0

Rationale: Resolve version conflict between Library A and Library B
Approach: Pin to highest compatible version (2.4.0)
Trade-off: Cannot use dep-x 2.5+ features until Library B updates
Risk: Low - 2.4.0 is stable

Identified Issues

Issue 1: Undocumented Library D Feature

Description: Architecture uses Library D's advanced_feature(), but not in docs
Impact: Medium - feature may change without notice
Mitigation: Pin Library D version, add comprehensive tests, monitor for updates

Issue 2: Component H Implementation Gap

Description: Component H responsibilities defined, but implementation approach unclear
Impact: High - blocks implementation
Action Required: Architecture Designer needs to provide implementation details

Gaps Requiring Attention

Resolve Component H implementation approach
Verify Library D's advanced_feature() API stability
Specify database driver version for Component G
Clarify performance targets for async operations
Add testing framework to dependency analysis


### Step 8: Validate Synthesis Quality

Quality checklist:

**Completeness**:
- ✅ All architecture components mapped to libraries
- ✅ All libraries mapped to dependencies
- ✅ All data models have implementation details
- ✅ All API contracts have library integration notes
- ⚠️  Component H needs more detail

**Consistency**:
- ✅ Terminology consistent across documents
- ✅ Version numbers match everywhere
- ✅ Component names standardized
- ✅ Dependencies resolved without conflicts

**Actionability**:
- ✅ Implementation path is clear and specific
- ✅ Installation commands provided
- ✅ Code patterns documented
- ⚠️  Some gaps flagged for resolution

**Traceability**:
- ✅ Design elements link to requirements
- ✅ Library choices justified
- ✅ Design decisions documented with rationale

## Best Practices

### 1. Start with Overview
- Read all outputs completely before synthesis
- Create summary of each output
- Identify major themes and patterns

### 2. Map Systematically
- Use structured templates for mapping
- Create traceability matrices
- Document every cross-reference

### 3. Validate Early
- Check consistency as you integrate
- Flag issues immediately
- Don't ignore small discrepancies

### 4. Resolve Conflicts Transparently
- Document all conflicts found
- Explain resolution reasoning
- Note trade-offs and risks

### 5. Identify All Gaps
- Missing documentation
- Incomplete specifications
- Unresolved ambiguities
- Assumptions that need validation

### 6. Create Unified Narrative
- Tell coherent story from architecture → libraries → dependencies → implementation
- Link every design element to requirements
- Provide clear implementation path

## Resources

### synthesis-guide.md
Comprehensive guide for synthesizing sub-agent outputs including:
- Cross-referencing methodology
- Consistency checking procedures
- Conflict resolution strategies
- Gap identification techniques
- Quality validation criteria

### design-patterns.md
Common design patterns and structures including:
- Component integration patterns
- Library usage patterns
- Dependency management patterns
- Error handling patterns
- Testing patterns

## Example Usage

### Input (Sub-Agent Outputs)

**Architecture Designer Output**:
```markdown
## Components
- **UserService**: Handles user CRUD operations
- **TaskQueue**: Manages background tasks

## Data Models
- **User**: id, name, email, created_at
- **Task**: id, task_type, status, payload

## APIs
- POST /api/users: Create user
- POST /api/tasks: Queue background task

Documentation Researcher Output:

## Libraries
**SQLAlchemy (v2.0.0)**: ORM for database
- User model: Use `declarative_base()` pattern
- Example: [Code snippet]

**Celery (v5.3.0)**: Background task queue
- Task definition: Use `@app.task` decorator
- Example: [Code snippet]

Dependency Manager Output:

## Dependencies
sqlalchemy==2.0.0
├── greenlet>=2.0
celery==5.3.0
├── kombu>=5.3
└── billiard>=4.0

Conflict: greenlet version (resolved to 2.0.2)

Output (Synthesized Design)

## Synthesized Design

### Component Architecture

**UserService** (uses SQLAlchemy v2.0.0)
- **Implementation**: SQLAlchemy `declarative_base()` pattern
- **Dependencies**: sqlalchemy==2.0.0, greenlet==2.0.2
- **Data Model**: User class inherits from SQLAlchemy Base

**TaskQueue** (uses Celery v5.3.0)
- **Implementation**: Celery `@app.task` decorator
- **Dependencies**: celery==5.3.0, kombu>=5.3, billiard>=4.0
- **Integration**: Tasks defined in tasks.py, queued via TaskQueue service

### Data Models (SQLAlchemy + Pydantic)

```python
from sqlalchemy import declarative_base
from pydantic import BaseModel

Base = declarative_base()

class User(Base):
    __tablename__ = 'users'
    id: int
    name: str
    email: str  # With SQLAlchemy validation
    created_at: datetime

Library Integration

SQLAlchemy: Use declarative_base() for User model (documented pattern) Celery: Define tasks with @app.task, configure broker in settings

Dependencies (Resolved)

sqlalchemy==2.0.0
├── greenlet==2.0.2  # Pinned to resolve conflict
celery==5.3.0
├── kombu>=5.3
└── billiard>=4.0

Installation:

pip install sqlalchemy==2.0.0 celery==5.3.0

Design Decisions

Decision: Pin greenlet to 2.0.2

Rationale: Resolve version conflict between SQLAlchemy and system
Risk: Low


## Integration

This skill is used by:
- **design-orchestrator** agent during Phase 2: Design & Planning
- Activates automatically when orchestrator synthesizes sub-agent outputs
- Provides unified design for PRP generation (prp-generator skill)

---

**Version**: 2.0.0
**Auto-Activation**: Yes (when synthesizing sub-agent outputs)
**Phase**: 2 (Design & Planning)
**Created**: 2025-10-29

design-synthesizer

About

Purpose

When to Use

Provided Capabilities

1. Output Integration

2. Consistency Checking

3. Conflict Resolution

4. Gap Identification

5. Coherent Design Narrative

Usage Guide

Step 1: Load Sub-Agent Outputs

Step 2: Extract Key Information

Step 3: Cross-Reference Design Elements

Step 4: Check Consistency

Step 5: Resolve Conflicts

Step 6: Identify Gaps

Step 7: Create Cohesive Design Narrative

API Contracts

Library Integration Strategy

Dependency Resolution

Implementation Path

Design Decisions

Identified Issues

Gaps Requiring Attention

Output (Synthesized Design)

Library Integration

Dependencies (Resolved)

Design Decisions

Use it

Manifest

Reviews