Record an exploration note (work-docs)

For work that has no JIRA issue: PoC, 검토(review), 코드 분석, and the like. Issue-keyed work goes through the worklog skill instead. Both write to the same public work-docs repo, side by side (issue records in uppercase-key folders, notes in lowercase category folders).

Step 0: Prereqs

• The public docs repo cloned at ${WORK_DOCS_REPO:-$HOME/Devel/work-docs} (shared with worklog; the legacy WORKLOG_DOCS_REPO also works), with its origin set to your public repo.

Step 1: Category and slug

The invocation is <category> <slug>. A category the user names wins over inference:

1. If the user named a category, use it verbatim (lowercased). A leading ASCII word (/note bug … → bug), or any word matching an existing folder, is the category, even when the rest of the request describes the content: /note bug 분석한 내용... still means category bug, not analysis.
2. Reuse an existing category rather than inventing a near-duplicate (bug vs analysis). List them first (uppercase folders are worklog issue keys: skip them):

   REPO="${WORK_DOCS_REPO:-$HOME/Devel/work-docs}"; ls -d "$REPO"/*/ 2>/dev/null | xargs -n1 basename | grep -vE '^[A-Z]'

3. Only if the user named no category, infer one that fits (poc, review, analysis, …).

Then pick a short slug. Before scaffolding, state the resolved <category>/<slug>; if you inferred the category (step 3) or it would create a brand-new folder, confirm with the user first (it creates a directory). Write the note in Korean. The date is added automatically (YYYY-MM-DD).

Step 2: Scaffold the file

bash ${CLAUDE_SKILL_DIR}/assets/new_note.sh <category> <slug>

Creates <category>/<YYYY-MM-DD>-<slug>.md from the template (refuses to overwrite) and prints the local path plus the public GitHub URL. Category and slug are lowercased and sanitized.

Step 3: Investigate (use the lookup / analysis skills)

Before writing conclusions, actively ground the note with the collection's investigation skills. Do not assert a fact from memory when a lookup can verify it:

• cubrid-manual: CUBRID engine SQL syntax, functions, data types, reserved words, and config parameters (for engine-behavior review or code analysis).
• cmt-manual: CUBRID Migration Toolkit behavior, source-type mapping, and options (for migration-related notes).
• Understand-Anything (if installed): /understand, /understand-explain, /understand-diff for codebase structure, a specific file/function, or change impact (for 코드 분석).
• jira-fetch: if the exploration relates to an existing CUBRID Jira issue, pull it for context.

Record what you consulted (manual URLs, graph, issue keys) in the 참고 section.

Step 4: Fill it in

Complete each section: 요약 / 목적 / 배경 / 범위·방법 / 발견·관찰 / 결론 / 다음 단계(이슈화 여부) / 참고. Detailed but easy to skim:

• ## 요약 first, in one line (핵심 결론/발견).
• 목적·배경·결론은 2~3문장 짧은 서술, 방법·발견·다음 단계의 나열은 개조식 불릿.
• 데이터·비교·수치는 표로, 코드·SQL·로그는 코드블록으로 (문장으로 풀지 않기).
• 한 불릿에는 한 사실만: 현재 → 목표를 한 문장에 욱여넣지 말고 표의 두 열로. 클래스·파일 이름을 넷 넘게 쉼표로 잇지 말고, 표로 분리하거나 기준 + 개수로 압축한다 (예: "Wrapper를 구현하는 7개 클래스").
• 흐름·구조·관계·시퀀스는 Mermaid 다이어그램(GitHub가 자동 렌더하는 mermaid 코드블록)으로 적극 표현: flowchart(처리·분기 흐름), sequenceDiagram(호출/상호작용), erDiagram(스키마·테이블 관계), classDiagram/stateDiagram(구조·상태 전이). 이해를 돕는 곳에만, 노드는 간결하게(대략 10개 이하). 노드가 4개를 넘으면 flowchart TB(세로)가 폭에 맞아 읽기 좋다.
  • 복잡한 도식은 커밋 전에 한 번 렌더해 눈으로 확인한다(문법 오류·어색한 배치 예방). 예: .mmd로 저장 후 curl -sf -X POST "${KROKI_URL:-https://kroki.io}/mermaid/png" -H 'Content-Type: text/plain' --data-binary @diagram.mmd -o /tmp/d.png 로 렌더해 이미지를 확인하고, 이상하면 고친 뒤 다시 렌더한다. 최종 문서에는 mermaid 코드블록을 그대로 둔다(GitHub가 자동 렌더).
• em-dash(—)는 쓰지 않는다. 쉼표·콜론·괄호·마침표로 대체.

The repo is PUBLIC: no credentials, internal hostnames, local absolute paths, or internal-only analysis. Keep sensitive detail in the master DOCX and link out.

Step 5: Commit (never push)

REPO="${WORK_DOCS_REPO:-$HOME/Devel/work-docs}"
git -C "$REPO" add "<category>/<YYYY-MM-DD>-<slug>.md"
git -C "$REPO" commit -m "note(<category>): <short summary>"

Give the user the local path and the public URL. Pushing is the user's responsibility.