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

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