Erlemar/gist:37c62e7afca0e25d7553547fabc18afd

## gistfile1.txt
Fill one broken-link stub in the DSWoK vault: research the topic, draft the note in DSWoK voice, run `draft-critic-mm`, save to the right folder, and refresh `missing_notes.md`.

Use the path `ROOT = '/Documents/DSWoK'`.

## Inputs

- `$ARGUMENTS` (optional). If provided, treat as the stub title to fill (e.g. "AUC", "Negative sampling", "T5"). If omitted, pick the highest-impact stub from `missing_notes.md` (most references first; ties broken by alphabetical order).

## Workflow

1. **Read context.**
   - `missing_notes.md` — the stub list and reference counts.
   - `.claude/writing_style_guide.md` — voice, spelling, AI-tells, tag rules.
   - `CLAUDE.md` — frontmatter taxonomy.
   - `feedback_aliases_purpose.md` (in memory) — alias synonym rule.

2. **Pick the stub.**
   If `$ARGUMENTS` given, use it. Otherwise read `missing_notes.md` and pick the highest-priority entry (most references). Validate the title looks like a real note name (contains letters, no Python list literals — see "Scanner gotcha" below).

3. **Locate references.**
   Use `Grep` for `[[<title>]]` across the vault to read 2–3 surrounding lines per occurrence. The referencing context tells you what role the note needs to play (e.g. NDCG was used as a ranking metric → deep-dive metric note, not a hub).

4. **Pick the destination folder** based on the stub's topical group in `missing_notes.md`:
   - Metrics: `Metrics and losses/`
   - NLP: `NLP/`
   - Deep Learning: `Deep Learning/`
   - General ML: `General ML/`
   - Use case: `Use_cases/`

5. **Find a structural template.**
   Read 1–2 existing well-formed notes in the same folder. For metrics, `f1 score.md` (~30 lines, focused) and `Confusion matrix.md` (~95 lines, deeper) bracket the typical depth. For NLP architectures, `BERT.md` and `Transformer.md` are the references. Match the depth of the closest structural sibling. Also read `Calibration.md` if the topic touches ranking, recommendation, or sampling — production calibration concerns must appear in the draft.

6. **Research via 3–5 sources — search actively, don't rely on memory.**
   For any topic beyond the most basic, run a web search before drafting. Working memory drifts on domain specifics: formula sign conventions, parameter names, citation venues, deprecated APIs, post-2024 work. Don't trust recall for a reference note.

   - **Search first.** Use `WebSearch` for the topic name with a recency qualifier (e.g., "calibration KDE 2022", "negative sampling logQ correction recsys") to surface canonical and recent work. Identify the seminal paper, the most-cited follow-ups, and any 2022–2025 reformulations.
   - **For every citation, fetch the actual page.** Do not trust author names, arXiv IDs, or venue information from memory. If you cite a paper, WebFetch its arXiv/DOI/openreview page and confirm: (a) the title matches, (b) the authors listed match what you claimed, (c) the venue (NeurIPS / ICML / ICLR / JMLR etc.) matches. **Wrong author attribution is a blocking error.**
   - **Prefer publisher DOI or arXiv** over conference re-uploads or PDF mirrors.
   - **Use Wikipedia** for formal definitions of mathematical objects, but cite the original paper for the concept itself.
   - **Cross-check at least one practitioner source** (scikit-learn docs, Hugging Face docs, Evidently AI, established MLOps blogs) for production-relevant detail.
   - **For any equation or comparative claim, find a source.** Sign and direction conventions in monotonic transformations (log-odds shifts, recalibration maps, IPS estimators, prior corrections) are easy to misremember or invert. Verify against the source's actual notation.

6.5. **Verify each cited URL before pasting it into the draft.**
   `WebFetch` or `curl -sL` each external link. Watch for: (a) corporate-blog redirects to a generic landing page after acquisitions or migrations; (b) DOIs that resolve to paywalled previews when an open arXiv version is available; (c) Wikipedia URLs that drift over time; (d) GitHub permalinks vs branch URLs that go stale. **Hard-to-verify citations are blocking errors.** If a citation cannot be verified, replace it with a hedge or remove it entirely — do not paste an unverified URL.

   - **Every specific numeric claim needs a citation or must be removed.** "1:1 to 1:3 hard-to-random ratio", "P99 50–100 ms latency", "requires ~1M examples" — if you cannot point to the source, drop the claim. Do not invent specifics to sound authoritative.

7. **Determine note type and structure.**
   - **Single-method deep-dive** (e.g. NDCG, GRU, T5): intro with citation → core math/algorithm → variants → when to use → limitations → code example callout → links.
   - **Concept overview** (e.g. Tokenization, Collaborative Filtering): intro → main approaches with one paragraph each → comparison table if ≥3 alternatives → trade-offs → links.
   - **Stub-and-pointer** (rarely): a few paragraphs that satisfy the broken link by pointing to the better-developed adjacent note (e.g. when the topic is genuinely sub-covered by a hub note already).

   **Code example is required for single-method deep-dives.** If the note has no code callout, the draft is incomplete. Include a `> [!example]-` collapsible callout with minimal runnable code (5–15 lines) that demonstrates the core idea or API. Exception: metric stubs with no computational implementation (e.g. MAP, MRR) may omit code.

8. **Draft the note.**
   Apply the [DSWoK frontmatter taxonomy](../../CLAUDE.md):
   - 1 domain tag (or omitted for foundational cross-domain notes — see CLAUDE.md exceptions)
   - 1 role tag (`algorithm`, `architecture`, `evaluation`, `loss`, `concept`, `interview-questions`)
   - 0–2 theme tags from the approved whitelist. Do not invent tag values.
   - Aliases for acronyms or alternative wordings of the *same* concept (not related-concept synonyms). **Alias violations are blocking.** Test: would another note naturally write `[[<alias>]]` inline and mean *this* note? Acronym ↔ spelled-out form, grammatical or qualified variants of the same name qualify. Adjacent concepts and sub-method names do not (e.g., "NCE" and "sampled softmax" are not valid aliases for "Negative sampling" — they are related but distinct; mention them inline instead). See `feedback_aliases_purpose.md` in memory.
   - `cssclasses: [term-table]` only if the note has a definition table with inline math.

   Style rules to follow strictly (full guide at `.claude/writing_style_guide.md`):
   - American spelling. Sentence-case headings.
   - No bullet-label bold; the colon is enough.
   - No banned vocabulary (delve, leverage as verb, robust as vague qualifier, showcase, foster, etc.).
   - Em dashes for syntactic parentheticals only, never as rhetorical drumrolls. Prefer colons for definitional expansion.
   - One idea per sentence. Sentences with 3+ chained clauses (`which … and … because …`) or stacked metaphors are split candidates.
   - No first-person, no anecdotes, no closing aphorisms.

   **Math verification.** For every equation or causal claim involving a monotonic transformation (log-odds shift, calibration map, prior correction, IPS weighting, normalization): reverse-derive from first principles, or sanity-check with a degenerate special case (e.g., when training prevalence equals production prevalence, the prior-correction shift should equal zero). Sign errors in the literature and in working memory are common; don't trust formula direction without a check.

   **Diagram decision.** Decide whether the note benefits from a visual. If yes, follow the diagram tooling order from `.claude/writing_style_guide.md`: **Mermaid** for flowcharts/pipelines/decision trees → **Excalidraw** for charts and conceptual diagrams (write `.excalidraw.md` source; user opens in Obsidian, plugin auto-exports `*.excalidraw.light.svg`/`*.excalidraw.dark.svg` next to the source) → **hand-authored SVG in `images/`** only when Excalidraw cannot produce the figure cleanly after a couple of iterations. Don't default to inline SVG out of CLI convenience.

9. **Cross-link to adjacent vault notes.**
   Add `[[Adjacent note]]` wikilinks inline in the body where related concepts come up. The `## Links` section is for external citations only — do not add a "see also" list of internal wikilinks at the top. Inline coverage is sufficient for navigation; a duplicated internal-wikilinks list at the end of `## Links` reads as ceremony. The `## Links` section should contain 2–4 external authoritative sources (paper DOI, library docs, an explanatory walkthrough).

   **Calibration cross-link is required** for any note covering ranking, recommendation, or sampling. Add `[[Calibration]]` inline in the section discussing prior correction or distribution mismatch.

10. **Run `draft-critic-mm`.**
    Invoke the `draft-critic-mm` agent on the new file with: "Review the newly drafted DSWoK vault note at <path>. This is a reference note, not a blog post — skip book-review-specific checks." Flag as Blocking: any sentence with "learns to", "decides to", "understands" (anthropomorphism); any sentence with "provides a", "enables", "delivers" as a vague intensifier (marketing register); any "Advantage" / "Limitation" header that reads as promotional rather than factual. Address every Blocking issue. Apply Suggested improvements that are clear wins; skip the ones the agent itself marks optional.

11. **Save the note** at the correct path. The filename matches the wikilink target exactly (case-sensitive on the macOS check — `NDCG.md`, not `Ndcg.md`).

12. **Regenerate `missing_notes.md`** by running the `/update-missing-notes` script.

13. **Verify.** Read the regenerated `missing_notes.md`:
    - The filled stub no longer appears.
    - Confirm any new wikilinks the note added are either (a) targets that already exist in the vault, or (b) intentional new entries to track.
    - Hand-clean any obvious scanner false positives (see Scanner gotcha).

14. **Report** to the user:
    - File created: `<path>` (~N lines).
    - Critic: blocking issues fixed; suggestions applied / skipped.
    - `missing_notes.md`: was N targets, now N-1.
    - Any new broken links the note introduced that need follow-up.

## Quality bar

The note is publishable as-is on dswok.com. That means:
- It would not embarrass the author next to `Confusion matrix.md` or `Transformer.md`.
- A practitioner reading the note for the first time leaves with the formal definition, the practical decision context, and a working code example.
- The Limitations section names real failure modes with citations or specifics, not platitudes.
- Cross-links connect the note to the rest of the graph; it does not become an orphan.
- All citations have been verified against the actual paper pages (authors, title, venue match the claim).
- No specific numeric claim without a citation.

For high-traffic foundational notes (`Recommendation system`, `Calibration`, `Training-serving skew`, and similar), expect a tight v1 (~80–110 lines, one structural template's worth of depth) followed by 1–2 expansion rounds when domain feedback surfaces additions. Don't try to ship the maximalist version on round 1; let v1 be reviewable, then add depth. Subsequent rounds typically catch new content (multi-class taxonomy, prior correction, alternative methods, illustrative diagrams) and small factual fixes (sign conventions, citation URLs, deprecated parameter names).

Even when the user explicitly approves a section in a triage step ("apply (a)", "yes, add"), they may trim it during a second-pass curation after reading the integrated note. Treat removal as a "didn't earn its space in context" signal, not as a "user changed their mind" complaint. Don't reintroduce trimmed content in subsequent rounds without new justification.

Vault notes are reference material describing concepts and patterns, not release-gate or operational artifacts. Avoid pre-launch / pre-deployment checklists, runbook-style "do these steps in order" sections, and other prescriptive process content. Diagnostic question lists ("when X breaks, ask these") are fine; prescriptive verification lists ("before launch confirm these") are not — those belong in operational runbooks, not reference notes.

## Scanner gotcha

The `/update-missing-notes` regex matches `[[anything]]` and will misread numpy 2D-array literals like `np.asarray([[3, 2, 1]])` as wikilinks. After regeneration, scan the Uncategorized section for entries with no letters or with comma-separated numbers and remove them by hand. The proper fix would patch the script to skip fenced code blocks; flag this if it bites repeatedly.

## What this skill does NOT do

- It does not add practitioner-perspective sections ("When to use", "Production considerations" with experiential color). Those live in a separate flow (`/practitioner-perspective`) so the author can answer the standardized questions in their own voice before synthesis.
- It does not edit the referencing notes. Once the stub is filled, the broken `[[X]]` links resolve automatically.
- It does not commit. Stop after Step 14 so the author can review.
	Fill one broken-link stub in the DSWoK vault: research the topic, draft the note in DSWoK voice, run `draft-critic-mm`, save to the right folder, and refresh `missing_notes.md`.

	Use the path `ROOT = '/Documents/DSWoK'`.

	## Inputs

	- `$ARGUMENTS` (optional). If provided, treat as the stub title to fill (e.g. "AUC", "Negative sampling", "T5"). If omitted, pick the highest-impact stub from `missing_notes.md` (most references first; ties broken by alphabetical order).

	## Workflow

	1. Read context.
	- `missing_notes.md` — the stub list and reference counts.
	- `.claude/writing_style_guide.md` — voice, spelling, AI-tells, tag rules.
	- `CLAUDE.md` — frontmatter taxonomy.
	- `feedback_aliases_purpose.md` (in memory) — alias synonym rule.

	2. Pick the stub.
	If `$ARGUMENTS` given, use it. Otherwise read `missing_notes.md` and pick the highest-priority entry (most references). Validate the title looks like a real note name (contains letters, no Python list literals — see "Scanner gotcha" below).

	3. Locate references.
	Use `Grep` for `[[<title>]]` across the vault to read 2–3 surrounding lines per occurrence. The referencing context tells you what role the note needs to play (e.g. NDCG was used as a ranking metric → deep-dive metric note, not a hub).

	4. Pick the destination folder based on the stub's topical group in `missing_notes.md`:
	- Metrics: `Metrics and losses/`
	- NLP: `NLP/`
	- Deep Learning: `Deep Learning/`
	- General ML: `General ML/`
	- Use case: `Use_cases/`

	5. Find a structural template.
	Read 1–2 existing well-formed notes in the same folder. For metrics, `f1 score.md` (~30 lines, focused) and `Confusion matrix.md` (~95 lines, deeper) bracket the typical depth. For NLP architectures, `BERT.md` and `Transformer.md` are the references. Match the depth of the closest structural sibling. Also read `Calibration.md` if the topic touches ranking, recommendation, or sampling — production calibration concerns must appear in the draft.

	6. Research via 3–5 sources — search actively, don't rely on memory.
	For any topic beyond the most basic, run a web search before drafting. Working memory drifts on domain specifics: formula sign conventions, parameter names, citation venues, deprecated APIs, post-2024 work. Don't trust recall for a reference note.

	- Search first. Use `WebSearch` for the topic name with a recency qualifier (e.g., "calibration KDE 2022", "negative sampling logQ correction recsys") to surface canonical and recent work. Identify the seminal paper, the most-cited follow-ups, and any 2022–2025 reformulations.
	- For every citation, fetch the actual page. Do not trust author names, arXiv IDs, or venue information from memory. If you cite a paper, WebFetch its arXiv/DOI/openreview page and confirm: (a) the title matches, (b) the authors listed match what you claimed, (c) the venue (NeurIPS / ICML / ICLR / JMLR etc.) matches. Wrong author attribution is a blocking error.
	- Prefer publisher DOI or arXiv over conference re-uploads or PDF mirrors.
	- Use Wikipedia for formal definitions of mathematical objects, but cite the original paper for the concept itself.
	- Cross-check at least one practitioner source (scikit-learn docs, Hugging Face docs, Evidently AI, established MLOps blogs) for production-relevant detail.
	- For any equation or comparative claim, find a source. Sign and direction conventions in monotonic transformations (log-odds shifts, recalibration maps, IPS estimators, prior corrections) are easy to misremember or invert. Verify against the source's actual notation.

	6.5. Verify each cited URL before pasting it into the draft.
	`WebFetch` or `curl -sL` each external link. Watch for: (a) corporate-blog redirects to a generic landing page after acquisitions or migrations; (b) DOIs that resolve to paywalled previews when an open arXiv version is available; (c) Wikipedia URLs that drift over time; (d) GitHub permalinks vs branch URLs that go stale. Hard-to-verify citations are blocking errors. If a citation cannot be verified, replace it with a hedge or remove it entirely — do not paste an unverified URL.

	- Every specific numeric claim needs a citation or must be removed. "1:1 to 1:3 hard-to-random ratio", "P99 50–100 ms latency", "requires ~1M examples" — if you cannot point to the source, drop the claim. Do not invent specifics to sound authoritative.

	7. Determine note type and structure.
	- Single-method deep-dive (e.g. NDCG, GRU, T5): intro with citation → core math/algorithm → variants → when to use → limitations → code example callout → links.
	- Concept overview (e.g. Tokenization, Collaborative Filtering): intro → main approaches with one paragraph each → comparison table if ≥3 alternatives → trade-offs → links.
	- Stub-and-pointer (rarely): a few paragraphs that satisfy the broken link by pointing to the better-developed adjacent note (e.g. when the topic is genuinely sub-covered by a hub note already).

	Code example is required for single-method deep-dives. If the note has no code callout, the draft is incomplete. Include a `> [!example]-` collapsible callout with minimal runnable code (5–15 lines) that demonstrates the core idea or API. Exception: metric stubs with no computational implementation (e.g. MAP, MRR) may omit code.

	8. Draft the note.
	Apply the [DSWoK frontmatter taxonomy](../../CLAUDE.md):
	- 1 domain tag (or omitted for foundational cross-domain notes — see CLAUDE.md exceptions)
	- 1 role tag (`algorithm`, `architecture`, `evaluation`, `loss`, `concept`, `interview-questions`)
	- 0–2 theme tags from the approved whitelist. Do not invent tag values.
	- Aliases for acronyms or alternative wordings of the same concept (not related-concept synonyms). Alias violations are blocking. Test: would another note naturally write `[[<alias>]]` inline and mean this note? Acronym ↔ spelled-out form, grammatical or qualified variants of the same name qualify. Adjacent concepts and sub-method names do not (e.g., "NCE" and "sampled softmax" are not valid aliases for "Negative sampling" — they are related but distinct; mention them inline instead). See `feedback_aliases_purpose.md` in memory.
	- `cssclasses: [term-table]` only if the note has a definition table with inline math.

	Style rules to follow strictly (full guide at `.claude/writing_style_guide.md`):
	- American spelling. Sentence-case headings.
	- No bullet-label bold; the colon is enough.
	- No banned vocabulary (delve, leverage as verb, robust as vague qualifier, showcase, foster, etc.).
	- Em dashes for syntactic parentheticals only, never as rhetorical drumrolls. Prefer colons for definitional expansion.
	- One idea per sentence. Sentences with 3+ chained clauses (`which … and … because …`) or stacked metaphors are split candidates.
	- No first-person, no anecdotes, no closing aphorisms.

	Math verification. For every equation or causal claim involving a monotonic transformation (log-odds shift, calibration map, prior correction, IPS weighting, normalization): reverse-derive from first principles, or sanity-check with a degenerate special case (e.g., when training prevalence equals production prevalence, the prior-correction shift should equal zero). Sign errors in the literature and in working memory are common; don't trust formula direction without a check.

	Diagram decision. Decide whether the note benefits from a visual. If yes, follow the diagram tooling order from `.claude/writing_style_guide.md`: Mermaid for flowcharts/pipelines/decision trees → Excalidraw for charts and conceptual diagrams (write `.excalidraw.md` source; user opens in Obsidian, plugin auto-exports `.excalidraw.light.svg`/`.excalidraw.dark.svg` next to the source) → hand-authored SVG in `images/` only when Excalidraw cannot produce the figure cleanly after a couple of iterations. Don't default to inline SVG out of CLI convenience.

	9. Cross-link to adjacent vault notes.
	Add `[[Adjacent note]]` wikilinks inline in the body where related concepts come up. The `## Links` section is for external citations only — do not add a "see also" list of internal wikilinks at the top. Inline coverage is sufficient for navigation; a duplicated internal-wikilinks list at the end of `## Links` reads as ceremony. The `## Links` section should contain 2–4 external authoritative sources (paper DOI, library docs, an explanatory walkthrough).

	Calibration cross-link is required for any note covering ranking, recommendation, or sampling. Add `[[Calibration]]` inline in the section discussing prior correction or distribution mismatch.

	10. Run `draft-critic-mm`.
	Invoke the `draft-critic-mm` agent on the new file with: "Review the newly drafted DSWoK vault note at <path>. This is a reference note, not a blog post — skip book-review-specific checks." Flag as Blocking: any sentence with "learns to", "decides to", "understands" (anthropomorphism); any sentence with "provides a", "enables", "delivers" as a vague intensifier (marketing register); any "Advantage" / "Limitation" header that reads as promotional rather than factual. Address every Blocking issue. Apply Suggested improvements that are clear wins; skip the ones the agent itself marks optional.

	11. Save the note at the correct path. The filename matches the wikilink target exactly (case-sensitive on the macOS check — `NDCG.md`, not `Ndcg.md`).

	12. Regenerate `missing_notes.md` by running the `/update-missing-notes` script.

	13. Verify. Read the regenerated `missing_notes.md`:
	- The filled stub no longer appears.
	- Confirm any new wikilinks the note added are either (a) targets that already exist in the vault, or (b) intentional new entries to track.
	- Hand-clean any obvious scanner false positives (see Scanner gotcha).

	14. Report to the user:
	- File created: `<path>` (~N lines).
	- Critic: blocking issues fixed; suggestions applied / skipped.
	- `missing_notes.md`: was N targets, now N-1.
	- Any new broken links the note introduced that need follow-up.

	## Quality bar

	The note is publishable as-is on dswok.com. That means:
	- It would not embarrass the author next to `Confusion matrix.md` or `Transformer.md`.
	- A practitioner reading the note for the first time leaves with the formal definition, the practical decision context, and a working code example.
	- The Limitations section names real failure modes with citations or specifics, not platitudes.
	- Cross-links connect the note to the rest of the graph; it does not become an orphan.
	- All citations have been verified against the actual paper pages (authors, title, venue match the claim).
	- No specific numeric claim without a citation.

	For high-traffic foundational notes (`Recommendation system`, `Calibration`, `Training-serving skew`, and similar), expect a tight v1 (~80–110 lines, one structural template's worth of depth) followed by 1–2 expansion rounds when domain feedback surfaces additions. Don't try to ship the maximalist version on round 1; let v1 be reviewable, then add depth. Subsequent rounds typically catch new content (multi-class taxonomy, prior correction, alternative methods, illustrative diagrams) and small factual fixes (sign conventions, citation URLs, deprecated parameter names).

	Even when the user explicitly approves a section in a triage step ("apply (a)", "yes, add"), they may trim it during a second-pass curation after reading the integrated note. Treat removal as a "didn't earn its space in context" signal, not as a "user changed their mind" complaint. Don't reintroduce trimmed content in subsequent rounds without new justification.

	Vault notes are reference material describing concepts and patterns, not release-gate or operational artifacts. Avoid pre-launch / pre-deployment checklists, runbook-style "do these steps in order" sections, and other prescriptive process content. Diagnostic question lists ("when X breaks, ask these") are fine; prescriptive verification lists ("before launch confirm these") are not — those belong in operational runbooks, not reference notes.

	## Scanner gotcha

	The `/update-missing-notes` regex matches `[[anything]]` and will misread numpy 2D-array literals like `np.asarray([[3, 2, 1]])` as wikilinks. After regeneration, scan the Uncategorized section for entries with no letters or with comma-separated numbers and remove them by hand. The proper fix would patch the script to skip fenced code blocks; flag this if it bites repeatedly.

	## What this skill does NOT do

	- It does not add practitioner-perspective sections ("When to use", "Production considerations" with experiential color). Those live in a separate flow (`/practitioner-perspective`) so the author can answer the standardized questions in their own voice before synthesis.
	- It does not edit the referencing notes. Once the stub is filled, the broken `[[X]]` links resolve automatically.
	- It does not commit. Stop after Step 14 so the author can review.
No results found