Skip to content

lemoncloud-io/doki / projects/second-brain/config/skills/vault-reach

vault-reach

Verified

볼트 문서가 최상단 `wiki/INDEX.md`에서 링크를 따라 찾아갈 수 있는지 점검하고(고아 문서 찾기), 문서마다 어디를 고치면 연결되는지 계획을 내고, 승인되면 그 연결을 적용한다. 사용자가 "고아 문서 찾아줘", "고아 노트 점검", "INDEX에서 못 찾아가는 문서", "도달성 점검", "/vault-reach"라고 할 때, 그리고 vault-lint의 고아 점검 단계에서 사용한다. node_modules·.claude 워크트리 등은 스캔하지 않는다.

vault-reach (INDEX 도달성 점검 — 고아 문서)

정의(2026-10-15 사용자 결정): 고아 문서란 wiki/INDEX.md에서 링크를 따라가도 닿지 않는 문서다. 최상단에서 찾아갈 수 없으면 문제로 보고, 끊긴 연결 지점을 찾아 고친다. 범위는 프로젝트 내부 문서까지다.

도구는 projects/second-brain/config/scripts/vault_orphans.py 하나다(의존성 없음, Python 3). 볼트 루트에서 실행한다.

범위

  • 도달해야 하는 문서: 볼트의 모든 Markdown. 단 아래는 도달하지 않아도 된다.
    • 도구·뼈대: projects/**/config/**(스킬·도구 README·픽스처), templates/
    • 루트 진입 파일: CLAUDE.md, AGENTS.md, README.md, VAULT_RULES.md 등
    • 개인 저장소는 예외다(2026-10-15 사용자 결정). 자기 폴더나 상위 폴더의 README.md frontmatter가 scope: personal인 문서(docs/github-linked-projects.md § Access and Visibility). 단 그 내용을 아이디어·프로젝트·위키로 승격하면 승격된 문서는 일반 문서라 INDEX에서 도달해야 한다 — 연결은 이때 필요하다.
    • --skip <경로 접두사>로 뺀 것(임시 예외). 경로를 커밋 문서나 PR 본문에 적지 않는다.
  • 로컬 전용 문서는 볼트 문서가 아니다: gitignore된 파일(공유 저장소에 올리지 않는 개인 소유자 폴더, 작업용 임시 폴더 등)은 팀원에게 존재하지 않으므로 판정하지도, 경로로 쓰지도 않는다. 그런 문서를 거쳐야만 닿는 공유 문서는 팀원 입장에서 끊긴 것이라 고아로 나온다.
  • 스캔하지 않는 것: node_modules(볼트 안에만 md 2천여 개), .git, .claude(워크트리가 볼트 사본이다), .obsidian, private, raw, archive, 빌드 디렉터리. 심볼릭 링크 디렉터리는 따라가지 않는다. 손으로 grep할 때도 같은 제외를 쓴다 — 빼지 않으면 README.md 같은 흔한 이름이 엉켜 판정이 틀어진다.
  • 링크로 세는 것: [[wikilink]]·![[embed]](frontmatter 포함), 상대 Markdown 링크, 폴더 링크 ([x](dir/) → dir/README.md). 코드 블록·인라인 코드 안의 경로는 링크가 아니다.

절차

  1. 점검. python3 projects/second-brain/config/scripts/vault_orphans.py — 도달 수/대상 수와 고아를 묶음별로 보여 준다. 고아가 0이면 끝.
    • --broken은 어디로도 이어지지 않는 링크(위키링크·상대 링크)를 전부 나열한다. vault_verify.py 검사 12는 변경분이 새로 만든 깨진 링크만 결함으로 올리고, base에 이미 있던 것은 이 목록으로 lint 레인이 정리한다. 첨부 임베드(![[shot.png]])는 Obsidian처럼 파일 이름(볼트 어디든)이나 루트 기준 경로로 찾으면 깨진 링크가 아니다(2026-10-25).
  2. 계획. --plan(필요하면 --skip)으로 고아마다 연결 방법을 본다. 수정 하나가 다른 문서까지 열어 주므로 계획은 라운드를 돌며 최소로 잡힌다.
    • mention — 이미 도달 가능한 살아 있는 문서가 그 경로를 인라인 코드로 언급한다 → 그 코드를 링크로 감싼다 (`docs/a.md` → [`docs/a.md`](docs/a.md)).
    • readme — 가장 가까운 상위 README.md가 도달 가능하다 → 그 README의 ## Document Map 절에 한 줄 (- [제목](경로))을 더한다. 절이 없으면 끝에 만든다.
    • 폴더 색인 — ## Document Map 절에 <!-- docmap: folder --> 표식이 있는 README(outputs/README.md, projects/<name>/outputs/README.md)는 그 폴더 트리의 문서 전부에 스스로 닿는다(하위 폴더에 README가 있으면 그 README까지). 그 아래 문서는 고아로 잡히지 않고, 점검 출력의 "폴더 색인 … 목록 갱신 필요"가 색인 목록이 낡았는지 알려 준다. 산출물을 내는 PR은 이 목록을 손으로 고치지 않는다 — 같은 자리에 줄을 더하는 PR끼리 충돌했다.
    • hub — 둘 다 없다 → 허브 연결이 끊긴 것이다. 손으로 고친다: 그 폴더의 README(없으면 짧은 허브 README)를 만들고 wiki/INDEX.md § Vault Hubs나 상위 README에서 링크한다. 그다음 다시 --plan. 계획을 사용자에게 요약해 보인다(종류별 건수, 수정될 파일 수, hub 목록).
  3. 적용(요청받았거나 lint 레인일 때). master에서 딴 작업 브랜치에서 --apply. 폴더 색인의 목록은 이때 경로순으로 다시 만들어진다(손으로 쓴 줄은 경로가 남아 있는 한 그대로, 없어진 파일의 줄은 삭제, 새 파일은 제목으로 추가). 도구는 다음을 고치지 않는다.
    • 날짜 기록: outputs/runs/, outputs/monthly/, areas/weekly/, YYYY-MM-DD-* 파일
    • 동결·생성 파일: docs/vault-ingest-log.md, docs/raw-index.md, wiki/VAULT_MEMORY.md
    • 도구·템플릿: config/, templates/
    • 다른 곳에서 관리되는 사본: 앞부분에 출처 스탬프(origin: frontmatter 키, 또는 첫 10줄 안의 # origin:·<!-- origin: --> 줄)가 있는 파일. 도구는 이 파일을 건너뛰고 다음 언급이나 위 README로 잇는다. 건너뛴 것은 출력과 --json의 skipped_managed에 나온다. 사람이나 에이전트도 이 파일을 손으로 고치지 않는다. 고쳐야 하면 사본을 관리하는 쪽에 변경을 요청한다.
  4. 검증. 다시 실행해 고아 0을 확인한다. 이어서 다음을 확인한다.
    • git diff --name-only에 위 고치지 않는 파일과 raw/·archive/가 없는가
    • vault_verify.py --lane <레인>이 PASS인가
    • diff 표본을 직접 읽어 본다: 링크 경로가 맞는가, 문서 목록 제목이 링크 문법을 깨지 않는가
  5. 기록. 커밋 → PR. 본문에 다음을 적는다.
    • 전후 도달 수, mention·readme·hub 건수
    • 손으로 고친 허브
    • 빼고 남긴 것(이유만, 경로는 적지 않음)

하지 않는 것

  • 링크를 지어내 건수를 맞추지 않는다. readme 목록은 위치만 잇는 것이고, 관계 설명이 필요하면 사람이 다듬는다.
  • raw/·archive/를 읽거나 고치지 않는다. 위키 노트를 병합·삭제하지 않는다.
  • 날짜 기록 안의 평문 경로를 링크로 바꾸지 않는다(기록은 쓴 그대로 둔다).

테스트

cd projects/second-brain/config/scripts && python3 -m unittest test_vault_orphans -v — 도달 판정, 제외 트리 (돌연변이 검사: node_modules 제외를 빼면 두 테스트가 실패해야 한다), 계획 순서, 적용 결과, 기록·도구 미수정을 고정한다.

slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 196kUpdated Claude CodeCodexVerifiedInstall