new-feature-design

name	new-feature-design
description	Design and document new features with GitHub issue, low-level design (LLD), and expert review. Creates structured documentation in .scratchpad/ with issue spec, technical design with diagrams and pseudo-code, and multi-persona expert review. Supports starting from a user description OR an existing GitHub issue URL. Folder naming: issue-{number}/ for existing issues, {feature-name}/ for new features.
metadata	{"author":"mcp-gateway-registry","version":"1.4"}

New Feature Design Skill

Use this skill when the user wants to design a new feature for the MCP Gateway Registry. This skill creates comprehensive design documentation that enables entry-level developers to implement the feature.

Input Modes

This skill supports two input modes:

1. User Description Mode - User describes the feature they want to design
2. GitHub Issue URL Mode - User provides a URL to an existing GitHub issue

Detecting Input Mode

When the user invokes this skill:

• If they provide a GitHub issue URL (e.g., https://github.com/owner/repo/issues/123), use GitHub Issue URL Mode
• Otherwise, use User Description Mode

Workflow

User Description Mode Workflow

1. Gather Requirements - Ask clarifying questions about the feature
2. Quick Codebase Review - Explore the codebase to understand structure
3. Create Design Folder - Create .scratchpad/{feature-name}/ directory
4. Write GitHub Issue - Create github-issue.md for issue creation
5. Deep Codebase Analysis - Thoroughly explore relevant code
6. Write Low-Level Design - Create lld.md with technical details
7. Expert Review - Create review.md with multi-persona feedback
8. Present Summary & Seek Guidance - Present findings and ask for direction

GitHub Issue URL Mode Workflow

1. Fetch GitHub Issue - Retrieve issue content using gh CLI
2. Analyze Issue Content - Extract requirements, design elements, and context
3. Quick Codebase Review - Explore the codebase to understand structure
4. Create Design Folder - Create .scratchpad/issue-{number}/ directory (e.g., issue-500 for GitHub issue #500)
5. Summarize Existing Issue - Create github-issue.md summarizing the existing issue
6. Clarify Requirements - Ask user about any gaps or ambiguities found
7. Deep Codebase Analysis - Thoroughly explore relevant code
8. Write Low-Level Design - Create lld.md with technical details
9. Expert Review - Create review.md with multi-persona feedback
10. Present Summary & Seek Guidance - Present findings and ask for direction

---

GitHub Issue URL Mode

Step 1: Fetch GitHub Issue

When a user provides a GitHub issue URL, fetch the issue content using the gh CLI:

# Extract owner, repo, and issue number from URL
# URL format: https://github.com/{owner}/{repo}/issues/{number}

# Fetch issue details
gh issue view {number} --repo {owner}/{repo} --json title,body,labels,state,assignees,comments

# For more context, also fetch related PRs if any
gh issue view {number} --repo {owner}/{repo} --json linkedPullRequests

Step 2: Analyze Issue Content

After fetching the issue, analyze it for:

1. Existing Requirements

   • Problem statement
   • User stories or use cases
   • Acceptance criteria
   • Scope definition

2. Existing Design Elements

   • Technical proposals in the issue body
   • Architecture suggestions
   • API designs mentioned
   • Data model proposals
   • Diagrams or pseudocode

3. Discussion Context

   • Comments with additional requirements
   • Decisions made in discussion
   • Concerns raised by team members
   • Alternative approaches discussed

4. Metadata

   • Labels (indicates feature type, priority)
   • Assignees (who might have context)
   • Linked PRs (prior implementation attempts)

Step 3: Create Issue Summary

Create a summary document that captures what was found:

# GitHub Issue Analysis: #{issue_number}

*Source: {issue_url}*
*Fetched: {date}*

## Issue Overview

| Field | Value |
|-------|-------|
| Title | {title} |
| State | {state} |
| Labels | {labels} |
| Assignees | {assignees} |

## Extracted Requirements

### Problem Statement
{extracted or "Not explicitly stated - needs clarification"}

### User Stories
{extracted user stories or "None found"}

### Acceptance Criteria
{extracted criteria or "Not defined - will need to establish"}

### Scope
{inferred scope or "Not specified"}

## Existing Design Elements

### Technical Proposals
{any technical details from issue body}

### Architecture Suggestions
{any architecture mentioned}

### API Design
{any API designs proposed}

### Open Questions in Issue
{questions raised but not answered}

## Discussion Summary

### Key Decisions Made
{decisions from comments}

### Concerns Raised
{concerns from team members}

### Alternative Approaches Mentioned
{alternatives discussed}

## Gaps Identified

The following information is missing and needs clarification:
1. {gap 1}
2. {gap 2}

Step 4: Clarify Requirements

Based on the analysis, ask the user only about gaps not covered in the issue:

1. Feature name (derive from issue title if possible, use kebab-case)
2. Missing requirements - Only ask about gaps identified
3. Design decisions - If alternatives were discussed but not decided
4. Scope confirmation - Verify the scope interpretation is correct

Example prompt:

I've analyzed GitHub issue #{number}: "{title}"

The issue provides:
- {what's available}

However, I need clarification on:
1. {gap question 1}
2. {gap question 2}

Also, the issue discusses two approaches for {topic}:
- Option A: {description}
- Option B: {description}

Which approach should we pursue in the design?

---

User Description Mode

Step 1: Gather Requirements

Before creating any files, ask the user:

1. What is the feature name? (will be used for folder name, use kebab-case)
2. What problem does this feature solve?
3. Who are the users/consumers of this feature?
4. Are there any constraints or requirements?
5. What is the expected scope (small/medium/large)?

Step 2: Quick Codebase Review

Before creating any design documents, perform a quick exploration of the codebase to understand:

1. Project Structure - Use Glob to understand the overall directory layout

   • Identify main source directories (registry/, src/, etc.)
   • Locate existing models, routes, services, and utilities
   • Find configuration files and constants

2. Related Components - Search for existing features similar to the one being designed

   • Use Grep to find relevant keywords and patterns
   • Identify existing patterns and conventions used in the codebase

3. Entry Points - Understand how the application is structured

   • Find the main FastAPI application and router setup
   • Identify middleware, dependencies, and shared utilities

This quick review should take 5-10 minutes and helps you ask better clarifying questions and avoid proposing designs that conflict with existing architecture.

Step 3: Create Design Folder

Folder Naming Convention

IMPORTANT: Use different naming conventions based on the input mode:

Input Mode	Folder Name	Example
GitHub Issue URL Mode	issue-{number}/	issue-500/ for GitHub issue #500
User Description Mode	{feature-name}/	rate-limiting/ for a rate limiting feature

This convention makes it easy to:

• Trace design documents back to their source GitHub issue
• Avoid duplicate work on the same issue
• Organize designs consistently

Folder Structure

Create the folder structure:

.scratchpad/issue-{number}/     # For GitHub Issue URL Mode
# OR
.scratchpad/{feature-name}/     # For User Description Mode

├── github-issue.md    # GitHub issue specification or summary
├── lld.md             # Low-level design document
└── review.md          # Expert review document

Step 4: Write GitHub Issue (github-issue.md)

For User Description Mode: Create a comprehensive GitHub issue specification.

For GitHub Issue URL Mode: Create a summary document that consolidates the existing issue content with any clarifications gathered. Use the "Issue Summary from URL" template below instead.

Template: New Issue Specification (User Description Mode)

# GitHub Issue: {Feature Title}

## Title
{concise title for the issue}

## Labels
- {appropriate labels from: enhancement, feature-request, api, frontend, backend, etc.}

## Description

### Problem Statement
{What problem does this solve? Why is it needed?}

### Proposed Solution
{High-level description of the solution}

### User Stories
- As a {user type}, I want to {action} so that {benefit}
- ...

### Acceptance Criteria
- [ ] {Criterion 1}
- [ ] {Criterion 2}
- ...

### Out of Scope
- {What is explicitly NOT included}

### Dependencies
- {Any dependent issues or external dependencies}

### Related Issues
- #{issue numbers if any}

Template: Issue Summary from URL (GitHub Issue URL Mode)

When working from an existing GitHub issue, create a summary document:

# Issue Summary: {Issue Title}

*Source Issue: [{owner}/{repo}#{number}]({issue_url})*
*Fetched: {date}*
*Status: {open/closed}*

## Issue Metadata

| Field | Value |
|-------|-------|
| Labels | {labels} |
| Assignees | {assignees} |
| Created | {created_date} |
| Last Updated | {updated_date} |

## Original Problem Statement

{Copy or summarize the problem statement from the issue body}

## Requirements Extracted

### From Issue Body
{Requirements found in the original issue}

### From Discussion (Comments)
{Additional requirements or clarifications from comments}

### Clarified with User
{Any requirements clarified during our conversation}

## Existing Design Elements

{Any technical proposals, architecture suggestions, or design decisions already in the issue}

### Technical Approach
{If specified in the issue}

### API Design
{If specified in the issue}

### Data Models
{If specified in the issue}

## Acceptance Criteria

### From Issue
{Criteria from the original issue}

### Additional (Established)
{Any additional criteria we established}

## Scope

{Scope as defined or inferred from the issue}

## Out of Scope

{What is explicitly excluded}

## Key Decisions from Discussion

| Decision | Context | Decided By |
|----------|---------|------------|
| {decision} | {why} | {who/when} |

## Open Questions Resolved

| Question | Resolution |
|----------|------------|
| {question from issue} | {answer we determined} |

## Dependencies

{Any dependencies mentioned in the issue}

## Notes

{Any additional context or notes relevant to the design}

Step 5: Deep Codebase Analysis

CRITICAL: Before writing the LLD, you MUST thoroughly understand all relevant code in the repository. This is not optional - a design that doesn't account for existing code patterns will fail during implementation.

What to Analyze

1. Existing Models and Data Structures

   • Read ALL relevant Pydantic models in registry/models/
   • Understand field types, validators, and relationships
   • Identify any models that need to be extended or referenced

2. Service Layer Patterns

   • Read existing services in registry/services/
   • Understand how business logic is organized
   • Identify common patterns (error handling, logging, caching)
   • Note any base classes or utility functions used

3. Route/API Patterns

   • Read existing routes in registry/routes/
   • Understand request/response patterns
   • Identify how authentication, validation, and error responses are handled
   • Note middleware and dependencies used

4. Storage Layer

   • Read storage implementations in registry/storage/
   • Understand how data is persisted
   • Identify any abstraction layers or interfaces

5. Configuration and Constants

   • Read configuration files and constants
   • Understand environment variable patterns
   • Identify feature flags or configuration options

6. Existing Tests

   • Read relevant test files in tests/
   • Understand testing patterns and fixtures used
   • Identify how mocking is done

How to Analyze

Use the Task tool with subagent_type=Explore for thorough investigation:

Task tool with prompt: "Thoroughly analyze the service layer patterns in registry/services/.
Read all service files and document: 1) Common patterns used, 2) Error handling approaches,
3) Logging conventions, 4) Any base classes or utilities, 5) How services interact with storage."

For each area, you should:

• Read the actual code, not just file names
• Understand the "why" behind design decisions
• Note any TODOs or known issues
• Identify code that your feature will need to integrate with

Document Your Findings

Create a brief section in your LLD documenting:

• Key files reviewed
• Patterns identified
• Integration points for the new feature
• Any constraints or limitations discovered

Step 6: Write Low-Level Design (lld.md)

Create a detailed technical design document. This is the most critical document - it should contain enough detail for an entry-level developer to implement the feature.

# Low-Level Design: {Feature Name}

*Created: {date}*
*Author: Claude*
*Status: Draft*

## Table of Contents
1. [Overview](#overview)
2. [Codebase Analysis](#codebase-analysis)
3. [Architecture](#architecture)
4. [Data Models](#data-models)
5. [API Design](#api-design)
6. [Configuration Parameters](#configuration-parameters)
7. [New Dependencies](#new-dependencies)
8. [Implementation Details](#implementation-details)
9. [Observability](#observability)
10. [Scaling Considerations](#scaling-considerations)
11. [File Changes](#file-changes)
12. [Testing Strategy](#testing-strategy)
13. [Alternatives Considered](#alternatives-considered)
14. [Rollout Plan](#rollout-plan)

## Overview

### Problem Statement
{Detailed problem description}

### Goals
- {Goal 1}
- {Goal 2}

### Non-Goals
- {What this design explicitly does NOT address}

## Codebase Analysis

*Summary of the deep codebase analysis performed before writing this LLD.*

### Key Files Reviewed

| File/Directory | Purpose | Relevance to This Feature |
|----------------|---------|---------------------------|
| `registry/models/{model}.py` | {Description} | {How it relates} |
| `registry/services/{service}.py` | {Description} | {How it relates} |
| `registry/routes/{route}.py` | {Description} | {How it relates} |

### Existing Patterns Identified

1. **Pattern Name**: {Description of the pattern and where it's used}
   - Files: `{file1.py}`, `{file2.py}`
   - How we'll follow this: {How the new feature will use this pattern}

2. **Pattern Name**: {Description}
   - Files: `{files}`
   - How we'll follow this: {How we'll apply it}

### Integration Points

| Component | Integration Type | Details |
|-----------|------------------|---------|
| {Existing component} | {Extends/Uses/Depends on} | {Specific integration details} |

### Constraints and Limitations Discovered

- {Constraint 1}: {How it affects the design}
- {Constraint 2}: {How it affects the design}

### Code Snippets Reference

{Include relevant code snippets from existing codebase that the new feature will integrate with or follow patterns from}

```python
# From registry/services/example_service.py:45-60
# This shows the pattern we'll follow for...
def existing_pattern_example():
    pass

Architecture

System Context Diagram

{ASCII diagram showing how this feature fits into the overall system}

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│                 │     │                 │     │                 │
│   Component A   │────▶│   New Feature   │────▶│   Component B   │
│                 │     │                 │     │                 │
└─────────────────┘     └─────────────────┘     └─────────────────┘

Sequence Diagram

{Show the flow of requests/data}

User          Frontend       Backend        Database
  │               │              │              │
  │──── Request ──▶│              │              │
  │               │── API Call ──▶│              │
  │               │              │── Query ────▶│
  │               │              │◀── Result ───│
  │               │◀── Response ─│              │
  │◀── Display ───│              │              │

Component Diagram

{Show internal components and their relationships}

Data Models

New Models

{Define any new Pydantic models with full field definitions}

class NewModel(BaseModel):
    """Description of the model."""

    field_name: str = Field(
        ...,
        description="What this field represents",
        min_length=1,
        max_length=100
    )
    optional_field: Optional[int] = Field(
        default=None,
        description="Optional field description"
    )

Model Changes

{Changes to existing models}

Database Schema Changes

{If applicable, show collection/table changes}

API Design

New Endpoints

POST /api/v1/{endpoint}

Description: {What this endpoint does}

Request:

{
    "field": "value"
}

Response (200 OK):

{
    "id": "123",
    "status": "success"
}

Error Responses:

• 400 Bad Request: {when}
• 401 Unauthorized: {when}
• 404 Not Found: {when}

API Changes

{Changes to existing endpoints}

Configuration Parameters

IMPORTANT: Clearly document all new configuration parameters this feature requires.

New Environment Variables

Variable Name	Type	Default	Required	Description
FEATURE_ENABLED	bool	true	No	Enable/disable the feature
FEATURE_INTERVAL_SECONDS	int	30	No	Polling interval in seconds

Settings Class Updates

Add to registry/core/config.py:

    # Feature-specific settings
    feature_enabled: bool = Field(
        default=True,
        description="Enable/disable feature X"
    )
    feature_interval_seconds: int = Field(
        default=30,
        description="Interval for feature X operations"
    )

Configuration Validation

{Any validation rules for configuration values}

New Dependencies

IMPORTANT: List all new Python packages or libraries required by this feature.

Python Packages

Package	Version	Purpose	Added By
package-name	latest	{Why needed}	Backend
another-package	latest	{Why needed}	Frontend

Adding Dependencies

# Add to pyproject.toml
uv add package-name

No New Dependencies

If no new dependencies are required, explicitly state:

• "This feature uses only existing dependencies from the project."

Implementation Details

Step-by-Step Implementation

Step 1: {First Step}

File: path/to/file.py Lines: {approximate line numbers or "new file"}

# Pseudo-code or actual code
def new_function(
    param1: str,
    param2: int
) -> dict:
    """
    Description of what this function does.

    Args:
        param1: Description
        param2: Description

    Returns:
        Description of return value
    """
    # Step 1: Validate input
    if not param1:
        raise ValueError("param1 is required")

    # Step 2: Process data
    result = process_data(param1, param2)

    # Step 3: Return response
    return {"status": "success", "data": result}

Step 2: {Second Step}

{Continue with detailed steps...}

Error Handling

{How errors should be handled}

Logging

{What should be logged and at what level}

Observability

Tracing

{Define trace spans for this feature}

Span Name	Attributes	Parent Span
feature.operation_name	param1, param2	http.request

Metrics

{Define metrics to track for this feature}

Metric Name	Type	Labels	Description
feature_requests_total	Counter	status, endpoint	Total requests
feature_duration_seconds	Histogram	operation	Operation duration

Logging Points

{Key operations that should emit logs}

Log Level	Event	Data to Include
INFO	Operation started	request_id, user_id
ERROR	Operation failed	error_type, context

Scaling Considerations

Current Load Assumptions

{Expected request volume and data size}

Horizontal Scaling

{How this feature scales across multiple instances}

Bottlenecks

{Potential bottlenecks and mitigation strategies}

Caching Strategy

{If applicable, what can be cached and for how long}

File Changes

New Files

File Path	Description
registry/routes/new_feature.py	API routes for new feature
registry/services/new_feature_service.py	Business logic
tests/unit/test_new_feature.py	Unit tests

Modified Files

File Path	Lines	Change Description
registry/main.py	~50	Add router import and include
registry/models/domain.py	~100-150	Add new model

Estimated Lines of Code

Category	Lines
New Python code	~{X}
New test code	~{X}
Modified code	~{X}
Total	~{X}

Testing Strategy

IMPORTANT: Explicitly list all new test files and test cases required for this feature.

New Test Files

Test File	Type	Description
tests/unit/services/test_feature_service.py	Unit	Service layer unit tests
tests/unit/repositories/test_feature_repository.py	Unit	Repository unit tests
tests/integration/test_feature_integration.py	Integration	End-to-end integration tests
tests/unit/api/test_feature_routes.py	Unit	API route unit tests

Unit Tests Required

List specific unit test cases:

Test Case	File	What It Tests
test_happy_path	test_feature_service.py	Normal operation with valid inputs
test_error_handling	test_feature_service.py	Error cases and edge conditions
test_validation	test_feature_service.py	Input validation logic

Example unit test structure:

class TestNewFeature:
    """Tests for new feature."""

    def test_happy_path(self):
        """Test normal operation."""
        # Arrange
        input_data = {...}

        # Act
        result = function_under_test(input_data)

        # Assert
        assert result["status"] == "success"

    def test_error_case(self):
        """Test error handling."""
        with pytest.raises(ValueError):
            function_under_test(None)

Integration Tests Required

List specific integration test cases:

Test Case	File	What It Tests
test_end_to_end_flow	test_feature_integration.py	Complete feature workflow
test_database_persistence	test_feature_integration.py	Data is correctly persisted
test_concurrent_operations	test_feature_integration.py	Concurrency handling

Test Coverage Requirements

• Minimum coverage for new code: 80%
• All public methods must have tests
• Error paths must be tested

Manual Testing

{Steps for manual verification}

Alternatives Considered

IMPORTANT: Document alternative approaches that were considered and why they were rejected.

Alternative 1: {Alternative Approach Name}

Description: {Brief description of the alternative}

Pros:

• {Advantage 1}
• {Advantage 2}

Cons:

• {Disadvantage 1}
• {Disadvantage 2}

Why Rejected: {Clear explanation of why this wasn't chosen}

Alternative 2: {Another Alternative}

Description: {Brief description}

Pros:

• {Advantage}

Cons:

• {Disadvantage}

Why Rejected: {Explanation}

Comparison Matrix

Criteria	Chosen Approach	Alternative 1	Alternative 2
Complexity	Low	Medium	High
Performance	Good	Better	Best
Maintainability	High	Medium	Low
Implementation Time	1 week	2 weeks	3 weeks

Rollout Plan

Phase 1: Development

• Implement core functionality
• Write unit tests
• Code review

Phase 2: Testing

• Integration testing
• Security review
• Performance testing (if applicable)

Phase 3: Deployment

• Deploy to staging
• Verify in staging
• Deploy to production
• Monitor for issues

Open Questions

• {Any unresolved questions that need answers}

References

• {Links to relevant documentation}
• {Links to similar implementations}

## Step 7: Expert Review (review.md)

Create a review document with feedback from multiple expert personas:

```markdown
# Expert Review: {Feature Name}

*Review Date: {date}*
*LLD Version: 1.0*

## Review Panel

| Role | Reviewer | Status |
|------|----------|--------|
| Frontend Engineer | Pixel | Pending |
| Backend Engineer | Byte | Pending |
| SRE/DevOps Engineer | Circuit | Pending |
| Security Engineer | Cipher | Pending |
| SMTS (Overall) | Sage | Pending |

---

## Frontend Engineer Review

**Reviewer:** Pixel
**Focus Areas:** UI/UX, React components, state management, API integration

### Assessment

#### Strengths
- {Positive aspects of the design from frontend perspective}

#### Concerns
- {Issues or risks identified}

#### New Libraries Required

| Library | Version | Purpose | Justification |
|---------|---------|---------|---------------|
| `library-name` | `latest` | {What it does} | {Why it's needed vs alternatives} |
| None | - | - | No new frontend dependencies required |

#### Better Alternatives Considered

{Are there better frontend approaches? Discuss alternatives like different state management, component libraries, etc.}

#### Recommendations
1. {Specific recommendation}
2. {Specific recommendation}

#### Questions for Author
- {Questions that need clarification}

### Verdict: {APPROVED / APPROVED WITH CHANGES / NEEDS REVISION}

---

## Backend Engineer Review

**Reviewer:** Byte
**Focus Areas:** API design, data models, business logic, database queries, performance

### Assessment

#### Strengths
- {Positive aspects from backend perspective}

#### Concerns
- {Issues or risks identified}

#### New Libraries Required

| Library | Version | Purpose | Justification |
|---------|---------|---------|---------------|
| `library-name` | `latest` | {What it does} | {Why it's needed vs alternatives} |
| None | - | - | No new backend dependencies required |

#### Better Alternatives Considered

{Are there better backend approaches? Discuss alternatives like different algorithms, data structures, caching strategies, etc.}

#### Recommendations
1. {Specific recommendation}
2. {Specific recommendation}

#### Questions for Author
- {Questions that need clarification}

### Verdict: {APPROVED / APPROVED WITH CHANGES / NEEDS REVISION}

---

## SRE/DevOps Engineer Review

**Reviewer:** Circuit
**Focus Areas:** Deployment, monitoring, scaling, infrastructure, reliability

### Assessment

#### Strengths
- {Positive aspects from SRE perspective}

#### Concerns
- {Issues or risks identified}

#### Infrastructure Dependencies

| Resource | Type | Purpose | Cost Impact |
|----------|------|---------|-------------|
| `resource-name` | AWS Service / Tool | {What it does} | {Estimated cost} |
| None | - | - | No new infrastructure required |

#### Better Alternatives Considered

{Are there better infrastructure approaches? Discuss alternatives like different AWS services, deployment strategies, monitoring tools, etc.}

#### Recommendations
1. {Specific recommendation}
2. {Specific recommendation}

#### Operational Checklist
- [ ] Monitoring/alerting considered
- [ ] Logging sufficient for debugging
- [ ] Graceful degradation planned
- [ ] Rollback strategy defined
- [ ] Resource requirements estimated

### Verdict: {APPROVED / APPROVED WITH CHANGES / NEEDS REVISION}

---

## Security Engineer Review

**Reviewer:** Cipher
**Focus Areas:** Authentication, authorization, input validation, data protection, OWASP

### Assessment

#### Strengths
- {Positive aspects from security perspective}

#### Concerns
- {Issues or risks identified}

#### Security Checklist
- [ ] Input validation adequate
- [ ] Authentication/authorization correct
- [ ] No sensitive data exposure
- [ ] No injection vulnerabilities
- [ ] Rate limiting considered
- [ ] Audit logging included

#### Recommendations
1. {Specific recommendation}
2. {Specific recommendation}

### Verdict: {APPROVED / APPROVED WITH CHANGES / NEEDS REVISION}

---

## SMTS Overall Review

**Reviewer:** Sage
**Focus Areas:** Architecture, code quality, maintainability, alignment with project goals

### Executive Summary

{2-3 sentence summary of the design and overall assessment}

### Architecture Assessment

- **Alignment with existing patterns:** {Good/Needs Work}
- **Maintainability:** {Good/Needs Work}
- **Scalability:** {Good/Needs Work}
- **Testability:** {Good/Needs Work}

### Cross-Cutting Concerns

{Issues that span multiple review areas}

### Final Recommendations

1. **Must Fix (Blockers):**
   - {Critical issues that must be addressed}

2. **Should Fix (Important):**
   - {Important issues to address before implementation}

3. **Consider (Nice to Have):**
   - {Suggestions for improvement}

### Overall Verdict: {APPROVED / APPROVED WITH CHANGES / NEEDS REVISION}

---

## Review Summary

| Reviewer | Verdict | Blockers | Key Concerns |
|----------|---------|----------|--------------|
| Frontend | {verdict} | {count} | {summary} |
| Backend | {verdict} | {count} | {summary} |
| SRE/DevOps | {verdict} | {count} | {summary} |
| Security | {verdict} | {count} | {summary} |
| SMTS | {verdict} | {count} | {summary} |

### Next Steps

1. {Action item}
2. {Action item}
3. {Action item}

### Sign-Off

- [ ] All blockers resolved
- [ ] Design updated based on feedback
- [ ] Ready for implementation

Important Guidelines

Design Principles

• Favor simple designs over unnecessary complexity
• Prefer straightforward code over clever solutions
• Design for maintainability by entry-level developers
• Add observability from the start, not as an afterthought

Documentation Quality

1. Be Thorough: The LLD should be detailed enough that someone unfamiliar with the codebase can implement it
2. Use Diagrams: ASCII diagrams help visualize the design
3. Include Code: Show actual or pseudo-code for key functions
4. Specify Files: Always mention which files to create/modify and approximate line numbers
5. Consider All Aspects: Think about error handling, logging, testing, and deployment
6. Expert Reviews: Make the reviews realistic - identify actual issues, not just praise

Example Usage

Example 1: User Description Mode

User: "Design a new feature for rate limiting on tool calls"

1. Ask clarifying questions about rate limiting requirements
2. Quick codebase review to understand existing architecture
3. Create .scratchpad/rate-limiting/
4. Write github-issue.md with rate limiting requirements
5. Deep codebase analysis of relevant services
6. Write lld.md with:
   • Architecture showing rate limiter component
   • Sequence diagram for rate-limited requests
   • Redis/in-memory counter data structures
   • API changes for rate limit headers
   • Middleware implementation details
   • Configuration options
7. Write review.md with expert feedback on:
   • Frontend: How to display rate limit info to users
   • Backend: Algorithm choice, storage considerations
   • SRE: Redis availability, monitoring needs
   • Security: Rate limit bypass prevention
   • SMTS: Overall architecture fit
8. Present summary and seek guidance on recommendations

Example 2: GitHub Issue URL Mode

User: "https://github.com/agentic-community/mcp-gateway-registry/issues/456"

1. Fetch issue #456 using gh issue view 456 --repo agentic-community/mcp-gateway-registry --json title,body,labels,state,comments
2. Analyze the issue content:
   • Extract: "Add support for federated registry syncing"
   • Found: Problem statement, some acceptance criteria
   • Missing: Specific sync frequency, conflict resolution strategy
3. Quick codebase review to understand registry architecture
4. Create .scratchpad/issue-456/ (folder named after the GitHub issue number)
5. Ask user only about gaps:
   • "The issue mentions syncing but doesn't specify frequency. What sync interval should we design for?"
   • "The issue discusses conflicts but doesn't specify resolution. Should we use last-write-wins or require manual resolution?"
6. Write github-issue.md summarizing the issue with clarifications
7. Deep codebase analysis of registry and storage layers
8. Write lld.md incorporating:
   • Requirements from original issue
   • Design elements proposed in issue comments
   • Clarifications from user
   • Technical details for implementation
9. Write review.md with expert feedback
10. Present summary noting:
    • What came from the original issue
    • What was clarified during design
    • Recommendations for implementation

Step 8: Present Summary & Seek Guidance

IMPORTANT: After completing the design documents and expert review, present a clear summary to the user and ask for guidance on addressing recommendations.

Summary Format

Present the following information in a clear, tabular format:

## Design Summary

### Documents Created

| Document | Location | Description |
|----------|----------|-------------|
| GitHub Issue | `.scratchpad/{feature}/github-issue.md` | Issue specification |
| Low-Level Design | `.scratchpad/{feature}/lld.md` | Technical design |
| Expert Review | `.scratchpad/{feature}/review.md` | Multi-persona review |

### Review Verdicts

| Reviewer | Verdict | Blockers | Key Recommendations |
|----------|---------|----------|---------------------|
| Frontend (Pixel) | {verdict} | {count} | {brief summary} |
| Backend (Byte) | {verdict} | {count} | {brief summary} |
| SRE (Circuit) | {verdict} | {count} | {brief summary} |
| Security (Cipher) | {verdict} | {count} | {brief summary} |
| SMTS (Sage) | {verdict} | {count} | {brief summary} |

### Configuration Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `PARAM_NAME` | type | value | {description} |

### New Dependencies

| Package/Resource | Type | Required By |
|------------------|------|-------------|
| `package-name` | Python | Backend |
| None | - | No new dependencies |

### New Tests Required

| Test File | Type | Coverage |
|-----------|------|----------|
| `tests/unit/test_feature.py` | Unit | Service layer |
| `tests/integration/test_feature.py` | Integration | End-to-end |

### Estimated Effort

| Category | Lines of Code |
|----------|---------------|
| New code | ~{X} |
| Tests | ~{X} |
| Modified | ~{X} |
| **Total** | **~{X}** |

Seeking Guidance

After presenting the summary, explicitly ask the user for guidance:

## Action Required

### Blockers (Must Address)

The following issues were identified as **blockers** and should be addressed before implementation:

1. {Blocker description from review}
2. {Blocker description from review}

**These will be incorporated into the LLD.**

### Recommendations (Need Your Input)

The following recommendations were made by reviewers. Please indicate which ones to incorporate:

| # | Recommendation | Reviewer | Priority | Incorporate? |
|---|----------------|----------|----------|--------------|
| 1 | {recommendation} | Backend | Should Fix | ? |
| 2 | {recommendation} | SRE | Should Fix | ? |
| 3 | {recommendation} | Security | Nice to Have | ? |

### Questions for You

1. Should I update the LLD to address the blockers and your selected recommendations?
2. Are there any additional requirements or constraints I should consider?
3. Would you like me to proceed with creating the GitHub issue?

Handling User Response

Based on user response:

1. If user wants LLD updates: Update the lld.md file with the agreed-upon changes
2. If user approves as-is: Proceed to offer GitHub issue creation
3. If user has additional feedback: Incorporate and regenerate affected sections

Alternative Approaches Discussion

If reviewers identified better alternatives, explicitly call this out:

### Alternative Approaches Identified

Reviewers suggested these alternative approaches that may be worth considering:

| Alternative | Proposed By | Trade-offs |
|-------------|-------------|------------|
| {approach} | {reviewer} | {pros/cons summary} |

Would you like me to explore any of these alternatives further?