# New Feature Design

> Design and document new features with GitHub issue, low-level design (LLD), expert review, and testing plan. Creates structured documentation in .scratchpad/ with issue spec, technical design with diagrams and pseudo-code, multi-persona expert review, and a testing plan covering functional (curl and registry_management.py), backwards-compatibility, UX, ECS/terraform, and E2E API tests. Supports starting from a user description OR an existing GitHub issue URL. Folder naming: issue-{number}/ for existing issues, {feature-name}/ for new features.

- Skill: `agentic-community/new-feature-design` (Agent Skill)
- Install (CLI): `npx skillmds@latest add agentic-community/new-feature-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/agentic-community/new-feature-design/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- License: Apache-2.0
- Author: agentic-community (https://skillmd.com/u/agentic-community)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/agentic-community/new-feature-design

---


# 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. **Write Testing Plan** - Create `testing.md` with functional, backwards-compat, UX, ECS, and E2E tests
9. **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. **Write Testing Plan** - Create `testing.md` with functional, backwards-compat, UX, ECS, and E2E tests
11. **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:

```bash
# 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:

```markdown
# 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
└── testing.md         # Testing plan (functional, backwards-compat, UX, ECS, E2E)
```

## 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)

```markdown
# 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:

```markdown
# 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.

> **REQUIRED: theory alignment.** Read [Theory of the System](../../../docs/design/theory-of-the-system.md)
> and check the proposed feature against its core invariants (single control plane for all asset
> types; the gateway is a generic reverse proxy and the registry is the control plane; registry is
> control-plane-not-data-path for A2A; `DEPLOYMENT_MODE` vs `REGISTRY_MODE`; three-surface config
> parity; fail-closed admission vs fail-open notification; IdP-agnostic across a closed provider
> factory; MCP spec compliance). Use the doc's
> "[how to change this system without breaking its theory](../../../docs/design/theory-of-the-system.md#6-how-to-change-this-system-without-breaking-its-theory)"
> checklist. **If the design would violate an invariant, flag it explicitly to the user** in the
> LLD (a "Theory impact" note) and in the Expert Review — a deliberate theory change is allowed, but
> it must be called out and argued, never slipped in. State which invariant is affected and the
> justification.

### 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.

```markdown
# 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}

### Theory Impact
{State whether this feature upholds or changes any core invariant in
[Theory of the System](../../../docs/design/theory-of-the-system.md). Default: "No invariant
affected." If an invariant IS affected, name it, explain why the change is deliberate and
justified, and note the consequence — this is a flag for the reviewer, not something to bury.}

## 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}

```python
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}

### Data Access Plan (avoid N+1)
{For each read path the feature introduces, state how the data is fetched.
Any time you need a count or lookup over a list of items, design a single bulk
query or aggregation (`$group`/`$sum`/`$in`/batched fetch) rather than one
query per item. Do NOT design a `for` loop that awaits a repository call per
element. If a per-item read seems unavoidable, justify why and bound the item
count. Note any new repository method (e.g. a `count_*` aggregation) the design
needs so it does not fall back to loading and counting in Python.}

## API Design

### New Endpoints

#### POST /api/v1/{endpoint}

**Description:** {What this endpoint does}

**Request:**
```json
{
    "field": "value"
}
```

**Response (200 OK):**
```json
{
    "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`:

```python
    # 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}

### Deployment Surface Checklist

**CRITICAL:** Every new configuration parameter must be propagated to all three deployment surfaces AND documented in the unified parameter reference. Use the checklist below and fill in the file-level details for each new parameter.

#### Unified Parameter Reference (must be updated for every new parameter)

The project maintains a single cross-surface mapping of every parameter at [`docs/unified-parameter-reference.md`](../../../docs/unified-parameter-reference.md). This is the authoritative index for how each logical parameter is named on each surface. **You must update it** whenever a parameter is added, renamed, removed, or re-scoped.

| File | What to Add | Done? |
|------|-------------|-------|
| `docs/unified-parameter-reference.md` | Add one row per new parameter to the correct logical group table: parameter name, Docker `.env` var, Terraform `.tfvars` var, Helm values path, purpose. Mark secrets with **(secret)**. If no existing group fits, add a new group section and explain why in the PR description. If a surface legitimately does not expose the parameter, leave the cell blank and note the reason in the PR. | [ ] |

Verification: `grep` the new variable name across [`.env.example`](../../../.env.example), [`terraform/aws-ecs/terraform.tfvars.example`](../../../terraform/aws-ecs/terraform.tfvars.example), [`charts/`](../../../charts/), AND `docs/unified-parameter-reference.md` — it must appear in all surfaces that the reference file claims it does.

#### Docker Deployment (5 files)

| File | What to Add | Done? |
|------|-------------|-------|
| `.env.example` | Variable with description and default value | [ ] |
| `.env` | Variable with the actual deployment value | [ ] |
| `docker-compose.yml` | Pass variable to the correct service(s) environment block | [ ] |
| `docker-compose.podman.yml` | Same as above (Podman variant) | [ ] |
| `docker-compose.prebuilt.yml` | Same as above (prebuilt-image variant) | [ ] |

#### Terraform / ECS Deployment (5+ files)

| File | What to Add | Done? |
|------|-------------|-------|
| `terraform/aws-ecs/variables.tf` | Root variable definition with description and default | [ ] |
| `terraform/aws-ecs/main.tf` | Pass the variable into the module call | [ ] |
| `terraform/aws-ecs/modules/mcp-gateway/variables.tf` | Module-level variable definition | [ ] |
| `terraform/aws-ecs/modules/mcp-gateway/ecs-services.tf` | Map variable to container environment in ECS task definition | [ ] |
| `terraform/aws-ecs/terraform.tfvars.example` | Documented example value | [ ] |

Sensitive values (tokens, private keys) must use AWS Secrets Manager references.

#### Helm / EKS Deployment (4 files)

| File | What to Add | Done? |
|------|-------------|-------|
| `charts/registry/values.yaml` (or the correct subchart) | Default value under the appropriate section | [ ] |
| `charts/mcp-gateway-registry-stack/values.yaml` | Default value (stack-level chart) | [ ] |
| `charts/<subchart>/templates/secret.yaml` | Add variable if sensitive (base64-encoded), plus support `existingSecret` / `secretKeyRef` | [ ] |
| `charts/<subchart>/templates/deployment.yaml` | Map value to container env var (plain or `secretKeyRef`) | [ ] |

Sensitive values must support `secretKeyRef` for Kubernetes secrets.

#### System Config Page (Backend API + Frontend UI)

New config params must appear on the System Config page in the UI. This requires backend and possibly frontend changes.

| File | What to Add | Done? |
|------|-------------|-------|
| `registry/api/config_routes.py` | Add field to `CONFIG_GROUPS` dict with `(field_name, display_label, is_sensitive)`. Sensitive fields must have `is_sensitive=True` so they are masked via `_mask_sensitive_value()`. | [ ] |
| Frontend (`ConfigPanel.tsx`) | Auto-renders fields from `/api/config/full`. Update only if the new parameters need special UI treatment (toggles, grouped display, color-coded status, etc.). | [ ] |

Verify after deployment: navigate to the System Config page and confirm the new parameter(s) appear with correct values and labels. Sensitive values should be masked. The same data is also available programmatically via `GET /api/config/full` (admin auth required) and can be exported via `GET /api/config/export?format={env|json|tfvars|yaml}`.

## 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

```bash
# 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"}

```python
# 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 |

### API Client Updates (IMPORTANT)

**When new API endpoints are added or modified, the following files MUST also be updated:**

| File Path | Update Required |
|-----------|-----------------|
| `api/registry_client.py` | Add Pydantic response models and client methods for new endpoints |
| `api/registry_management.py` | Add CLI commands (argparse parsers) and handler functions |
| `api/openapi.json` | Regenerate OpenAPI spec if using auto-generation |

**Example additions for a new endpoint `GET /api/feature/{path}/data`:**

```python
# In api/registry_client.py:
class FeatureDataResponse(BaseModel):
    """Response model for feature data endpoint."""
    path: str = Field(..., description="Feature path")
    data: dict = Field(..., description="Feature data")

def get_feature_data(self, path: str) -> FeatureDataResponse:
    """Get feature data from the registry."""
    response = self._make_request("GET", f"/api/feature/{path}/data")
    return FeatureDataResponse(**response)

# In api/registry_management.py:
def cmd_feature_data(args: argparse.Namespace) -> None:
    """Get feature data command handler."""
    client = _get_client(args)
    result = client.get_feature_data(path=args.path)
    # Display result...
```

This ensures the registry management CLI stays in sync with backend API capabilities.

### 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:

```python
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}

#### N+1 Access Pattern Check (MANDATORY)
Inspect every data-access path in the design. Flag any pattern that reads from
a database or data source once per item (a `count()` / `find_one()` / `get()` /
`distinct()` or repository call inside a `for`/`while`/comprehension/per-item
callback, or a service that internally queries per element). State the fix: a
single bulk query or aggregation (`$group`/`$sum`/`$in`/batched fetch) outside
the loop. `asyncio.gather` over a per-item list is still N+1 round-trips; flag
it unless the item count is small and bounded.
- **N+1 patterns:** {None found / FLAGGED: <where + the per-item read and the bulk-query fix>}

#### 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

> **Before writing this section, read [security-patterns.md](../pr-review/personas/security-patterns.md)** — the catalog of security defects that have shipped and been fixed in this project. Design the feature so it does not reintroduce any of them (SSRF on outbound fetches, broken access control / info disclosure on new endpoints, weak defaults, token-boundary confusion, missing CSRF, injection, log/secret leakage, agent execution safety). Call out in the Concerns/Recommendations below which patterns this feature touches and how the design avoids them.

### Assessment

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

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

#### Security Checklist
See [security-patterns.md#review-checklist](../pr-review/personas/security-patterns.md#review-checklist) for the full per-pattern list. Key items:
- [ ] Outbound fetches of stored/request-supplied URLs go through the SSRF guard (pattern #1)
- [ ] New GET endpoints strip backend URLs for non-admins; mutations 404-then-403 on resolved identity (pattern #2)
- [ ] No new secret ships with a working default; new env vars added to reserved-name + weak-secret lists (pattern #3)
- [ ] Inbound auth headers stripped on egress; JWTs verified; no client-supplied session id trusted (pattern #4)
- [ ] Every mutating endpoint carries the CSRF dependency (pattern #5)
- [ ] No untrusted input interpolated into nginx/query/HTML/href without escaping (pattern #6)
- [ ] No secrets/headers/OIDC claim values logged; secret fields write-only in responses (pattern #7)
- [ ] Mutating agent tools gated behind confirmation; agent endpoints authenticate (pattern #9)

#### 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 

…(truncated)