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:
- 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.
- 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]'
- 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 <skill-base-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.
1---2name: note3description: Record an exploration note (PoC, review, code analysis, or any work without a JIRA issue) as a Markdown file in your public work-docs repo. Give it a free-form category and a slug and it scaffolds <category>/<YYYY-MM-DD>-<slug>.md from an exploration template (목적/배경/범위·방법/발견/결론/다음 단계/참고), fills it from the session, and commits it. While researching, actively use the collection's lookup/analysis skills (cubrid-manual, cmt-manual, and Understand-Anything if installed) so findings are verified, not asserted from memory. Complements the worklog skill, which is for issue-keyed work. The repo is PUBLIC, so keep internal-only detail in the master DOCX. Triggers on phrases like 'PoC 노트 남겨', '검토 노트 작성', '코드 분석 기록', 'record an exploration note', 'note this analysis'.4---56# Record an exploration note (work-docs)78For 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).910## Step 0: Prereqs1112- 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.1314## Step 1: Category and slug1516The invocation is `<category> <slug>`. **A category the user names wins over inference:**17181. **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`.192. **Reuse an existing category** rather than inventing a near-duplicate (`bug` vs `analysis`). List them first (uppercase folders are worklog issue keys: skip them):20 ```bash21 REPO="${WORK_DOCS_REPO:-$HOME/Devel/work-docs}"; ls -d "$REPO"/*/ 2>/dev/null | xargs -n1 basename | grep -vE '^[A-Z]'22 ```233. **Only if the user named no category, infer one** that fits (`poc`, `review`, `analysis`, …).2425Then 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`).2627## Step 2: Scaffold the file2829```bash30bash <skill-base-dir>/assets/new_note.sh <category> <slug>31```3233Creates `<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.3435## Step 3: Investigate (use the lookup / analysis skills)3637Before 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:3839- **cubrid-manual**: CUBRID engine SQL syntax, functions, data types, reserved words, and config parameters (for engine-behavior review or code analysis).40- **cmt-manual**: CUBRID Migration Toolkit behavior, source-type mapping, and options (for migration-related notes).41- **Understand-Anything** (if installed): `/understand`, `/understand-explain`, `/understand-diff` for codebase structure, a specific file/function, or change impact (for 코드 분석).42- **jira-fetch**: if the exploration relates to an existing CUBRID Jira issue, pull it for context.4344Record what you consulted (manual URLs, graph, issue keys) in the 참고 section.4546## Step 4: Fill it in4748Complete each section: 요약 / 목적 / 배경 / 범위·방법 / 발견·관찰 / 결론 / 다음 단계(이슈화 여부) / 참고. Detailed but **easy to skim**:4950- **`## 요약` first, in one line** (핵심 결론/발견).51- 목적·배경·결론은 2~3문장 짧은 서술, 방법·발견·다음 단계의 나열은 **개조식 불릿**.52- 데이터·비교·수치는 **표**로, 코드·SQL·로그는 **코드블록**으로 (문장으로 풀지 않기).53- **한 불릿에는 한 사실만**: `현재 → 목표`를 한 문장에 욱여넣지 말고 표의 두 열로. 클래스·파일 이름을 넷 넘게 쉼표로 잇지 말고, 표로 분리하거나 **기준 + 개수**로 압축한다 (예: "`Wrapper`를 구현하는 7개 클래스").54- 흐름·구조·관계·시퀀스는 **Mermaid 다이어그램**(GitHub가 자동 렌더하는 `mermaid` 코드블록)으로 적극 표현: `flowchart`(처리·분기 흐름), `sequenceDiagram`(호출/상호작용), `erDiagram`(스키마·테이블 관계), `classDiagram`/`stateDiagram`(구조·상태 전이). 이해를 돕는 곳에만, 노드는 간결하게(대략 10개 이하). 노드가 4개를 넘으면 `flowchart TB`(세로)가 폭에 맞아 읽기 좋다.55 - 복잡한 도식은 커밋 전에 한 번 렌더해 눈으로 확인한다(문법 오류·어색한 배치 예방). 예: `.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가 자동 렌더).56- em-dash(`—`)는 쓰지 않는다. 쉼표·콜론·괄호·마침표로 대체.5758**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.5960## Step 5: Commit (never push)6162```bash63REPO="${WORK_DOCS_REPO:-$HOME/Devel/work-docs}"64git -C "$REPO" add "<category>/<YYYY-MM-DD>-<slug>.md"65git -C "$REPO" commit -m "note(<category>): <short summary>"66```6768Give the user the local path and the public URL. Pushing is the user's responsibility.
Srltas