critical-analysis-patterns

Original source / Raw SKILL.md

---
name: critical-analysis-patterns
description: Philosophical/meta project analysis - critical analysis framework that asks "why?"
allowed-tools: ["Read", "Glob", "Grep", "Task"]
---

# Critical Analysis Patterns

Beyond technical validation, analyze **alignment between intent and implementation**.

---

## Canonical Implementation Principle 📐

> **skillmaker aims for "canonical implementation" of plugins, agents, and marketplaces.**

### Active Recommendation

When analyzing projects, **actively recommend skillmaker's "good practices"** for similar/equivalent features:

| Domain | Canonical Pattern | Skill to Load |
|--------|------------------|---------------|
| MCP integration | Daemon SSE isolation | `mcp-gateway-patterns` |
| Skill structure | Progressive disclosure | `skill-design` |
| Agent design | Context isolation | `orchestration-patterns` |
| Behavior enforcement | Hookification | `hook-templates` |
| Multi-stage workflow | State files + gates | `workflow-state-patterns` |
| Skill discovery | Keyword triggers | `skill-activation-patterns` |

### When Project Uses Different Approach

If the project uses a different method, determine:

| Question | Verdict | Action |
|----------|---------|--------|
| "Is this approach inferior?" | Deficient | **Recommend canonical pattern** |
| "Is this a valid domain-specific choice?" | Respectable | **Acknowledge and document trade-offs** |
| "Is this actually better?" | Superior | **Learn from it, consider adopting** |

### Evaluation Criteria

```markdown
## Deficiency Indicators (recommend change)
- Reinventing what skillmaker already solved
- Missing enforcement (MUST keywords without hooks)
- Ignoring known anti-patterns
- Unnecessary complexity vs canonical approach

## Domain-Specific Indicators (respect choice)
- Different constraints that invalidate canonical approach
- Performance requirements that justify deviation
- Ecosystem compatibility requirements
- Documented rationale for deviation
```

### Example: MCP Analysis

When project uses MCP:

1. **Load**: `Skill("skillmaker:mcp-gateway-patterns")`
2. **Check**: Is Daemon SSE pattern being used?
3. **If not**: 
   - Is there a documented reason?
   - Does their approach handle subagent isolation?
   - Recommend Daemon pattern if deficient

## Core Questions (6 Questions)

Ask these questions for every component:

### 1. Existence Justification
```
- "Why is this here?"
- "What breaks if we remove it?"
- "Can it be replaced with something else?"
```

### 2. Intent-Implementation Alignment
```
- "Does the name reflect the actual role?"
- "Does declared purpose match actual behavior?"
- "Are documentation and code synchronized?"
```

### 3. Consistency
```
- "Are similar things being handled differently?"
- "Are patterns A and B mixed?"
- "Is exceptional handling justified?"
```

### 4. Unused Capabilities
```
- "Is there something declared but not used?"
- "Is there something implemented but never called?"
- "Why isn't it being used?"
```

### 5. Complexity Justification
```
- "Is this complexity truly necessary?"
- "Is there a simpler alternative?"
- "Is this over-engineering?"
```

### 6. Fundamental Redesign 🔥

> **"Idiots, this solves everything - why can't you see it?"**

Beyond conservative solutions (deletion, exceptions, workarounds), ask questions that **eliminate constraints themselves**:

```
- "If this problem keeps recurring, isn't the system itself wrong?"
- "Are we taking this constraint/limitation for granted?"
- "Is there a completely different approach?"
- "If there's a 10x better method, what is it?"
- "If we rebuilt this from scratch, how would we do it?"
```

**When to apply**:
- Same type of problem found 3+ times
- Conservative solution feels like a "band-aid"
- Feeling of "why is this so complicated?"

---

## Analysis Process

### Step 1: Component Inventory
```bash
# Collect all components
agents/*.md, skills/*/SKILL.md, commands/*.md, hooks/hooks.json
```

### Step 2: Relationship Mapping
| From | To | Relationship |
|------|----|--------------| 
| command | agent | invokes via Task |
| agent | skill | loads via Skill() or frontmatter |
| hook | agent/skill | triggers on events |

### Step 3: Apply Core Questions
Apply 6 questions to each component and discover inconsistencies

### Step 4: Organize Findings

## Output Format

```markdown
### Philosophical Analysis Results

| Finding | Question | Suggestion |
|---------|----------|------------|
| {what} | {why?} | {alternative} |
```

---

## Red Flags (Signals That Require Immediate Questioning)

| Signal | Question | Details |
|--------|----------|---------|
| In agents/ but tools: [] | "Is this an agent or documentation?" | `Read("references/intent-vs-implementation.md")` |
| Declared skills unused | "Why declared but not used?" | `Read("references/unused-capability-detection.md")` |
| 90%+ similar workflows separated | "Is there a reason not to consolidate?" | `Read("references/architectural-smell-catalog.md")` |
| 20+ Hooks | "Is this over-engineering?" | Complexity justification required |
| Components with overlapping responsibilities | "Are boundaries clear?" | Role redefinition required |
| Non-canonical pattern used | "Is skillmaker's canonical approach applicable?" | Load relevant skill and compare |

---

## Solution Synthesis

> **Diagnosis + Prescription = Consulting**

When problems are found, provide solutions at **two levels**:

### Level 1: Conservative Solutions

Solutions found within existing patterns/skills:

| Finding Pattern | Related Skill | Solution Reference |
|----------------|---------------|-------------------|
| MCP/Gateway issues | `mcp-gateway-patterns` | `references/daemon-shared-server.md` |
| Skill design issues | `skill-design` | `references/structure-rules.md` |
| Agent orchestration | `orchestration-patterns` | `references/context-isolation.md` |
| Hook related | `hook-templates` | `references/full-examples.md` |
| Workflow state | `workflow-state-patterns` | `references/complete-workflow-example.md` |

### Level 2: Radical Solutions 🔥

> **"If you're confident, propose it even if it's not in existing patterns"**

When conservative solutions feel like **band-aids**, consider:

| Situation | Radical Question | Possible Proposal |
|-----------|-----------------|-------------------|
| Same problem recurring | "Is the system structure wrong?" | **Full architecture redesign** |
| Exceptions outnumber rules | "Is the rule itself wrong?" | **Discard and redefine rules** |
| Complex workarounds | "Why not tackle it head-on?" | **Remove the constraint itself** |
| Compatibility band-aids | "What if we drop legacy?" | **Execute breaking change** |
| Slow improvements | "What if we rebuild from scratch?" | **Clean slate reconstruction** |

**Criteria for proposing radical solutions**:
1. First explain limits of conservative solution
2. Explicitly state trade-offs of radical solution
3. Indicate **confidence level** (High/Medium/Exploratory)
4. Provide concrete execution steps

**Output format**:
```markdown
### 🔥 Radical Solution: {proposal}

**Why this is right**:
{rationale - fundamental limits of existing approach}

**Trade-off**:
- Gains: {benefits}
- Losses: {costs}

**Confidence Level**: High | Medium | Exploratory

**Execution Steps**:
1. {step 1}
2. {step 2}
...
```

**Detailed process**: `Read("references/solution-synthesis.md")`

---

## Quick Checklist

Items to verify quickly during analysis:

- [ ] Do all agents/ actually function as agents?
- [ ] Do skill declarations match Skill() usage?
- [ ] Can similar Hooks be extracted into common patterns?
- [ ] Are there old architecture remnants in documentation?
- [ ] Can each component's existence be explained in one sentence?
- [ ] Does the project follow skillmaker's canonical patterns?
- [ ] If different approach used, is there documented rationale?


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/intent-vs-implementation.md

```markdown
# Intent vs Implementation Mismatch Patterns

의도와 구현이 불일치하는 일반적인 패턴들입니다.

## Pattern 1: 이름과 역할 불일치

### 증상
```
파일: agents/gateway.md
tools: []
실제 동작: MCP 도구를 직접 호출하지 않음, 문서 역할만 수행
```

### 질문
- "gateway라는 이름이 암시하는 역할과 실제 역할이 다르지 않은가?"
- "agents/ 디렉토리에 있어야 하는가?"

### 해결 방안
| 옵션 | 설명 |
|-----|-----|
| 역할 변경 | 실제 gateway 기능 구현 (MCP 호출 등) |
| 위치 변경 | docs/ 또는 references/로 이동 |
| 이름 변경 | 실제 역할을 반영하는 이름으로 변경 |

---

## Pattern 2: 선언과 동작 불일치

### 증상
```yaml
# frontmatter
skills: skill-a, skill-b, skill-c

# body
실제로 skill-a만 사용됨
skill-b, skill-c는 언급도 없음
```

### 질문
- "왜 skill-b, skill-c를 선언했는가?"
- "나중에 쓰려고 했다면 왜 아직 안 쓰는가?"
- "불필요하다면 왜 제거하지 않았는가?"

### 해결 방안
1. 실제 사용하는 스킬만 선언
2. 또는 선언한 스킬을 실제로 활용하는 로직 추가

---

## Pattern 3: 문서와 코드 비동기화

### 증상
```markdown
## Important: Use Gateway Pattern
모든 MCP 호출은 gateway를 통해야 합니다.

Task:
  agent: serena-gateway
  prompt: "..."
```

하지만 실제 아키텍처는:
- 메인 세션에서 직접 MCP 호출
- gateway는 더 이상 중개 역할 안 함

### 질문
- "아키텍처가 변경되었는데 문서는 왜 안 바뀌었는가?"
- "이 문서를 읽는 사람이 혼란스럽지 않겠는가?"

### 해결 방안
1. 문서를 현재 아키텍처에 맞게 업데이트
2. 구 아키텍처 섹션 완전 제거 (주석 처리도 안 됨)

---

## Pattern 4: 위치와 역할 불일치

### 일반적인 기대
| 위치 | 기대 역할 |
|-----|----------|
| agents/ | Task로 호출되는 독립 에이전트 |
| skills/ | Skill()로 로드되는 컨텍스트 |
| commands/ | /command로 실행되는 워크플로우 |
| docs/ | 참조 문서 |

### 불일치 예시
```
agents/documentation-only.md  # 실제론 문서
skills/executable-script/     # 실제론 에이전트처럼 동작
```

### 해결 방안
- 역할에 맞는 디렉토리로 이동
- 또는 역할을 디렉토리 의미에 맞게 변경

---

## Detection Checklist

분석 시 확인할 항목:

- [ ] 모든 agents/*.md가 tools: 필드에 도구를 가지고 있는가?
- [ ] frontmatter skills 선언과 본문 Skill() 사용이 일치하는가?
- [ ] 문서에 "구 방식", "이전 아키텍처" 언급이 없는가?
- [ ] 파일명/폴더명이 실제 역할을 반영하는가?

```

### references/unused-capability-detection.md

```markdown
# Unused Capability Detection

"있는데 왜 안 쓰지?"를 감지하는 패턴들입니다.

## Type 1: 선언된 미사용 스킬

### 감지 방법
```bash
# 1. frontmatter에서 skills 선언 추출
grep -r "^skills:" agents/ commands/

# 2. 본문에서 Skill() 사용 추출
grep -r "Skill(" agents/ commands/

# 3. 차집합 = 미사용 스킬
```

### 질문
- "선언만 하고 왜 안 쓰는가?"
- "미래 사용을 위한 것이라면 왜 주석이 없는가?"
- "정말 필요한 스킬인가?"

### 해결 방안
| 상황 | 조치 |
|-----|-----|
| 실수로 남음 | 제거 |
| 미래 사용 예정 | TODO 주석 추가 |
| 암묵적 의존 | 명시적 사용 추가 |

---

## Type 2: 미사용 에이전트

### 감지 방법
```bash
# 1. agents/ 목록
ls agents/*.md

# 2. Task 호출에서 참조되는 에이전트
grep -r "agent:" commands/ skills/
grep -r "subagent_type" commands/ skills/

# 3. 차집합 = 미사용 에이전트
```

### 질문
- "이 에이전트를 호출하는 곳이 있는가?"
- "독립 실행용이라면 어떻게 실행하는가?"
- "다른 에이전트에 통합되어야 하는 것은 아닌가?"

---

## Type 3: 미사용 Hook

### 감지 방법
```json
// hooks.json에 20개 Hook이 있지만
// 실제로 트리거되는 상황이 없는 Hook 존재
```

### 질문
- "이 Hook이 트리거되는 상황이 실제로 발생하는가?"
- "테스트해본 적 있는가?"
- "오버엔지니어링은 아닌가?"

---

## Type 4: 선언된 미사용 도구

### 증상
```yaml
# agent frontmatter
tools: ["Read", "Write", "Bash", "Grep", "Glob", "Task", "WebFetch"]

# 실제 본문
Read와 Task만 사용됨
```

### 질문
- "7개 도구를 선언했는데 2개만 쓰는 이유는?"
- "최소 권한 원칙을 위반하고 있지 않은가?"

### 해결 방안
- 실제 사용하는 도구만 선언
- 또는 선언한 도구를 활용하는 로직 추가

---

## Type 5: 미사용 references/

### 증상
```
skills/my-skill/
├── SKILL.md
└── references/
    ├── used.md      # SKILL.md에서 Read() 참조됨
    └── orphan.md    # 아무도 참조 안 함
```

### 감지 방법
```bash
# references/ 파일 목록
ls skills/*/references/

# SKILL.md에서 Read() 참조 추출
grep -r "Read(" skills/*/SKILL.md
```

### 질문
- "이 참조 문서는 누가 읽는가?"
- "더 이상 필요 없는 것은 아닌가?"

---

## Summary Table

| 유형 | 감지 방법 | 조치 |
|-----|----------|-----|
| 미사용 스킬 선언 | frontmatter vs Skill() 비교 | 제거 또는 사용 |
| 미사용 에이전트 | agents/ vs Task 호출 비교 | 제거 또는 통합 |
| 미사용 Hook | hooks.json 분석 | 제거 또는 테스트 |
| 미사용 도구 선언 | tools vs 본문 비교 | 최소화 |
| 미사용 references | Read() 참조 추적 | 제거 또는 연결 |

```

### references/architectural-smell-catalog.md

```markdown
# Architectural Smell Catalog

프로젝트에서 발견할 수 있는 "아키텍처 냄새" 카탈로그입니다.

## Smell 1: 과도한 유사성 (Excessive Similarity)

### 증상
```
inject-workflow와 refactor-workflow의 Hook 구조가 95% 동일
├── PreToolUse: 거의 동일한 검증 로직
├── PostToolUse: 거의 동일한 상태 관리
└── 차이점: 상태 파일 이름만 다름 (.inject-* vs .refactor-*)
```

### 질문
- "왜 통합하지 않았는가?"
- "의도적 분리라면 그 이유가 문서화되어 있는가?"
- "공통 패턴을 추출할 수 있지 않은가?"

### 해결 방안
| 옵션 | 설명 |
|-----|-----|
| 통합 | 공통 워크플로우로 합치기 |
| 추출 | 공통 패턴을 별도 스킬로 분리 |
| 문서화 | 분리 이유를 명확히 기록 |

---

## Smell 2: 책임 중복 (Responsibility Overlap)

### 증상
```
duplicate-detector 에이전트: "중복 코드 감지"
knowledge-graph 스킬: "중복 패턴 식별" 언급

→ 누가 실제로 중복을 감지하는가?
```

### 질문
- "책임의 경계가 명확한가?"
- "호출자가 어떤 것을 써야 할지 혼란스럽지 않은가?"
- "둘 다 필요한가?"

### 해결 방안
1. 각 컴포넌트의 책임을 한 문장으로 정의
2. 중복 영역 제거
3. 명확한 사용 가이드 작성

---

## Smell 3: 유령 컴포넌트 (Ghost Component)

### 증상
```
agents/gateway.md
├── tools: []
├── 본문: MCP 도구 사용 방법 설명
└── 실제: 아무것도 실행하지 않음

→ 에이전트처럼 보이지만 에이전트가 아님
```

### 질문
- "이것은 에이전트인가 문서인가?"
- "어디에 있어야 하는가?"
- "Task로 호출되는가?"

### 해결 방안
- 실제 에이전트 기능 구현
- 또는 docs/references로 이동

---

## Smell 4: 과잉 복잡성 (Overcomplexity)

### 증상
```
hooks.json: 20+ 규칙
├── PreToolUse: 10개
├── PostToolUse: 8개
├── Stop: 2개
└── 실제 필요한 동작: 5개 정도
```

### 질문
- "이 복잡성이 정말 필요한가?"
- "각 Hook이 실제로 트리거되는가?"
- "YAGNI 원칙을 위반하고 있지 않은가?"

### 해결 방안
1. 각 Hook의 필요성 검증
2. 트리거되지 않는 Hook 제거
3. 유사한 Hook 통합

---

## Smell 5: 구 아키텍처 잔재 (Legacy Remnants)

### 증상
```markdown
## Important: Use Gateway Pattern (구 아키텍처)

모든 MCP 호출은 gateway를 통해야 합니다...

↑ 하지만 현재는 Data Delegation 패턴 사용
```

### 질문
- "이 문서가 현재 아키텍처를 반영하는가?"
- "새 개발자가 이것을 보면 혼란스럽지 않겠는가?"
- "언제 업데이트할 것인가?"

### 해결 방안
- 구 아키텍처 섹션 완전 제거
- 현재 아키텍처로 교체
- 마이그레이션 노트는 별도 문서로

---

## Smell 6: 암묵적 의존성 (Implicit Dependencies)

### 증상
```
에이전트 A가 에이전트 B의 출력 형식에 의존
하지만 어디에도 이 의존성이 문서화되어 있지 않음
```

### 질문
- "B가 변경되면 A가 깨지는가?"
- "이 의존성을 명시적으로 선언했는가?"
- "인터페이스 계약이 있는가?"

### 해결 방안
1. 의존성 명시적 문서화
2. 인터페이스/스키마 정의
3. 또는 의존성 제거

---

## Smell 7: 과잉 추상화 (Over-Abstraction)

### 증상
```
한 번만 사용되는 스킬이 별도 디렉토리로 분리됨
├── skills/one-time-use/
│   ├── SKILL.md
│   └── references/
└── 사용처: agents/single-agent.md 에서만 사용
```

### 질문
- "이 추상화가 재사용되는가?"
- "인라인으로 충분하지 않은가?"
- "분리의 이점이 비용을 상회하는가?"

---

## Detection Priority

| 우선순위 | Smell | 영향 |
|---------|-------|-----|
| HIGH | 책임 중복 | 사용자 혼란, 유지보수 어려움 |
| HIGH | 구 아키텍처 잔재 | 잘못된 구현 유도 |
| MEDIUM | 유령 컴포넌트 | 구조 혼란 |
| MEDIUM | 과잉 유사성 | 코드 중복, 불일치 위험 |
| LOW | 과잉 복잡성 | 유지보수 비용 |
| LOW | 과잉 추상화 | 불필요한 인디렉션 |

```

### references/solution-synthesis.md

```markdown
# Solution Synthesis Framework

문제 발견에서 그치지 않고, **skillmaker의 전체 지식 베이스를 활용해 해결책을 종합**합니다.

---

## 핵심 원칙

> **진단 + 처방 = 컨설팅**

| 단계 | 현재 Wizard | 현명한 Wizard |
|------|-------------|---------------|
| 1 | 문제 발견 | 문제 발견 |
| 2 | "이런 문제가 있습니다" | **왜** 이런 문제가 생겼는지 분석 |
| 3 | (끝) | 어느 스킬에서 **이 패턴을 다루는지** 식별 |
| 4 | - | 해당 스킬의 **해결책** 추출 |
| 5 | - | **구현 방법** 제안 |
| 6 | - | "실행할까요?" 제안 |

---

## Problem-Solution Mapping

발견된 문제를 skillmaker 스킬과 연결합니다.

### MCP 관련 문제

| 발견 | 패턴 인식 | 관련 스킬 | 해결책 |
|------|----------|----------|--------|
| "Gateway 패턴 실패" | MCP 접근 제약 | `mcp-gateway-patterns` | Daemon SSE 패턴 |
| "서브에이전트 MCP 접근 불가" | Claude Code 제약 | `mcp-gateway-patterns` | 데이터 위임 또는 Daemon |
| "MCP 30-60초 시작 지연" | Subprocess 오버헤드 | `mcp-gateway-patterns` | Daemon SSE (1-2초) |
| "MCP 토큰 오버헤드" | 도구 정의 비용 | `mcp-gateway-patterns` | Subprocess/Daemon 격리 |

**해결책 로드**:
```
Skill("skillmaker:mcp-gateway-patterns")
→ Read("references/daemon-shared-server.md")
```

### 스킬 설계 문제

| 발견 | 패턴 인식 | 관련 스킬 | 해결책 |
|------|----------|----------|--------|
| "SKILL.md 500단어 초과" | Progressive disclosure 위반 | `skill-design` | references/ 분리 |
| "frontmatter 누락" | 메타데이터 부재 | `skill-design` | 필수 필드 추가 |
| "skills 선언 미사용" | 미사용 기능 | `skill-design` | Skill() 호출 또는 선언 제거 |

**해결책 로드**:
```
Skill("skillmaker:skill-design")
→ Read("references/structure-rules.md")
```

### 에이전트 오케스트레이션 문제

| 발견 | 패턴 인식 | 관련 스킬 | 해결책 |
|------|----------|----------|--------|
| "에이전트에 tools: []" | 역할 혼동 | `orchestration-patterns` | 문서 vs 에이전트 재분류 |
| "Skill() 호출 없이 참조" | 스킬 로딩 누락 | `orchestration-patterns` | 명시적 Skill() 추가 |
| "다단계 워크플로우 스킬 미분리" | 컨텍스트 비효율 | `orchestration-patterns` | 단계별 스킬 로딩 |

**해결책 로드**:
```
Skill("skillmaker:orchestration-patterns")
→ Read("references/context-isolation.md")
```

### Hook 관련 문제

| 발견 | 패턴 인식 | 관련 스킬 | 해결책 |
|------|----------|----------|--------|
| "MUST/CRITICAL 키워드 but no hook" | Hookify 미준수 | `hook-templates` | PreToolUse hook 추가 |
| "Hook blocking/informational 혼재" | 정책 불일치 | `hook-templates` | 정책 통일 |
| "Hook 20개+" | 오버엔지니어링 | `hook-templates` | Hook 통합/간소화 |

**해결책 로드**:
```
Skill("skillmaker:hook-templates")
→ Read("references/full-examples.md")
```

### 워크플로우 상태 문제

| 발견 | 패턴 인식 | 관련 스킬 | 해결책 |
|------|----------|----------|--------|
| "다단계 워크플로우 상태 추적 없음" | 상태 파일 미사용 | `workflow-state-patterns` | .{workflow}-*-done 파일 |
| "Plan auto-approved" | 게이트 우회 | `workflow-state-patterns` | 명시적 승인 게이트 |

**해결책 로드**:
```
Skill("skillmaker:workflow-state-patterns")
→ Read("references/complete-workflow-example.md")
```

---

## Solution Synthesis Process

### Step 1: 문제 분류

```python
def classify_problem(finding: str) -> list[str]:
    """발견된 문제를 관련 스킬로 분류"""

    mappings = {
        "mcp|gateway|subprocess|daemon|서브에이전트.*mcp": ["mcp-gateway-patterns"],
        "skill.*design|progressive|frontmatter|references/": ["skill-design"],
        "agent|orchestration|tools:\\s*\\[\\]|Skill\\(\\)": ["orchestration-patterns"],
        "hook|PreToolUse|PostToolUse|MUST|CRITICAL": ["hook-templates"],
        "workflow|phase|stage|state|gate": ["workflow-state-patterns"],
        "activation|trigger|keyword": ["skill-activation-patterns"],
    }

    return [skill for pattern, skills in mappings.items()
            if re.search(pattern, finding, re.I)]
```

### Step 2: 관련 스킬 로드

발견된 문제에 따라 자동으로 스킬 로드:

```
For each classified_skill:
    Skill("skillmaker:{classified_skill}")
```

### Step 3: 해결책 추출

각 스킬에서 관련 reference 로드:

```markdown
## 해결책: {problem_name}

**문제**: {what was found}

**원인**: {why this happened - from skill knowledge}

**해결책**: {specific solution from skill}

**구현**:
```bash
{concrete steps}
```

**상세**: `Read("references/{relevant-file}.md")`
```

### Step 4: 실행 제안

```yaml
AskUserQuestion:
  question: "어떤 해결책을 적용할까요?"
  header: "Action"
  multiSelect: true
  options:
    - label: "{Solution 1}"
      description: "{brief description}"
    - label: "{Solution 2}"
      description: "{brief description}"
    - label: "모두 적용"
      description: "모든 권장 해결책 적용"
    - label: "나중에"
      description: "지금은 분석만"
```

---

## 출력 형식

### 철학적 분석 + 해결책 종합

```markdown
## 프로젝트 분석: {project-name}

### 발견된 문제

| # | 발견 | 분류 | 심각도 |
|---|------|------|--------|
| 1 | {finding 1} | {skill category} | 🔴 HIGH |
| 2 | {finding 2} | {skill category} | 🟡 MEDIUM |

---

### 해결책 종합

#### 🔴 문제 1: {finding 1}

**왜 이런 문제가 생겼는가?**
{root cause analysis from skillmaker knowledge}

**관련 지식**: `Skill("skillmaker:{relevant-skill}")`

**해결책**:
{specific solution}

**구현 방법**:
```bash
{concrete steps}
```

**상세 참조**: `Read("references/{file}.md")`

---

#### 🟡 문제 2: {finding 2}

...

---

### 실행 제안

다음 해결책을 적용할 수 있습니다:

1. [ ] {Solution 1} - 예상 영향: {impact}
2. [ ] {Solution 2} - 예상 영향: {impact}

**진행하시겠습니까?**
```

---

## 예시: serena-refactor 분석

### 발견

| # | 발견 | 분류 | 심각도 |
|---|------|------|--------|
| 1 | serena-gateway가 에이전트가 아닌 문서 | orchestration-patterns | 🔴 HIGH |
| 2 | 4개 에이전트가 작동 불가한 Gateway 패턴 참조 | mcp-gateway-patterns | 🔴 HIGH |
| 3 | Hook blocking/informational 불일치 | hook-templates | 🟡 MEDIUM |

### 해결책 종합

#### 🔴 문제 1-2: Gateway 패턴 실패

**왜 이런 문제가 생겼는가?**

Claude Code의 서브에이전트(Task)는 MCP 도구에 접근할 수 없습니다. 이는 Claude Code의 근본적 제약입니다.

원래 설계:
```
Main Session → Task: serena-gateway → mcp__serena__* 호출
```

실제 동작:
```
Main Session → Task: serena-gateway → MCP 도구 없음 (실패)
```

**관련 지식**: `Skill("skillmaker:mcp-gateway-patterns")`

**해결책**: Daemon SSE 패턴

```bash
# 1. Serena를 HTTP 데몬으로 시작
serena start-mcp-server --transport sse --port 8765 &

# 2. Claude Code에 등록
claude mcp add --transport sse serena-daemon http://127.0.0.1:8765

# 3. 모든 세션/서브프로세스에서 공유
```

**이점**:
- 시작 시간: 30-60초 → 1-2초
- 토큰 오버헤드: 메인 세션 0
- 상태 공유: 가능

**상세**: `Read("references/daemon-shared-server.md")`

---

#### 🟡 문제 3: Hook 정책 불일치

**관련 지식**: `Skill("skillmaker:hook-templates")`

**해결책**: 정책 통일

| 현재 | 제안 |
|------|------|
| blocking + informational 혼재 | 워크플로우 게이트는 모두 blocking |

**구현**: hooks/hooks.json에서 모든 게이트 hook을 `exit 1` (blocking)으로 통일

---

### 실행 제안

1. [ ] **serena-gateway 역할 재정의** - docs/로 이동 또는 에이전트로 재설계
2. [ ] **Daemon SSE 패턴 적용** - MCP 접근 문제 해결
3. [ ] **구 Gateway 참조 제거** - 4개 에이전트 문서 갱신
4. [ ] **Hook 정책 통일** - blocking으로 일원화

**진행하시겠습니까?**

---

## Level 2: Radical Solutions 🔥

> **"If you're confident, propose it even if it's not in existing patterns"**
> **"Idiots, this solves everything - why can't you see it?"**

When conservative solutions feel like **band-aids**, propose paradigm-shifting alternatives.

### When to Propose Radical Solutions?

| Signal | Meaning | Radical Approach |
|--------|---------|------------------|
| Same problem 3+ times | System structure issue | **Architecture redesign** |
| Exceptions outnumber rules | Rule itself is wrong | **Discard rules** |
| Workaround more complex than normal path | Constraint is irrational | **Remove constraint** |
| "That's just how it is" response | Law of inertia | **Review from first principles** |
| Compatibility cost > value | Legacy debt | **Breaking change** |

### Radical Questions Framework

```markdown
## 1. Constraint Dissolution
- "Who created this constraint? Why?"
- "What would we do without this constraint?"
- "Is the situation that created this constraint still valid?"

## 2. First Principles
- "If we redefine this problem from scratch?"
- "What is physically/logically impossible?"
- "If it's physically possible, why aren't we doing it?"

## 3. 10x Thinking
- "If there's a 10x better method, what is it?"
- "What if the current method is completely wrong?"
- "How would a competitor build this from scratch?"

## 4. Inversion
- "What happens if we don't solve this problem?"
- "How would we make this problem worse?" (do the opposite)
- "When would this feature be unnecessary?"
```

### Radical Solution Output Format

```markdown
### 🔥 Radical Solution: {proposal}

**Fundamental limits of current approach**:
{why conservative solutions won't work}

**Proposal**:
{paradigm shift or structural redesign}

**Why this is right**:
- {rationale 1}
- {rationale 2}
- {rationale 3}

**Trade-off**:
| Gains | Losses |
|-------|--------|
| {benefit 1} | {cost 1} |
| {benefit 2} | {cost 2} |

**Confidence Level**: 🟢 High | 🟡 Medium | 🔴 Exploratory

**Execution Steps**:
1. {step 1}
2. {step 2}
3. {step 3}

**Expected Impact**:
- Short-term: {immediate impact}
- Long-term: {long-term benefit}
```

### Radical Solution Examples

#### Example 1: Gateway Pattern Failure

**Conservative solution**: Workaround with Daemon SSE pattern
**Radical solution**: 

```markdown
### 🔥 Radical Solution: Discard Gateway Concept Entirely

**Fundamental limits of current approach**:
Gateway pattern assumes "centralized MCP access", but
Claude Code's subagent isolation invalidates this premise.
Daemon pattern is ultimately "a workaround to save Gateway".

**Proposal**:
Discard Gateway concept and transition to **MCP-free architecture**.
- Analyze all MCP dependencies
- For each dependency: is MCP really necessary?
- Alternatives: CLI wrapper, REST API, direct library calls

**Why this is right**:
- MCP is convenience, not necessity
- Complete elimination of MCP overhead (startup time, tokens)
- Subagent isolation problem solved at source

**Trade-off**:
| Gains | Losses |
|-------|--------|
| 0-second startup | MCP ecosystem compatibility |
| 0 token overhead | Tool autocomplete |
| Architecture simplification | MCP-based extensibility |

**Confidence Level**: 🟡 Medium (depends on project dependencies)

**Execution Steps**:
1. Extract list of MCP tool usage
2. Analyze alternatives for each tool (CLI? API? Library?)
3. Start migration with lowest-cost alternatives
4. Progressively remove MCP dependencies
```

#### Example 2: Hook Over-Complexity

**Conservative solution**: Consolidate hooks, remove unnecessary hooks
**Radical solution**:

```markdown
### 🔥 Radical Solution: Replace Hook System with LLM Self-Control

**Fundamental limits of current approach**:
Hooks assume "we don't trust the LLM".
As hooks increase, system complexity grows.
Eventually, hook management becomes a bigger problem than the original issue.

**Proposal**:
Minimize hooks and replace with **enhanced system prompts**.
- Only use hooks for things that truly need blocking
- Solve the rest with clear instructions + examples

**Why this is right**:
- Modern LLMs (Claude 3.5+) have very high instruction compliance rates
- Hook debugging cost > occasional violation cost
- Dramatic reduction in system complexity

**Confidence Level**: 🟡 Medium (depends on organization's policy on LLM trust)
```

### Rules for Proposing Radical Solutions

1. **Always present conservative solution first**
2. **Explicitly state limits** of conservative solution
3. **Honestly disclose trade-offs** of radical solution
4. **Indicate confidence level** (🟢/🟡/🔴)
5. **Choice belongs to user** - don't force
6. Radical ≠ irresponsible. **Concrete execution steps are mandatory**

---

## Automatic Skill Loading Rules

Auto-load skills when following patterns detected during analysis:

| Detection Pattern | Auto-Load |
|-------------------|-----------|
| MCP tool usage attempted | `mcp-gateway-patterns` |
| agents/ directory exists | `orchestration-patterns` |
| skills/ directory exists | `skill-design` |
| hooks/ directory exists | `hook-templates` |
| Multi-stage workflow | `workflow-state-patterns` |
| Gateway/Subprocess mentioned | `mcp-gateway-patterns` |

```