---
name: sdlc-onboard-docs
description: Document onboarding — Graphify build graph + Claude verify + supplement gaps
version: 1.0.1
author: "@ngocsangairvds/vsaf"
---

# Onboard Docs — Build & Verify Document Knowledge Graph

You are a Knowledge Engineer. Mission: ensure graph.json captures ACCURATELY all knowledge from project documents.

## Progress Protocol

Each step prints progress:
```
[ONBOARD-DOCS] [1/4] description... (icon)
```
Icon: `⏳` running, `✅` done, `❌` error.

## Index Protection

> ⛔ DO NOT modify `graphify-out/` or `.gitnexus/` DIRECTLY — only graphify is allowed to write to `graphify-out/`.
> **Exception:** Phase 3 supplements nodes/edges directly into `graph.json` after graphify has built it — this is the only permitted direct modification.

## Input

- Project path: `$ARGUMENTS` (or current directory)
- Read all docs in project: README, docs/, wiki/, specs/, *.md, *.txt

## Steps

### Phase 1: Scan & Import

```
[ONBOARD-DOCS] [1/4] Scan & import documents... ⏳
```

1. Scan all documents in project (README, docs/, wiki, specs)
2. List all docs found
3. Resolve markitdown Python — run:
   ```bash
   VENVS=$(pipx environment --value PIPX_LOCAL_VENVS 2>/dev/null)
   MARKITDOWN_PYTHON="${VENVS}/markitdown/bin/python"
   # Windows: "${VENVS}\markitdown\Scripts\python.exe"
   # Fallback: ~/.local/pipx/venvs/markitdown/bin/python
   ```
   If markitdown Python not found, skip step 5 entirely and route ALL complex files through tier fallbacks:
   - **All Tier 1 files** → add to graphify-direct-read list (graphify reads natively)
   - **All Tier 2 HTML files** → Claude Read fallback (step 6)
   - **All Tier 2 PPTX/EPUB/ZIP files** → skipped (no fallback available)
   Then jump to step 6 routing.

4. Classify each complex file into a tier:
   - **Tier 1 (graphify-native):** PDF, DOCX, XLSX, PNG, JPG, GIF, WEBP — graphify can read these directly if markitdown fails
   - **Tier 2 (graphify-blind):** HTML, PPTX, EPUB, ZIP — graphify cannot read these; need markitdown or Claude fallback
   - Text files (`.md`, `.txt`) are NOT complex — read directly, skip conversion

5. For each complex file, attempt markitdown conversion (skip if markitdown not found — see step 3):
   - Resolve markitdown Python (step 3 above)
   - Convert using the wrapper script (bundled in this skill directory):
     ```bash
     "${MARKITDOWN_PYTHON}" "<this-skill-dir>/convert.py" \
       --input "{file}" \
       --output ".vsaf/docs/onboarding/doc-imports/{name}.md"
     ```
   - `<this-skill-dir>` = the directory containing this SKILL.md
   - The script auto-detects OCR availability from `~/.vsaf/markitdown.env`

6. After each conversion, verify and route:

   **If convert.py exit code = 0:**
   Read the output `.md` file and verify content quality. Check ALL of:
   - Contains meaningful content from the document? (not just auto-generated headers like `## Page 1`)
   - Not an LLM refusal? (e.g., "I'm sorry, but I can't help with that")
   - Not hallucinated? (e.g., fabricated tool calls, irrelevant JSON/XML, text unrelated to source file)
   - Has substance? (more than a few words after stripping structural markers)

   If ALL checks PASS → use the `.md` output. Log: `[ONBOARD-DOCS] {file} → converted ✅`

   If ANY check FAILS → treat as conversion failure (continue to fallback below).

   **If convert.py exit code ≠ 0, OR verification failed:**

   - **Tier 1 file** → Log: `[ONBOARD-DOCS] {file}: markitdown failed → graphify will read directly`
     Add the ORIGINAL file path to a "graphify-direct-read" list. Do NOT retry conversion.
     After all conversions, persist the list to `.vsaf/docs/onboarding/graphify-direct-read.txt` (one path per line).
   - **Tier 2 HTML file** → Read the HTML file with the Read tool. Extract meaningful content (headings, paragraphs, tables, lists, links). Write clean markdown to `.vsaf/docs/onboarding/doc-imports/{name}.md`. Log: `[ONBOARD-DOCS] {file} → Claude Read fallback ✅`
   - **Tier 2 PPTX/EPUB/ZIP file** → Log: `[ONBOARD-DOCS] ⚠️ {file}: conversion failed, no fallback — skipped`

Print conversion summary:
```
[ONBOARD-DOCS] Conversion summary:
  markitdown OK:     N files
  graphify direct:   N files (Tier 1 fallback)
  Claude Read:       N files (Tier 2 HTML fallback)
  Skipped:           N files (no fallback available)
```

```
[ONBOARD-DOCS] [1/4] Scan & import documents... ✅
```

### Phase 2: Graphify Build

```
[ONBOARD-DOCS] [2/4] Graphify build for docs... ⏳
```

7. Create a staging directory at `.vsaf/docs/onboarding/graphify-staging/` and populate it with ALL inputs for graphify:
   - Copy or symlink original text documents (`.md`, `.txt`, README)
   - Copy or symlink successfully converted `.md` files from `.vsaf/docs/onboarding/doc-imports/`
   - Copy or symlink files from `.vsaf/docs/onboarding/graphify-direct-read.txt` (original binary files — graphify reads these natively: PDF, DOCX, XLSX, images)
   
   This directory is the single input to graphify — it ensures graphify only processes docs, never source code.

8. Run `/graphify .vsaf/docs/onboarding/graphify-staging/`
9. Output: `graphify-out/graph.json`

**IMPORTANT:** Graphify is ONLY for docs (documents, specs, README). DO NOT run graphify on source code — code indexing is handled by GitNexus in `/sdlc-onboard-code`.

```
[ONBOARD-DOCS] [2/4] Graphify build for docs... ✅
```

### Phase 3: Claude Verify & Fix

```
[ONBOARD-DOCS] [3/4] Verify & fix graph... ⏳
```

10. Re-read **each original doc** — extract: concepts, relationships, business rules, constraints
11. Read `graph.json` — find corresponding nodes/edges
12. Compare:
    - Concept in doc but no node in graph → **MISSING**
    - Relationship in doc but no edge in graph → **MISSING**
    - Business rule/constraint not captured → **MISSING**
    - All present → OK
13. If missing: supplement nodes/edges directly into `graph.json` (this is the permitted exception to the Index Protection rule)
14. Report: "{doc}: +N nodes, +M edges supplemented"

```
[ONBOARD-DOCS] [3/4] Verify & fix graph... ✅
```

### Phase 4: Extract Domain Terms

```
[ONBOARD-DOCS] [4/4] Extract domain terms → CONTEXT.md... ⏳
```

15. From the completed graph, extract domain terms → `CONTEXT.md`
16. Format Shared Language table:

```markdown
## Shared Language

| Term | Definition | Example |
|------|-----------|---------|
| {term} | {1-line definition} | {concrete example} |
```

```
[ONBOARD-DOCS] [4/4] Extract domain terms → CONTEXT.md... ✅
```

## Output

- `graphify-out/graph.json` — verified + supplemented
- `.vsaf/docs/onboarding/doc-imports/{name}.md` — converted/fallback imports (if any)
- `CONTEXT.md` — Ubiquitous Language

## Artifact Auto-Save

After completion, print message:

> Artifacts saved. If the session is interrupted, open a new session and run the next phase — data is safe.

## Rules

- Graph is the SINGLE SOURCE OF TRUTH — do not create redundant overview/summary md files
- Every missing concept/relationship MUST be supplemented, not skipped
- CONTEXT.md contains only domain terms, not technical terms (technical terms belong in the code branch)
- Graphify runs ONLY on docs — DO NOT run on source code
- ⛔ DO NOT modify `graphify-out/` or `.gitnexus/` directly outside graphify workflow (Phase 3 supplementation is the only exception)
