peach-skill-feedback

peach-skill-feedback — Skill improvement feedback documentation

⛔ Scope of responsibility for this skill: up to document creation

할 것: Create feedback document (docs/스킬피드백/TODO-*.md)

What not to do: Modifying the target skill's SKILL.md, changing references/ files, modifying code

Once the document is created and the path is given to the user, this skill's role is finished. Actual skill application is another AI agent in a different sessionreading the document and carrying it out.

Discovered while using Peach skills: problems, workarounds, know-how, improvement directionsare structured and docs/스킬피드백/saved as Korean files by date.

So that another AI agent can read this document and immediately start skill update work, it includes problem analysis + verification scenarios + specific change proposals.

⛔ Sensitive information prohibition rules (top-level rule for all work)

peach-harness is a PUBLIC GitHub repository. Feedback documents are made public as-is. Once committed, even if history is rewritten with BFG, it permanently remains in forks, archives, and search caches. Sensitive information must be blocked before saving, which is the only line of defense. This section takes precedence over all steps of the workflow. Be aware of it before Step 0 environment detection, and if sensitive information is found at any point in Steps 1–5, block it immediately.

Items absolutely prohibited from inclusion

In the feedback document (docs/스킬피드백/*.md), do not write the information below verbatim as-is .

Category	Prohibited items	Replacement placeholder
Internal domain	Actual company/customer domains (operational/development/local, all of them)	`db.dev.example.com`, `app.local.example.com`, `local.example.com`, `dev.example.com`
DB host/port	Actual host name/port	`{DB_HOST}:{DB_PORT}`
DB account	Actual user name	`{DB_USER}`
Password	An actual password string of any form	`{DB_PASSWORD}`
API key/token	Actual key value, Bearer token	`{API_KEY}`, `{TOKEN}`
Company name/business registration number	Actual corporate name, `\d{3}-\d{2}-\d{5}` business registration number	`{COMPANY_NAME}`, `{BIZ_NUMBER}`
Customer-identifiable information	Actual address/phone/email	`{CUSTOMER_INFO}`
Internal project codename	Short English codename (e.g., an abbreviation used only internally)	`{PROJECT}`, `my-project`
Internal work-domain Korean vocabulary	Korean keywords used only in a specific work area (e.g., specific tax/medical/financial item names)	`{기능명}`, general workflow words (`주문`, `결제`, `등록` 등)
In-house PK/identifier field name	Columns/identifiers bearing a company-specific name (e.g., `_number`, `_id` in-house name in the form of)	`{PK_FIELD}`, `id`, `pk`
Korean company name/app name/service name	In-house or client Korean proper noun	`{COMPANY_NAME}`, `{APP_NAME}`, `{SERVICE_NAME}`
Personal absolute path	`/Users/<id>/...`, `/home/<id>/...`, `C:\\Users\\<id>\\...`	`~/source/{project}` relative path such as

Prohibited examples are intentionally not written in this document. If even an example contains real data, this skill violates its own rules. If a pattern is suspicious, ask the user to confirm, and do not copy real data into this document.

Korean/proper noun judgment heuristics

For items that are difficult to detect automatically with regular expressions (Korean vocabulary, short English codenames), if the signals below appear, after confirming with the user replace with placeholders.

Signal	Suspicious case	Response
Korean compound word not found in a general dictionary	예: `XX세액공제`, `YY조제등록`	Ask the user, "Is this word in-house domain vocabulary?"
A short English word of 4-10 characters appears as a directory/module name	예: `~/source/abcd/...`, `module: xyzw`	Possibly a codename → confirm with the user
Korean + English combination that looks like a company name	예: `XX컴퍼니`, `XX솔루션`, `XX헬스`	Possibly a company name → confirm with the user
The username portion of an absolute path	`/Users/<id>/`, `/home/<id>/`, `C:\\Users\\<id>\\`	Always replace with a relative path
General word such as payment/order/medical treatment + in-house-specific prefix	예: `재처방-결제`, `청산-신고`	Neutralize with a general workflow word

If the above signals appear but it is difficult to confirm with the user (e.g., automated workflow), conservatively replace with placeholdersand then proceed with writing. What is incorrectly generalized can be restored later, but what is incorrectly exposed is irreversible.

Required check immediately before saving (before calling Write)

Before saving the feedback document with Write, immediately before, check the following for the written body text.

# 1) 도메인 — 허용 리스트 외 모두 의심
echo "$DRAFT_CONTENT" | grep -nE "[a-z0-9-]+\.(co\.kr|com|net|io|org)" \
  | grep -vE "example\.com|example\.co\.kr|github\.com|google\.com|figma\.com|npmjs|playwright|anthropic|claude\.ai|nuxt|tailwind|kakao|naver|daum|w3\.org|semver|keepachangelog"

# 2) 시크릿 패턴 (실 시크릿 리터럴은 정규식으로만)
echo "$DRAFT_CONTENT" | grep -nE "password[[:space:]]*[=:]|passwd[[:space:]]*[=:]|pwd[[:space:]]*[=:]|AKIA[0-9A-Z]{16}|ghp_[A-Za-z0-9]{20,}|sk-[A-Za-z0-9]{20,}|Bearer[[:space:]]+[A-Za-z0-9]{20,}"

# 3) 사업자번호
echo "$DRAFT_CONTENT" | grep -nE "[0-9]{3}-[0-9]{2}-[0-9]{5}"

# 4) 개인 절대경로
echo "$DRAFT_CONTENT" | grep -nE "/Users/[a-zA-Z0-9._-]+/|/home/[a-zA-Z0-9._-]+/|C:\\\\Users\\\\[a-zA-Z0-9._-]+\\\\"

Even if the above four automatic checks pass, Korean/proper nouns/codenames are not caught automatically. Go through the written body text once and directly review whether there are signals from the above "Korean/proper noun judgment heuristics."

If any detected items are found, do not save notify the user, then replace with placeholders and rewrite.

Principles applied at each writing stage

Command examples: Do not write actual host/user/password. Write generalized placeholders.

# ✅ 권장 (모든 값 플레이스홀더화)
mysql -h {DB_HOST} -u {DB_USER} -p'{DB_PASSWORD}' {DB_NAME}

Scenario URL: Use example domains instead of actual domains.
```
# ✅ 권장
http://local.example.com/admin/...
```
Screenshots/logs: Attach outputs containing sensitive information after masking.
Company/client identifying information: Business registration numbers, company names, and contact names must all be masked or replaced with placeholders.

Handling upon violation

If sensitive information is detected in already-written text, stop saving → report to the user → rewrite after substitution.
Even if the user says "just save it," refuse (irreversible due to the nature of a PUBLIC repository).
If the user explicitly says "force saving with sensitive information included," proceed after one warning, but at the end of the response output a ⚠️ 커밋·푸시 전 반드시 마스킹 필요 warning.

Location of this skill (workflow)

피치 스킬 사용 → 문제 발견 →
  /peach-skill-feedback (이 스킬) → docs/스킬피드백/ 문서 생성 →
  다른 에이전트가 문서를 읽고 → skills/{대상스킬}/ 업데이트

Step 0: Environment detection

Automatically detect the Peach Harness original folder.

# OS별 자동 감지
if [ -d "D:/peachSolution2/peach-harness" ]; then
  HARNESS_ROOT="D:/peachSolution2/peach-harness"
elif [ -d "$HOME/source/peachSolution2/peach-harness" ]; then
  HARNESS_ROOT="$HOME/source/peachSolution2/peach-harness"
else
  echo "❌ 피치 하네스 폴더를 찾을 수 없습니다"
  echo "   Windows: D:\\peachSolution2\\peach-harness"
  echo "   macOS:   ~/source/peachSolution2/peach-harness"
  # 사용자에게 경로 확인
fi

FEEDBACK_DIR="$HARNESS_ROOT/docs/스킬피드백"
SKILLS_DIR="$HARNESS_ROOT/skills"

# 년월 하위 폴더 (예: 2026-05)
YM=$(date +%Y-%m)
MONTH_DIR="$FEEDBACK_DIR/$YM"

# 피드백 폴더 생성 (최초 1회 + 월 폴더)
mkdir -p "$MONTH_DIR"

Rule: Feedback documents must be saved in the Peach Harness original folder. If saved in the plugin cache (~/.claude/plugins/cache/), it will be deleted when npm is updated.

Step 1: Identify target skill

Automatic detection

Identify the Peach skill used in the current conversation context:

/peach-e2e-browse → Target: peach-e2e-browse
/peach-gen-backend → Target: peach-gen-backend
If there are multiple skills, make the skill with the most problems the main target

Manual specification

When the user specifies directly:

/peach-skill-feedback peach-e2e-browse

Read target skill document

# SKILL.md 읽기
cat "$SKILLS_DIR/{대상스킬}/SKILL.md"

# references/ 목록 확인
ls "$SKILLS_DIR/{대상스킬}/references/" 2>/dev/null

Step 2: Collect problem/solution patterns

Extract the following 4 items from the current conversation:

2-1. Discovered problems

Collection item	Example
Things attempted but failed	eval click() not working in Flutter
Situations not in the skill document	accessibility needs to be reactivated
Points where tokens were wasted	screenshot + Read 3 times = thousands of tokens
Things that behaved differently than expected	Clicking VPN menu → bounced to a different page

2-2. Resolved methods

Collection item	Example
Successful workaround	Extract API method from dart.js → call fetch directly
Patterns that were efficient	eval "body.innerText.substring(0,200)"
Newly discovered commands/features	highlight, record, find commands

2-3. Differences from existing skill

Read the target skill's SKILL.md + references/, and among what was discovered in the current conversation, items not in the existing documentidentify.

2-4. Severity classification

Severity	Criteria	Example
High	Work is impossible with the method guided by the skill	Missing method for activating Flutter accessibility
Medium	Massive token waste or causing trial and error	Insufficient guidance to use eval instead of screenshot + Read
Low	Missing convenience features	highlight, record commands undocumented

Step 3: Comparative analysis with existing skill document

# SKILL.md에서 의사결정 트리 확인
grep -n "결정\|판단\|분기\|├─\|└─" "$SKILLS_DIR/{대상스킬}/SKILL.md"

# 핵심 규칙 확인
grep -n "규칙\|금지\|필수\|주의" "$SKILLS_DIR/{대상스킬}/SKILL.md"

# references/ 문서 목록
ls "$SKILLS_DIR/{대상스킬}/references/"

Organize the comparison results in the form below:

| # | 발견된 문제 | 현재 SKILL.md에 있는가 | 위치 (행 번호) |
|---|-----------|:---:|-----|
| 1 | Flutter accessibility 활성화 | X (없음) | — |
| 2 | eval click isTrusted 차이 | X (없음) | — |
| 3 | 세션 끊김 복구 | X (없음) | — |

Step 4: Generate output

File naming rules

For files not yet applied (pending processing), TODO- prefix is added. When applied, TODO-is removed.

# 생성 시 (미반영)
docs/스킬피드백/{YYYY-MM}/TODO-YYYY-MM-DD-{스킬명}-피드백.md

# 반영 완료 후
docs/스킬피드백/{YYYY-MM}/YYYY-MM-DD-{스킬명}-피드백.md

Example:

# 대기 중
docs/스킬피드백/2026-04/TODO-2026-04-15-peach-gen-backend-피드백.md

# 반영 완료
docs/스킬피드백/2026-04/2026-04-12-peach-e2e-browse-피드백.md

year-month (YYYY-MM) is classified into folders. Automatically determined by the date at the time of creation.

When viewing the folder with ls로 볼 때 TODO- only the files stand out, so tasks can be identified immediately. Most files are applied (no prefix), so the folder stays clean.

Document structure (required sections)

---
status: pending            # pending → completed
target_skill: peach-{name}
severity: 높음 N / 중간 N / 낮음 N
completed_at:              # 반영 완료 시 날짜 기입
applied_by:                # 반영 완료 시 에이전트명 기입
---

# {스킬명} 피드백 — YYYY-MM-DD

> **대상 스킬**: peach-{name}
> **작성 근거**: [어떤 작업을 하다가 발견했는지 한 줄]
> **심각도 요약**: 높음 N건 / 중간 N건 / 낮음 N건

---

## 1. 발견된 문제

| # | 문제 | 심각도 | 현재 스킬에 있는가 | SKILL.md 행 |
|---|------|:---:|:---:|-----|

## 2. 해결 방법 / 우회 전략

(문제 번호별 대응. 실제 실행한 명령 + 결과 포함)

### 문제 #1: {제목}
**원인**: ...
**해결**: ...
```bash
# 실제 실행한 명령

3. Skill update proposal

3-1. SKILL.md changes

(Specific line ranges + content to add/modify presented in Markdown)

3-2. references/ additions/modifications

(New reference file names + summary of key content)

3-3. Supplementing existing references such as agent-browser-commands.md

(Commands/patterns to add)

4. Verification scenarios

(Step-by-step commands that another AI agent can reproduce using only this document)

Scenario {number}: {title}

Purpose: ... Prerequisites: ...

# 단계 1: ...
# 단계 2: ...

Expected result: ... Pass criteria: ...

5. Work instructions for the next agent

The AI agent that reads this document proceeds in the following order:

Check the original Pitch Harness folder
- Windows: D:\peachSolution2\peach-harness\
- macOS: ~/source/peachSolution2/peach-harness/
Check the current state of the target skill cat skills/{대상스킬}/SKILL.md
Apply "3. Skill update proposal" in this document in order
- Modify SKILL.md
- Add/modify references/ files
Run the verification scenarios (Section 4) to confirm the changes
After completing the changes:
- frontmatter의 status를 completedchange to , completed_at과 applied_by fill in
- From the file name, TODO- remove the prefix (git mv로 rename)
- Add an application record at the bottom:
```
## 반영 기록
- [날짜] {에이전트}: SKILL.md 행 XX~YY 수정, references/XX.md 추가
```


---

## 5단계: 저장 및 안내

### 저장

```bash
# 피드백 문서 저장 (TODO- 접두어 포함)
FEEDBACK_FILE="$MONTH_DIR/TODO-YYYY-MM-DD-{스킬명}-피드백.md"
# Write tool로 저장

Notify the user

📄 피드백 문서 생성 완료

경로: docs/스킬피드백/{YYYY-MM}/YYYY-MM-DD-{스킬명}-피드백.md
문제: N건 (높음 X / 중간 Y / 낮음 Z)
검증 시나리오: N개

다음 에이전트가 이 문서를 읽고 스킬을 업데이트할 수 있습니다.
반영하려면: /peach-skill-feedback 문서를 참고하여 skills/{대상스킬}/ 수정

⛔ The work of this skill ends here

Save the document, inform the user of the path, and then do not modify any more files. Skill application (modifying SKILL.md, adding references/) is performed by another AI agent that reads this document.

Key rules

Save only in the original Pitch Harness folder — cache folders prohibited
File names in Korean + date, classified into year-month folders — docs/스킬피드백/{YYYY-MM}/YYYY-MM-DD-{스킬명}-피드백.md
Include actual commands — No abstract descriptions, use executable commands
Verification scenarios required — Must be reproducible by another agent
Work instructions for the next agent required — Must be able to start work immediately after reading the document
Comparison with existing documents required — Specify even the SKILL.md line numbers
Never modify skill files — Do not directly Edit/Write SKILL.md, references/, or other skill files. The work of this skill is complete once a document (TODO-*.md) is created and reported to the user. Reflecting changes to the skill must be performed by an agent in a different session reading the feedback document.
Task Completion Criteria — docs/스킬피드백/{YYYY-MM}/TODO-*.md The task is complete the moment the file is saved with the Write tool. After that, no files are modified.

Usage Example

# e2e-browse 스킬 사용 후 문제 발견
/peach-skill-feedback peach-e2e-browse

# gen-backend 스킬 피드백
/peach-skill-feedback peach-gen-backend

# 스킬명 생략 시 대화 맥락에서 자동 감지
/peach-skill-feedback