debug

maestro:debug

설정된 AI 팀원들이 병렬로 버그를 조사하고 PM(Claude)이 결과를 합쳐 종합 디버그 리포트를 생성합니다. Maestro 모드 활성 여부에 관계없이 사용 가능합니다.

ideation/discussion과의 차이

	ideation	discussion	debug
목적	다양한 관점 수집 (발산)	합의 도달 (수렴)	버그 탐지 (조사)
Claude 역할	종합자 (PM)	사회자 (PM)	종합자 (PM)
에이전트 역할	의견 제시	토론 참여	독립 조사 → 결과 문서
라운드	1회	N회 반복	1회 (병렬 조사 후 합류)
종료 조건	PM 종합 완료	참여자 합의	에이전트 합류 완료
출력	synthesis.md	consensus.md	debug-report.md

실행 프로토콜

경로 규칙 (MANDATORY): 이 스킬의 모든 .gran-maestro/ 경로는 절대경로로 사용합니다. 스킬 실행 시작 시 PROJECT_ROOT를 취득하고, 이후 모든 경로에 {PROJECT_ROOT}/ 접두사를 붙입니다.

PROJECT_ROOT=$(pwd)

{PLUGIN_ROOT}는 이 스킬의 "Base directory"에서 skills/{스킬명}/을 제거한 절대경로입니다. 상대경로(.claude/...)는 절대 사용하지 않습니다.

MANDATORY Read: ~/.claude/user-profile.json (AskUserQuestion 컨텍스트, 비차단)

1. ~/.claude/user-profile.json을 Read한다.
   • 파일이 없으면 user_profile_context = null로 처리하고 기존 동작을 유지한다 (graceful fallback).
2. 파일이 있으면 JSON을 파싱하고 아래 필드만 사용한다.
   • role (string)
   • experience_level (string)
   • domain_knowledge (string[])
   • communication_style (string)
3. JSON 파싱 실패 또는 타입 불일치 시 warn만 출력하고 user_profile_context = null로 처리한다 (워크플로우 차단 금지).
4. 이후 AskUserQuestion과 사용자 설명 텍스트 작성 시:
   • communication_style을 최우선 반영한다.
   • experience_level/domain_knowledge에 맞춰 용어 수준과 설명 깊이를 조절한다.
   • 누락 필드는 추정하지 않고, 존재하는 필드만 참고한다.

Step 1: 초기화

1. {PROJECT_ROOT}/.gran-maestro/debug/ 디렉토리 존재 확인, 없으면 생성
2. 새 세션 ID 채번 (DBG-NNN):
   • 스크립트 우선: python3 {PLUGIN_ROOT}/scripts/mst.py counter next --type dbg → 출력 ID 사용
   • Fallback (counter.json 기반):
     • {PROJECT_ROOT}/.gran-maestro/debug/counter.json 파일 Read
     • 파일 존재 시: next_id = last_id + 1
     • 파일 미존재 시 (최초 또는 복구): a. {PROJECT_ROOT}/.gran-maestro/debug/ 하위의 기존 DBG-* 디렉토리 스캔 b. {PROJECT_ROOT}/.gran-maestro/archive/ 내 debug-* tar.gz 파일명에서 ID 범위 추출 c. 모든 소스에서 최대 번호 결정 → counter.json 생성: { "last_id": {max_number} } d. next_id = last_id + 1
     • counter.json 업데이트: { "last_id": {next_id} }
3. {PROJECT_ROOT}/.gran-maestro/debug/DBG-NNN/ 디렉토리 생성 (NNN은 3자리 zero-padded)
4. session.json 작성:

⏱️ 타임스탬프 취득 (MANDATORY): TS=$(python3 {PLUGIN_ROOT}/scripts/mst.py timestamp now) 위 명령 실패 시 폴백: python3 -c "from datetime import datetime, timezone; print(datetime.now(timezone.utc).isoformat())" 출력값을 created_at 필드에 기입한다. 날짜만 기입 금지.

{
  "id": "DBG-NNN",
  "issue": "{사용자 이슈 설명}",
  "focus": "{--focus 값 또는 null}",
  "status": "analyzing",
  "created_at": "{TS — mst.py timestamp now 출력값}",
  "dispatch_started_at": null,
  "investigators": {
    "codex": { "role": "", "status": "pending", "provider": "codex", "started_at": null, "completed_at": null },
    "gemini": { "role": "", "status": "pending", "provider": "gemini", "started_at": null, "completed_at": null }
  },
  "participant_config": { "codex": 1, "gemini": 1, "claude": 0 },
  "merge_wait_ms": 60000,
  "fix_attempts": {
    "total_attempts": 0,
    "consecutive_failures": 0,
    "last_request_id": null,
    "last_result": null,
    "last_checked_at": null,
    "architect_escalation": {
      "triggered": false,
      "triggered_at": null,
      "status": "pending",
      "reason": null,
      "output_file": null
    }
  }
}

investigators는 config의 debug.agents를 읽어 생성합니다.

investigators 동적 생성 규칙

1. 각 provider(codex, gemini, claude)의 count 읽기
2. count == 1 → 키 이름은 provider 그대로
3. count > 1 → 첫 번째는 {provider}, 이후는 {provider}-2, {provider}-3 ...
4. 각 항목에 provider 필드 기록
5. 합계 검증: 1~6명, 위반 시 에러 후 중단

debug.agents 키 없으면 기본값 { codex:1, gemini:1, claude:0 } 사용.

fix_attempts 추적 규칙

1. Step 7에서 /mst:request --from-debug {DBG-NNN} 실행이 종료될 때마다 fix_attempts를 갱신합니다.
2. 판정 기준 (판정 소스: {PROJECT_ROOT}/.gran-maestro/requests/{last_request_id}/request.json의 status 필드):
   • 성공: request.json.status가 done, completed, 또는 accepted인 경우
   • 실패: Skill 호출 에러/중단, 또는 request.json.status가 위 값이 아닌 경우 (예: failed, cancelled)
3. 갱신 방식:
   • 성공: total_attempts += 1, consecutive_failures = 0, last_result = "success", last_request_id = "{최근 REQ-NNN}"
   • 실패: total_attempts += 1, consecutive_failures += 1, last_result = "failed", last_request_id = "{최근 REQ-NNN 또는 null}"
4. 동일 DBG 세션에서는 Step 7 재진입 시 기존 session.json.fix_attempts를 Read하여 누적 카운터를 이어갑니다.
5. 레거시 폴백: session.json에 fix_attempts 키가 없으면(구버전 세션) Step 1 초기값(total_attempts: 0, consecutive_failures: 0, architect_escalation.triggered: false)을 자동 주입한 뒤 정상 진행합니다.

Step 1.5: PM 역할 배정 (Investigation Assignment)

PM이 이슈를 분석하여 investigators 수만큼 조사 역할을 배정합니다.

• 이슈 분석: 증상, 재현 조건, 관련 모듈, 의심 영역 파악
• 조사 각도 배정: Codex(코드 레벨 추적), Gemini(광역 컨텍스트), Claude(설계 의도/아키텍처)
• session.json 업데이트: investigators[key].role 기록, status: "investigating"

AUTO-CONTINUE 원칙 (CRITICAL)

이 스킬의 모든 Step은 사용자 입력 없이 자율적으로 진행합니다.

• 백그라운드 작업 완료 시 사용자에게 확인 질문 금지
• 모든 단계는 사용자 입력 없이 자동 진행
• Step 2~5는 완전 자동, Step 6에서만 사용자 보고

병렬 Write 원칙 (CRITICAL)

독립 파일 Write는 하나의 응답에서 동시에 수행:

• session.json, 프롬프트 여러 개를 함께 생성
• 순차 쓰기를 피해 병렬성 보장

Step 2: 에이전트 백그라운드 파견

investigators 키를 순회하여 조사 프롬프트를 작성하고 즉시 백그라운드로 파견합니다.

Claude 모델 결정: config.resolved.json의 models.providers.claude[debug.agents.claude.tier || default_tier]로 resolve (미설정 시 "sonnet" 폴백).

2a. Dispatch 프롬프트 조립 — feature flag 분기

config 확인:

python3 {PLUGIN_ROOT}/scripts/mst.py config get prompt_builder.enabled prompt_builder.fallback_on_error

(a) prompt_builder.enabled=true (하이브리드 JSON 경로)

1. 조사 공통 컨텍스트(이슈 설명, 집중 영역 등)를 .gran-maestro/tmp/ctx-{session_id}.md로 Write
2. dispatch-input.json Write:

   {
     "format": "mst.dispatch",
     "schema_version": 1,
     "common": {
       "topic": "{DBG-NNN 이슈 제목}",
       "constraints": ["..."],
       "reference_context_file": ".gran-maestro/tmp/ctx-{session_id}.md"
     },
     "tasks": [
       {"role": "{investigatorKey}", "angle": "{role}", "ask": "조사 지침 ≤200자 또는 ask_file"}
     ]
   }
   

   • tasks[]는 investigators 키를 순회하여 작성
   • 각 task의 role 값은 "{investigatorKey}" 그대로 설정 (split 결과 파일이 {investigatorKey}-prompt.md로 생성되어 기존 dispatch 경로 호환)
   • 200자 초과 또는 줄바꿈 포함 시 ask_file 경로로 분리
3. CLI 호출: python3 {PLUGIN_ROOT}/scripts/mst.py prompt build --input {absolute_path}/dispatch-input.json --out-dir {absolute_path}/prompts --sid {session_id}
4. 성공 시: python3 {PLUGIN_ROOT}/scripts/mst.py session split-prompts --dir {absolute_path}/prompts 호출 → prompts/{investigatorKey}-prompt.md 개별 파일 생성 → 기존 dispatch (2b 단계) 그대로 실행
5. 실패 시 repair 1회 재요청 → 그래도 실패면 (b) 경로로 자동 전환

(b) prompt_builder.enabled=false 또는 CLI fallback

• 기존 개별 파일 직접 Write 경로 그대로 유지 (변경 금지)

fallback 규약 (MANDATORY)

• CLI 오류 시 stderr/stdout을 Read, PM이 구조화 errors JSON 기반으로 JSON 수정 후 1회 재시도 (repair 1회)
• 재시도 실패 시 (b) 경로로 자동 전환 (fallback_on_error=true일 때)
• fallback_on_error=false이면 워크플로우 중단 + 사용자 에스컬레이션
• 참고: mst.py prompt build는 오류 반환만 담당, repair 1회/fallback 전환은 본 스킬(debug)의 책임이다

2b. 프롬프트 파일 작성

investigators 키를 순회하여 prompts/{investigatorKey}-prompt.md를 하나의 메시지에서 동시에 Write합니다.

프롬프트 작성 포맷:

# 버그 조사 요청


<!-- @include _shared/skill-execution-marker.md -->
## 스킬 실행 마커 (MANDATORY)

- 모든 응답의 첫 줄 또는 각 Step 시작 줄에 아래 마커를 출력한다.
- 기본 마커 포맷: `[MST skill={name} step={N}/{M} return_to={parent_skill/step | null}]`
- 필드 규칙:
  - `skill`: 현재 실행 중인 스킬 이름
  - `step`: 현재 단계(`N/M`) 또는 서브스킬 종료 시 `returned`
  - `return_to`: 최상위 스킬이면 `null`, 서브스킬이면 `{parent_skill}/{step_number}`
- 서브스킬 종료 마커: `[MST skill={subskill} step=returned return_to={parent/step}]`
- C/D 분리 마커 규칙을 추가로 사용하지 않는다. 반드시 단일 MST 마커만 사용한다.
- 예시:
  - `[MST skill={name} step=1/3 return_to=null]`
  - `[MST skill={subskill} step=returned return_to={parent_skill}/{step_number}]`
<!-- @end-include -->

## 이슈
{사용자가 보고한 이슈 전체 내용}

## 당신의 조사 역할
당신은 {provider}입니다. 조사 각도: **{role}**

## 조사 지침
1. 아래 관점에서 코드베이스를 철저히 조사하세요
2. 구체적인 파일명, 라인 번호, 코드 스니펫을 포함하세요
3. 발견한 문제의 근본 원인(root cause)을 추론하세요
4. 수정 방안이 있다면 제안하세요

## 집중 영역
{--focus 값이 있으면 해당 파일 패턴, 없으면 "코드베이스 전체"}

## 출력 형식
응답을 {output_file}에 마크다운으로 작성하세요. 다음 섹션을 포함:
- **Symptom (증상)**: 관찰된 현상, 재현 조건, 영향 범위를 파일/라인 근거와 함께 명시
- **Hypothesis (가설)**: 가능한 근본 원인 가설(1~3개)과 우선순위, 각 가설의 근거
- **Experiment (실험)**: 가설 검증을 위해 수행한 코드 추적/재현 절차/명령 및 확인한 파일:라인
- **Result (결과)**: 실험 결과, 가설 채택/기각 판단, 최종 원인 결론, 수정 제안
- **Open Questions (추가 조사 필요 영역)**: 아직 검증되지 않은 항목과 후속 확인 계획

글자 수 제한: {config.collaborative_debug.finding_char_limit}자 이내

2c. 병렬 호출

모든 호출은 Task(run_in_background: true)로 실행합니다.

• provider: "codex":

  Bash(
    run_in_background: true,
    command: "codex exec --full-auto -m $(python3 {PLUGIN_ROOT}/scripts/mst.py resolve-model codex debug 2>/dev/null || echo \"gpt-5.3-codex\") -C $(pwd) \"$(cat {absolute_path}/prompts/{investigatorKey}-prompt.md)\" > {absolute_path}/finding-{investigatorKey}.md < /dev/null 2>&1; EC=$?; echo \"EXIT_CODE:$EC\" >> {absolute_path}/finding-{investigatorKey}.md; exit $EC"
  )
  

• provider: "gemini":

  Bash(
    run_in_background: true,
    command: "gemini -p \"$(cat {absolute_path}/prompts/{investigatorKey}-prompt.md)\" --model {config.models.providers.gemini[debug.agents.gemini.tier || default_tier]} --approval-mode yolo --sandbox=false > {absolute_path}/finding-{investigatorKey}.md < /dev/null 2>&1; EC=$?; echo \"EXIT_CODE:$EC\" >> {absolute_path}/finding-{investigatorKey}.md; exit $EC"
  )
  

• provider: "claude":

  Task(
    subagent_type: "general-purpose",
    run_in_background: true,
    prompt: "Skill(skill: 'mst:claude', args: '--prompt-file {absolute_path}/prompts/{investigatorKey}-prompt.md --output {absolute_path}/finding-{investigatorKey}.md') 실행 후 완료 보고"
  )
  

각 호출의 background task ID를 session.json에 기록합니다.

Step 4: 합류 (Merge)

에이전트 파견 후 결과를 합류합니다.

4a. 즉시 확인

investigators 순회 → finding-{investigatorKey}.md 존재 여부 확인:

• 존재 + 비어있지 않음 → "done", 미존재/비었음 → "in_progress"

4b. 대기 (필요 시)

모든 investigator done이면 즉시 Step 5 진행.

in_progress investigator가 있으면: 다음 명령을 실행하고 결과를 기다리세요 (타임아웃: config.collaborative_debug.merge_wait_ms ÷ 1000 초, 기본 60): python3 {PLUGIN_ROOT}/scripts/mst.py wait-files
--timeout {config.collaborative_debug.merge_wait_ms을 1000으로 나눈 값, 기본 60}
{in_progress investigator들의 {absolute_path}/finding-{investigatorKey}.md 절대 경로 목록}

마지막 줄이 ALL_READY면 즉시 Step 4c로 진행. TIMEOUT이면 완료된 결과만 사용, 미완료는 "timeout" 기록 후 Step 4c 진행.

4c. session.json 업데이트

⏱️ 타임스탬프 취득 (MANDATORY): TS=$(python3 {PLUGIN_ROOT}/scripts/mst.py timestamp now) 위 명령 실패 시 폴백: python3 -c "from datetime import datetime, timezone; print(datetime.now(timezone.utc).isoformat())" 출력값을 merge_completed_at 필드에 기입한다. 날짜만 기입 금지.

{
  "status": "synthesizing",
  "investigators": {
    "codex": { "status": "done", ... },
    "gemini": { "status": "timeout", ... }
  },
  "merge_completed_at": "{TS — mst.py timestamp now 출력값}"
}

Step 5: 종합 리포트 작성

status: "done"인 finding-{investigatorKey}.md를 Read → debug-report.md 생성:

• 중복 제거 + 교차 검증: 다수 조사자가 동일 문제 지목 시 확신도 상승, 단독 발견은 "추가 검증 필요"
• 근본 원인 통합 최종 진단
• 수정 방안 우선순위 정렬 (P0/P1/P2)
• session.json.fix_attempts.architect_escalation.triggered == true이면 architect 위임 이력(트리거 조건/시각/결과 파일)을 debug-report.md에 포함

session.json의 status를 "completed"로 변경.

Step 6: 사용자 보고

debug-report.md의 내용을 사용자에게 표시합니다.

표시 포맷:

## DBG-NNN 디버그 리포트

### 참여 조사자
- {investigatorKey} ({role}, {provider}): {status}  ← investigators 키 순서대로 반복
  (예: codex, codex-2, gemini, claude 등 설정에 따라 동적 나열)

### 핵심 발견
{가장 확신도 높은 문제 1~3개}

### 수정 제안
{우선순위별 수정 방안}

### Architect 승격 (조건부)
{3회 연속 실패 시 자동 위임 결과 요약, 미발생 시 "없음"}

---
상세 리포트: .gran-maestro/debug/DBG-NNN/debug-report.md

Step 7: 다음 단계 안내

ℹ️ AUTO-CONTINUE 예외: 사용자 의사 확인 필요 → AskUserQuestion 사용. ⚠️ CONTINUATION GUARD: 서브스킬 반환 후 즉시 다음 Step 진행 (hook이 자동 강제).

AskUserQuestion으로 선택지 제시:

• "수정 작업 시작 (→ /mst:request)":
  1. Skill(skill: "mst:request", args: "--from-debug {DBG-NNN} {이슈 제목 앞 50자}") 실행
  2. 서브스킬 반환 직후 session.json.fix_attempts 갱신:
     • 성공: total_attempts += 1, consecutive_failures = 0, last_result = "success", last_request_id = "{최근 REQ-NNN}"
     • 실패: total_attempts += 1, consecutive_failures += 1, last_result = "failed", last_request_id = "{최근 REQ-NNN 또는 null}"
     • last_checked_at은 반드시 현재 UTC ISO-8601 타임스탬프로 기록
  3. consecutive_failures >= 3 && (architect_escalation.triggered == false || architect_escalation.status == "failed")이면 즉시 architect 자동 위임 (첫 위임 실패 후 추가 3회 실패 시 재위임 허용):

     Task(
       subagent_type: "general-purpose",
       prompt: "{PROJECT_ROOT}/agents/architect.md를 Read한 뒤, DBG-NNN의 finding/debug-report를 기반으로 구조적 결함 재검토 문서 작성. 출력: {absolute_path}/architect-review.md"
     )
     

  4. architect 위임 시 session.json.fix_attempts.architect_escalation 업데이트:
     • triggered: true
     • triggered_at: {UTC ISO-8601}
     • status: "requested" | "completed" | "failed"
     • reason: "3 consecutive failed fix attempts in same debug session"
     • output_file: "{absolute_path}/architect-review.md"
  5. debug-report.md에 ## Architect Escalation 섹션을 추가/갱신하여 위임 사실과 결과 파일 경로를 기록
• "플랜으로 정제 후 진행 (→ /mst:plan)" → Skill(skill: "mst:plan", args: "--from-debug {DBG-NNN} {이슈 제목 앞 50자}")
• "리포트만 확인 (종료)" → 스킬 종료

에러 처리

• 과반 이상 done: 정상 합성
• 과반 미만 done: 완료 결과만으로 리포트 생성 (미완료 수 명시)
• 전원 미완료/타임아웃: 에러 + 재시도 안내
• CLI 미설치: 해당 AI 스킵

세션 파일 구조

.gran-maestro/debug/DBG-NNN/
├── session.json
├── prompts/
│   ├── {investigatorKey}-prompt.md
│   └── ...
├── finding-{investigatorKey}.md
└── debug-report.md

옵션

• --focus {파일패턴}: 조사 범위를 특정 파일 패턴으로 제한 (예: src/auth/**/*.ts)

예시

/mst:debug "로그인 시 간헐적으로 401 에러가 발생합니다"
/mst:debug --focus src/api/**/*.ts "API 응답이 비정상적으로 느립니다"
/mst:debug "빌드 시 타입 에러가 발생하는데 원인을 모르겠습니다"

참고

• investigators 동적 배정은 ideation 규칙을 디버그용으로 재사용. roles 대신 investigators 사용은 디버그 고유 스키마.
• claude 포함 모든 provider가 동일 형식으로 investigators에 포함됩니다.