| name | improve |
| version | 0.3.0 |
| description | 실제 사용 실패를 기반으로 다른 스킬을 개선하는 메타 스킬입니다. SDT가
스킬의 출력이 잘못되었거나 예상과 다르다고 보고하면, 근본 원인을 분석하고,
개선안을 작성하며, CONTRIBUTING.md 가이드라인에 따라 수정을 적용하고,
PR 생성 또는 로컬 적용을 제안합니다.
사용 시점: "improve", "this didn't work", "fix this skill", "the output was wrong",
"skill improvement", "qa-improve".
사용하지 않을 때: 출력 내용에 대한 피드백을 줄 때 (확인 단계에서 옵션 B 사용), QA 방법론에 대해 문의할 때, 일반 QA 워크플로우를 실행할 때.
|
| tool-groups | ["bash","read","write","edit","glob","grep","ask"] |
| preamble-tier | 1 |
/improve: 스킬 자기 개선
실제 사용 실패를 기반으로 다른 QABuddy 스킬을 개선하는 메타 스킬입니다.
SDT가 스킬의 출력이 부정확하거나, 오해를 유발하거나, 불완전하다고 보고하면
근본 원인을 분석하고, 목표 수정을 제안하고, 적용하고, 검증합니다.
제약 사항
- 실패를 추측하지 않기. SDT에게 어떤 일이 발생했고 무엇을 기대했는지 물어봅니다. 모호한 설명으로 추론하지 않습니다.
- 변경을 제안하기 전에 스킬을 읽기. 모든 수정은 변경하려는 특정 라인, 페이즈, 또는 섹션을 참조해야 합니다.
- CONTRIBUTING.md를 따르기. 변경 전에 읽습니다. 300줄 스킬 예산, Sonnet 컨텍스트 제한, 구조적 규칙을 준수합니다.
- 한 번에 하나의 근본 원인만. SDT가 여러 문제를 보고하면 순차적으로 처리합니다. 관련 없는 수정을 묶지 않습니다.
- 워크플로우 고유 지식을 보존. 축소 작업 중에도 페이즈 로직, KB 경로, 심각도 척도, SDT 승인 게이트를 제거하지 않습니다.
- 수정을 개념적으로 테스트. 적용 전에 수정이 원래 실패의 재발을 어떻게 방지하는지 설명합니다.
- 버전을 올리기. 모든 스킬 변경에는 패치 또는 마이너 버전 범프가 필요합니다.
Phase 1: 실패 파악
SDT에게 다음을 질문합니다 (SDT가 이미 답한 항목은 건너뜁니다):
- 어떤 스킬? -- 잘못된 출력을 생성한 스킬이 무엇인가요? (예:
/qa-test-plan, /qa-qa)
불분명하면 최근 세션에서 스킬 호출을 확인합니다.
- 무엇이 발생했나요? -- 스킬이 어떤 출력을 생성했나요? 구체적으로: 잘못된 텍스트를 인용하거나, 잘못된 테이블을 보여주거나, 누락된 섹션을 설명해 주세요.
- 무엇을 기대했나요? -- 출력이 어떠했어야 하나요? 올바른 동작은 어떤 모습인가요?
- 어떻게 발견했나요? -- SDT가 검토 중 발견했나요? 다른 스킬이 이로 인해 실패했나요? 팀원이 지적했나요?
- 재현 가능한가요? -- 동일한 입력으로 매번 동일한 잘못된 출력이 나오나요, 아니면 일회성인가요?
답변을 받으면 요약합니다: "정리하면: [스킬]이 [X]를 했지만 [Y]를 했어야 하며, 원인은 [근본 원인 가설]입니다. 맞나요?"
Phase 2: 근본 원인 분석
- 스킬 파일 읽기:
core/skills/<skill>/SKILL.md
- CONTRIBUTING.md 읽기 -- 가이드라인 및 제약 사항 확인
- 실패 지점 식별: 어떤 페이즈, 제약 사항, 또는 지시사항이 잘못된 동작을 유발했는지 파악
근본 원인을 분류합니다:
| 분류 | 설명 | 예시 |
|---|
| 제약 사항 누락 | 잘못된 동작을 방지하는 규칙이 없음 | 에이전트가 Jira에서 테스트 상태를 추론함 -- "하지 말라"는 제약 사항이 없었음 |
| 잘못된 페이즈 순서 | 페이즈 N에서 필요한 정보가 페이즈 N+2에서 생성됨 | feature.md가 테스트 계획 작성 이후에 생성됨 |
| 지시사항 공백 | 페이즈 지시사항이 해당 시나리오를 다루지 않음 | Jira description 필드에서 AC를 읽는 방법에 대한 안내가 없었음 |
| 자체 평가 공백 | 자체 평가가 해당 실패를 검사하지 않음 | 미검증 테스트 상태에 대한 체크가 없었음 |
| 템플릿 문제 | 출력 템플릿이 잘못된 형식을 허용하거나 유도함 | 상태 열이 증거 없이 "Done (in PR)"을 허용함 |
| 컨텍스트 과잉 의존 | 스킬이 파일에 쓰지 않고 메모리 내 데이터에 의존함 | AC를 컨텍스트에만 보관하여 대형 에픽에서 소실됨 |
| 범위 이탈 | 스킬이 의도된 역할 외의 작업을 수행함 | 테스트 계획 스킬이 검사하지 않은 코드에 대해 주장함 |
분석 결과를 SDT에게 제시합니다: "근본 원인: [분류] -- [설명]. 이를 유발한 구체적인 지시사항: [스킬에서 인용]."
Phase 3: 개선안 작성
구조화된 제안을 작성합니다:
# 스킬 개선 제안: `<skill-name>`
**버전:** 현재 -> 제안
**근본 원인:** [Phase 2의 분류]
**보고자:** [SDT 이름 또는 "세션"]
## 문제
[1-2문장: 어떤 부분이 기대와 다르게 동작했는지]
## 근본 원인
[어떤 페이즈/지시사항/공백이 원인인지. 구체적인 텍스트를 인용.]
## 제안 변경 사항
| # | 위치 | 변경 유형 | 설명 |
|---|------|----------|------|
| 1 | 제약 사항 | 추가 | [새 제약 사항 텍스트] |
| 2 | Phase N | 수정 | [무엇을 변경하고 그 이유] |
| 3 | 자체 평가 | 추가 | [새 체크리스트 항목] |
## 기대 결과
[이 수정이 실패 재발을 어떻게 방지하는지]
## 예산 확인
- 현재 스킬 줄 수: [N]
- 변경 후: [예상 N]
- 300줄 예산 이내: Yes/No
SDT에게 제시합니다: "제안된 수정 사항입니다. 적용할까요?"
승인을 기다립니다. SDT가 제안을 수정하고 싶으면 적용 전에 반영합니다.
Phase 4: 변경 적용
SDT가 승인하면:
-
스킬 파일을 수정합니다: core/skills/<skill>/SKILL.md
- 제안의 각 변경 사항을 적용합니다
- 버전을 올립니다 (수정은 패치, 새 페이즈/제약 사항은 마이너)
-
빌드하고 확인합니다:
node build.js all
- 3개 플랫폼 모두 빌드가 성공하는지 확인합니다
- 스킬이 300줄 이내인지 확인합니다:
wc -l core/skills/<skill>/SKILL.md
-
eval fixture를 실행합니다 -- 변경된 스킬에 대해:
core/skills/<skill>/tests/fixtures.json을 읽습니다- 각 fixture에 대해: fixture 입력으로 스킬을 시뮬레이션하고, 모든 assertion을 확인합니다
- 결과를 보고합니다. fixture가 실패하면 수정이 회귀를 유발했을 수 있으므로 계속하기 전에 검토합니다.
-
해당 스킬에 한국어 로케일이 있는 경우, locales/ko/skills/<skill>/SKILL.md도 업데이트가 필요하다는 점을 SDT에게 알립니다. 자동 번역하지 않습니다.
Phase 5: 자체 평가
전달하기 전에 확인합니다:
- 변경이 제안과 일치 -- 제안의 모든 변경을 적용했고, 추가한 것이 없음
- 예산 확인 -- 스킬이 300줄 이하, 전체 컨텍스트가 530줄 이하
- CONTRIBUTING.md 준수 -- 제약 사항이 상단에, 자체 평가에 형식 검사 포함, 완료 상태가 마지막에 위치
- 빌드 통과 -- 3개 플랫폼 모두 빌드 성공
- eval fixture 통과 -- 변경된 스킬의 모든 fixture가 수정 후에도 통과. 회귀가 있으면 전달 전에 수정.
- 부수 피해 없음 -- 이 스킬의 출력을 읽는 다른 스킬(예: sprint-status가 QA 보고서를 읽는 경우)이 새 형식에서도 정상 동작
Phase 6: 전달
SDT에게 물어봅니다:
(A) PR 생성 (공유 리포지토리에 권장)
(B) 로컬 적용 (개인 테스트용)
- 동일한 구조화된 메시지로 현재 브랜치에 커밋합니다
.qabuddy.json의 teamMode 설정을 확인합니다 -- 'team'이면 옵션 (A)를 기본으로 합니다.
(C) 커밋하지 않음 (변경 사항만 검토)
- SDT가 수동으로 검토할 수 있도록 워킹 트리에 편집 내용을 유지합니다
업스트림(Upstream) 기여 (A 또는 B 후 자동)
.qabuddy.json에 contributeUpstream: true가 설정되어 있으면, 로컬 적용 또는 프로젝트 PR 생성 후 자동으로 업스트림에 기여합니다:
- 업스트림 리포지토리를 포크합니다 (아직 안 했으면):
gh repo fork {upstreamRepo} --clone=false
- 브랜치 생성:
improve/<skill>-<short-description>
core/ 변경 사항만 커밋합니다 (dist/, team-practices/, .qabuddy.json 제외)- 포크에 푸시하고 업스트림에 PR을 생성합니다:
gh pr create --repo {upstreamRepo} --title "fix(<skill>): <description>" --body "$(cat <<EOF
## Improvement Proposal
{Phase 3의 제안}
## Eval Results
{Phase 4의 eval 실행 결과}
EOF
)"
다음 경우에는 업스트림 기여를 건너뜁니다:
- 옵션 (C)를 선택한 경우 (아직 커밋한 것이 없음)
- 변경이 팀 고유인 경우 (team-practices/, .qabuddy.json, 또는 프로젝트 고유 내용을 수정)
Status: DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT
Summary: {무엇을 변경했고 그 이유}
Next steps: {업스트림 PR 링크가 있으면 포함, 프로젝트 PR 링크, 또는 "수정을 테스트하세요"}
