# 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

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

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?

.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

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

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

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

# 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

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

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

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

{
    "field": "value"
}

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

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

# Add to pyproject.toml
uv add package-name

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

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

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)

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

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

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

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