Harden postcode lookup guidance for flaky shell/runtime conditions

The zipcode-search docs were directionally correct, but they left a few practical failure modes underexplained for real operator use. This update makes the retry order explicit, adds guidance for temp-file based parsing in wrapped shells, and documents the benign curl (23) case when downstream readers close early.

Constraint: Keep the change docs-first without adding runtime code or dependencies
Constraint: The official ePost endpoint remains intermittently flaky, so guidance must focus on stable operator behavior rather than pretending transport is deterministic
Rejected: Replace the docs example with a larger shell wrapper script | too heavy for a small skill-doc improvement
Rejected: Ignore curl (23) and here-doc issues as user error | repeated operator confusion is worth documenting
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: If the zipcode-search example changes again, keep the retry order and shell-wrapper caveats aligned between the skill doc, feature doc, and regression test
Tested: node --check scripts/skill-docs.test.js
Tested: node --test scripts/skill-docs.test.js
Tested: npm run ci
Tested: npx --yes skills add . --list
Not-tested: Live ePost requests for this doc-only follow-up

docs/features/zipcode-search.md

@@ -24,7 +24,7 @@
 2. 주소 키워드를 `keyword` 파라미터로 넘겨 HTML 결과를 받습니다.
 3. 결과에서 우편번호(`sch_zipcode`)와 표준 주소(`sch_address1`), 건물명(`sch_bdNm`)을 추출합니다.
 4. 후보가 여러 개면 상위 3~5개만 간단히 비교해 줍니다.
-5. 전송 timeout/reset이 나면 `curl` 재시도 옵션을 유지한 채 한 번 더 돌리고, 그래도 실패하면 키워드를 도로명 + 건물번호 또는 동/리 + 지번 형태로 다시 줄여서 재시도합니다.
+5. 전송 timeout/reset이 나면 `curl` 재시도 옵션을 유지한 채 한 번 더 돌리고, 그래도 실패하면 `세종대로 209` 같은 짧은 도로명 + 건물번호 → `서울 종로구 세종대로 209` 같은 시/군/구 포함 전체 주소 → 동/리 + 지번 순으로 재시도합니다.
 
 ## 예시
 
@@ -79,6 +79,12 @@ for zip_code, address, building in matches[:5]:
 PY
 ```
 
+## 실전 운영 팁
+
+- 쉘 래퍼나 에이전트 환경에서는 here-doc + Python one-liner보다 `mktemp` 같은 임시 파일에 HTML을 저장한 뒤 파싱하는 쪽이 더 안전합니다.
+- 응답 일부만 빨리 보려고 `curl ... | head` 를 붙이면 다운스트림이 먼저 닫히면서 `curl: (23)` 이 보일 수 있습니다. 이때는 전체 응답을 임시 파일에 저장한 뒤 확인합니다.
+- 재시도 순서는 보통 `세종대로 209` 같은 짧은 도로명 + 건물번호 → `서울 종로구 세종대로 209` 같은 전체 주소 → 동/리 + 지번 순이 가장 덜 헷갈립니다.
+
 ## 프로토콜/클라이언트 제약
 
 - 현재 ePost 엔드포인트는 로컬 기본 `urllib` 전송으로 붙으면 TLS/HTTP 협상 중 연결 reset이 날 수 있습니다.

scripts/skill-docs.test.js

@@ -123,6 +123,10 @@ test("zipcode-search docs lock the official ePost extraction flow and reliable t
     assert.match(doc, /"--retry",\s+"3"/);
     assert.match(doc, /--retry-all-errors/);
     assert.match(doc, /"--retry-delay",\s+"1"/);
+    assert.match(doc, /mktemp|임시 파일/);
+    assert.match(doc, /curl: \(23\)/);
+    assert.match(doc, /짧은 도로명 \+ 건물번호/);
+    assert.match(doc, /시\/군\/구 포함 전체 주소/);
     assert.doesNotMatch(doc, /urllib\.request/);
     assert.doesNotMatch(doc, /urlopen/);
   }

zipcode-search/SKILL.md

@@ -102,7 +102,7 @@ PY
 
 핵심 필드는 `sch_zipcode`(우편번호), `sch_address1`(기본 주소), `sch_bdNm`(건물명)이다.
 
-바깥쪽 Python `timeout`은 두지 말고 `curl` 자체 제한(`--max-time` + `--retry`)으로 전송 시간을 제어한다. 전송 실패가 나도 바로 다른 소스로 우회하지 말고, 위 재시도 옵션 그대로 한 번 더 실행한 뒤 키워드를 더 구체화한다.
+바깥쪽 Python `timeout`은 두지 말고 `curl` 자체 제한(`--max-time` + `--retry`)으로 전송 시간을 제어한다. 전송 실패가 나도 바로 다른 소스로 우회하지 말고, 위 재시도 옵션 그대로 한 번 더 실행한 뒤 키워드를 더 구체화한다. 실전에서는 `세종대로 209` 같은 짧은 도로명 + 건물번호를 먼저 넣고, 실패하면 `서울 종로구 세종대로 209` 같은 시/군/구 포함 전체 주소 순으로 재시도한다.
 
 ### 3. Normalize for humans
 
@@ -113,13 +113,17 @@ PY
 - 건물명이 있으면 함께 표기
 - 후보가 여러 개면 상위 3~5개만 보여주고 어느 항목이 가장 근접한지 짚기
 
-### 4. Retry with a tighter keyword when needed
+### 4. Retry with tighter and fuller keywords when needed
 
-검색 결과가 없으면 키워드를 더 짧고 정확하게 바꿔 다시 조회한다.
+검색 결과가 없거나 timeout/reset이 반복되면 아래 순서로 재시도한다.
 
-- `세종대로 209`
-- `서울 종로구 세종대로 209`
-- `세종로 209`
+- 짧은 도로명 + 건물번호: `세종대로 209`
+- 시/군/구 포함 전체 주소: `서울 종로구 세종대로 209`
+- 동/리 + 지번 또는 대체 표기: `세종로 209`
+
+### 5. Prefer temp files in wrapped shells
+
+CLI 래퍼나 에이전트 쉘에서는 here-doc + Python one-liner가 깨질 수 있으므로, 실전에서는 `mktemp` 같은 임시 파일에 HTML을 저장한 뒤 그 파일을 파싱하는 경로를 우선한다. 응답 일부만 보려고 `| head` 를 붙이면 다운스트림이 먼저 닫히면서 `curl: (23)` 이 보일 수 있으니, 이 경우도 전체 응답을 임시 파일에 저장한 뒤 확인한다.
 
 ## Done when