agentleFS
matvej-melikhovmatvej-melikhov/karpathy-llm-wiki/.claude/skills/lint/SKILL.md

lint

Skill2 starsChanged 6 months agoMITView on GitHub

Ревьюер Obsidian wiki-vault. Запускает статические проверки + script auto-fixes, затем агентские проверки (Layer 2) и LLM-fix'ы, в конце ведёт диалог с пользователем по оставшимся ask-issues. Единственный owner всего post-detection пайплайна — вызывается напрямую (`/lint`) или из ingest в конце synthesis-цикла. Триггеры: /lint, "lint", "проверка здоровья", "очисти wiki", "проверь wiki", "найди сирот", "wiki audit".

82 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use project, coverage and 6 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • BugRogerSkill

    project

    Project lifecycle management. Dispatches to Ada.

    Also in 5 projects that use this

  • PydanticSkill

    coverage

    Fetch coverage diff from Codecov for the current branch or a specific PR. Shows uncovered lines, patch coverage, and overall coverage change.

    Also in 4 projects that use this

  • GitHubSkill

    state-management

    CoreAI Sandbox's TanStack Query + mock-JSON data layer. USE WHEN: editing data-fetching hooks (`app/hooks/use*.ts`), adding mock data in `app/data/`, or wiring a component to query state.

    Also in 3 projects that use this

  • AWSSkill

    issue

    Implement a GitHub issue end-to-end — branch, code, test, docs, and commit.

    Also in 4 projects that use this

  • AnthropicSkill

    digest

    Generate a daily or weekly digest of activity across all connected sources. Use when catching up after time away, starting the day and wanting a summary of mentions and action items, or reviewing a week's decisions and document updates grouped by project.

    Also in 3 projects that use this

  • toneron2Skill

    capture

    Capture thoughts to inbox with automatic classification

    Also in 4 projects that use this

The file

Files
SKILL.md

lint: пайплайн ревью wiki

Lint — единственный owner всего пайплайна обработки issues. Когда скилл вызван (пользователем напрямую или из ingest), он:

  1. Запускает bin/static_lint.py (Layer 1 + script auto-fixes inline).
  2. Запускает Layer 2 — LLM-семантические проверки.
  3. Применяет agent auto-fixes (missing-summary, domain-order, tag-casing).
  4. Ведёт диалог с пользователем по оставшимся ask-issues.
  5. Перезаписывает lint-state.json финальным состоянием.

После выполнения: либо все issues разрешены (open_issues пуст), либо остались явно отложенные пользователем («позже»).


Итоговый отчёт (всегда первым в чате)

После Step 1 и Step 4 (то есть когда уже понятна суммарная статистика по авто-фиксам) — выдай одну строку сводки ещё до ask-диалога:

Lint завершён. Script auto-fix: 5 (inline-tags×2, non-canonical-wikilink×2, missing-summary handled by agent). Agent auto-fix: 1 (missing-summary). Ask: 2.

Правила:

  • Сводка — одна строка, в формате «N (тип×k, тип×k, …)» для каждой категории. Если в категории один issue — тип без ×k.
  • Источник script-фиксов — lint-state.json::applied_script_fixes. Это список {type, where}, собранный скриптом за этот запуск.
  • Если applied_script_fixes пуст — пиши «Script auto-fix: 0» или вообще опусти эту часть.
  • Если хочешь дать полный список «что и где» — оборачивай в <details>, чтобы не загромождать чат:

    <details>
    <summary>Что было автоматически исправлено</summary>
    
    - inline-tags → wiki/ideas/X.md
    - inline-tags → wiki/ideas/Y.md
    - non-canonical-wikilink → wiki/entities/Z.md
    …
    
    </details>
  • Если open_issues пуст и applied_script_fixes пуст — короткое «wiki чистая, изменений не было», без таблиц.

Дальше — ask-диалог по оставшимся issues, как обычно.


Pipeline

Step 1. Запустить bin/static_lint.py

python3 bin/static_lint.py          # --quick (default)
python3 bin/static_lint.py --full   # full audit

Скрипт сам делает:

  • skip-check (если wiki не менялась и нет накопленных issues — пропуск)
  • детект 13 типов issues (Layer 1) + 2 embedding-based (Layer 1.5)
  • inline применение script auto-fixes для всех script-fixable типов
  • запись lint-state.json с remaining issues (agent-fix + ask + skip)

Embedding-based проверки (similar-but-unlinked, synthesis-drift, contradiction_candidates) запускаются всегда, если есть wiki/meta/embeddings.json. Если эмбеддингов нет (embedder недоступен) — warning + skip только этих checks, остальные работают.

В режиме --quick (по умолчанию) скрипт фильтрует scope: новые issues эмитятся только для touched pages (контент-хеш изменился с прошлого lint), старые issues для не-touched сохраняются. В --full scope не ограничен.

Step 2. Прочитать lint-state.json

Получить:

  • open_issues — всё что не пофиксил скрипт
  • contradiction_candidates (опц.) — пары для Layer 2

Если open_issues пуст и contradiction_candidates нет — pipeline закончен, ничего больше делать не нужно. Сообщить пользователю «wiki чистая».

Step 3. Layer 2 — LLM-проверки

См. секцию «Layer 2» ниже. Дописывает свои issues в open_issues (в памяти, запись на диск только в Step 6).

Step 4. Agent auto-fixes

Для issues типа missing-summary, domain-order, tag-casing (см. секцию «Agent auto-fixes» ниже) применить LLM-генерируемые правки. Удалить применённые из open_issues.

Step 5. Ask-dialogue

Оставшиеся ask-issues спросить у пользователя одним батчем (см. «Ask-dialogue»). По каждому ответу применить соответствующее действие, удалить из open_issues. Issues с ответом «отложить» остаются в open_issues.

Step 6. Записать финальное состояние

Если в Step 3-5 что-то поменялось — пересчитать wiki_hash и записать lint-state.json с обновлённым open_issues. Иначе оставить как есть.


Layer 2: LLM-проверки

Layer 2 запускается этим скиллом после Layer 1+1.5. Каждая проверка ниже — самостоятельное задание: дано что найти, формат issue, граничные случаи. Способ исполнения (как читать страницы, в каком порядке, в одном батче или нескольких) — на твоё усмотрение. Используй доступные артефакты (перечислены в каждой секции) и применяй естественный triage.

domain-order

Цель: в поле domain: домены должны быть упорядочены от частного к общему. Первый = primary classification, используется для раскраски в knowledge map.

Что НЕ флагуем:

  • Параллельные/cross-cutting домены без иерархии: [Machine Learning, Knowledge Management] — оба корневые, иерархии нет.
  • Один домен — упорядочивать нечего.

Issue format:

{
  "type": "domain-order",
  "where": "wiki/ideas/PPO.md",
  "current": ["Machine Learning", "Reinforcement Learning"],
  "expected": ["Reinforcement Learning", "Machine Learning"],
  "reasoning": "RL ⊂ ML"
}

Это знание о мире (RL — поддомен ML), а не структурное свойство wiki. Скриптовые подсчёты member-pages ломаются на молодой wiki, поэтому LLM.

tag-casing

Цель: теги во frontmatter с правильным регистром. Аббревиатуры uppercase (ML, RL, IR, NLP, RLHF), обычные слова TitleCase (Code, Optimization, Alignment).

Что флагуем:

  • Lowercase аббревиатуры: ml → ML, rl → RL.
  • Lowercase обычные слова: optimization → Optimization.
  • Очевидные опечатки регистра: mL → ML.

Что НЕ флагуем:

  • Уже-uppercase аббревиатуры: ML, RL, IR, RLHF.
  • Capitalized обычные слова: Code, Optimization, Math, Alignment.
  • Канонические аббревиатуры с нестандартным регистром: LoRA, MapReduce, KMeans.

Issue format (один issue на тег):

{
  "type": "tag-casing",
  "where": "wiki/ideas/X.md",
  "current": "ml",
  "expected": "ML",
  "reasoning": "ML — аббревиатура (Machine Learning)"
}

contradiction

Цель: найти пары страниц с прямо противоречивыми утверждениями (одна говорит X, другая ¬X на ту же тему).

Что НЕ контрадикция:

  • Дополняющие утверждения («A это X», «A также Y»).
  • Утверждения на разные подтемы.
  • Несогласованности в формулировках без логического противоречия.

Доступные артефакты:

  • lint-state.json::contradiction_candidates — список пар, отфильтрованный Layer 1.5 по cosine similarity. Это primary entry point — пары, у которых даже теоретически может быть противоречие. Если поле есть — начинай отсюда.
  • Если нет (эмбеддинги не доступны) — построй кандидатов сам через topic-overlap (общие домены, общие теги, упоминания друг друга).

Issue format:

{
  "type": "contradiction",
  "page_a": "wiki/ideas/A.md",
  "page_b": "wiki/ideas/B.md",
  "claim": "<одно предложение про что они расходятся>"
}

outdated-claim

Цель: утверждение в более старой странице опровергнуто более новой.

Проверяй только пары где даты updated: различаются и темы пересекаются. Можно использовать те же contradiction_candidates. Дополнительная эвристика: A.updated < B.updated, B содержит явное «X has been replaced», «Y is no longer recommended», «previously, but now» паттерны.

Issue format:

{
  "type": "outdated-claim",
  "where": "wiki/ideas/A.md",
  "claim": "<устаревшее утверждение в A>",
  "conflicts_with": "wiki/ideas/B.md"
}

missing-concept

Цель: концепция упомянута в ≥3 разных content-страницах, но своей wiki-страницы у неё нет — кандидат на создание.

Что считается «упоминанием»:

  • Capitalized one-word terms (аббревиатуры, имена методов): GAE, LoRA, BERT.
  • Multi-word concepts: Monte Carlo, Temporal Difference Learning, Markov Decision Process.

Что НЕ считается упоминанием:

  • Wikilinks ([[GAE]]) — отдельный case, ловится dead-link.
  • Code blocks (fenced или inline code) — это примеры/код, не нарратив.
  • Meta-страницы (wiki/cache.md, wiki/log.md, wiki/index.md).

Threshold: 3 разных страницы (не 3 упоминания). Повторное упоминание в одной странице не накручивает.

Доступная эвристика: Bash-grep по capitalized phrases, sort | uniq -c, top кандидатов — дешёвый pre-filter. Дальше LLM судит «реальный концепт достойный страницы или общеупотребительное слово».

Issue format:

{
  "type": "missing-concept",
  "term": "GAE",
  "mentioned_in": ["wiki/ideas/PPO.md", "wiki/ideas/TD Learning.md",
                    "wiki/ideas/Advantage Function.md"]
}

Agent auto-fixes

Применяются автоматически (без вопросов пользователю), но требуют LLM.

missing-summary

Контент-страница без summary: во frontmatter (либо summary: "").

Действие:

  1. Прочитать страницу целиком.
  2. Сгенерировать саммари ≤120 символов: одно декларативное предложение, что это и зачем. Без отсылок к источнику, без «эта страница описывает...».
  3. Вписать в frontmatter одинарными YAML-кавычками: summary: 'текст'. Двойные кавычки только если внутри есть одинарная. Внутри текста допустимы :, $, \, диакритика — одинарные кавычки безопасны.
  4. На следующем Stop-hook'е bin/gen_index.py подхватит саммари в wiki/index.md.
  5. Удалить issue из open_issues.

Если страница пустая (нет body) — взять тему из заголовка/aliases, описать максимально кратко.

domain-order

Issue эмитится Layer 2 (см. выше), здесь применяем.

Действие:

  1. Прочитать domain: блок из frontmatter where.
  2. Переписать в порядке из expected (массив имён в правильном порядке).
  3. Сохранить wikilink-формат ("[[Domain Name]]") — поменять только порядок.
  4. Удалить issue из open_issues.

tag-casing

Issue эмитится Layer 2 (см. выше), применяем здесь.

Действие:

  1. Прочитать tags: массив из where.
  2. Заменить current на expected.
  3. Удалить issue из open_issues.

Ask-dialogue

Оставшиеся issues (тип ≠ auto-fix и ≠ agent-fix) спросить у пользователя одним батчем. Категории см. в таблице ниже.

Формат вопроса

Lint нашёл проблемы, требующие решения:

1. [dead-link] [[SFT]] упомянута в [[RLHF]], страницы нет.
   → создать заглушку / убрать ссылку / отложить?

2. [orphan] [[Foo Bar]] никем не упомянута.
   → удалить / слинковать с [[X]] / отложить?

3. [missing-concept] "GAE" в [[PPO]], [[TD Learning]], [[Advantage]].
   → создать idea-страницу / отложить?

4. [contradiction] [[A]] и [[B]] (similarity 0.87): <claim>
   → разрешить (какая страница права?) / отложить?

5. [asymmetric-related] [[A]] → [[B]], но [[B]] не ссылается на [[A]].
   → симметризовать / удалить одностороннюю / отложить?

6. [similar-but-unlinked] [[PPO]] и [[Policy Gradient]] (cosine 0.87)
   семантически близки, но wikilink между ними отсутствует.
   → связать в обе стороны / связать в одну / игнорировать / отложить?

7. [synthesis-drift] [[RLHF]] (drift 0.42) сильно отклонилась от
   эмбеддинга своих источников. Возможна галлюцинация.
   → перечитать страницу и сравнить с источником / отложить?

Действия по ответам

  • «Создать [[X]]» (dead-link, missing-concept) → создать stub-страницу по _templates/idea.md (или entity если контекст указывает) с минимальным содержанием, удалить issue.
  • «Убрать ссылку» (dead-link) → удалить wikilink из тела родительской страницы, удалить issue.
  • «Удалить» (orphan) → удалить файл целиком, удалить issue.
  • «Слинковать с [[X]]» (orphan) → дописать wikilink на текущую страницу в подходящую родительскую (выбрать X агентски), удалить issue.
  • «Симметризовать» (asymmetric-related) → дописать [[A]] в related: страницы B, удалить issue.
  • «Удалить одностороннюю» (asymmetric-related) → удалить [[B]] из related: страницы A, удалить issue.
  • «Создать domain» (dangling-domain-ref) → создать wiki/domains/<missing_domain>.md из _templates/domain.md с минимальным описанием, удалить issue.
  • «Убрать domain» (dangling-domain-ref) → удалить [[<missing_domain>]] из поля domain: страницы, удалить issue.
  • «Связать обе» (similar-but-unlinked) → добавить [[B]] в related: A И [[A]] в related: B, удалить issue.
  • «Связать одну» (similar-but-unlinked) → спросить направление, добавить wikilink в related: соответствующей страницы, удалить issue.
  • «Игнорировать» (similar-but-unlinked) → удалить issue (могут быть параллельные сущности, связь не нужна).
  • «Разрешить» (contradiction, outdated-claim) → агент применяет правильное утверждение к одной из страниц или к обеим, удалить issue.
  • «Перечитать» (synthesis-drift) → прочитать страницу + связанные [[raw/...]], сверить, при необходимости обновить, удалить issue.
  • «Отложить» / «позже» → оставить issue в open_issues. Снова всплывёт при следующем /lint.

Несколько issues разом

Пользователь может ответить пачкой («1 — создать, 2 — отложить, 3, 4 — симметризовать»). Применить каждый ответ к соответствующему issue.


Категории issues

Каждый issue имеет type — категория определяет, на каком шаге pipeline он обрабатывается.

Script auto-fix (Step 1, inline в static_lint.py)

Применяется самим скриптом, не доходит до lint-скилла. Перечислено для контекста.

typeУсловиеСтруктура issue
status-not-in-enumstatus не из evaluation/in-progress/ready{type, where, value, fix}
invalid-fieldsfrontmatter не соответствует _templates/<type>.md. Subtype extra (удалить поле) или missing (добавить с default из шаблона){type, where, subtype, field}
inline-tagstags: [a, b] инлайн вместо block YAML{type, where}
raw-link-with-extension[[raw/X.md]] вместо [[raw/X]]{type, where, link}
raw-ref-in-body[[raw/...]] в теле страницы{type, where, link, line}
folder-type-mismatchwiki/<X>/ vs type: рассогласованы{type, where, current_type, expected_type}
non-canonical-wikilinkpath-prefixed [[wiki/ideas/X]] вместо [[X]]{type, where, link, fix, context}
binary-source-outside-formatsбинарь в raw/ вне raw/formats/{type, where, suggested}

Agent auto-fix (Step 4)

Требует LLM (генерация контента или семантическое суждение). См. секцию выше.

typeУсловиеСтруктура
missing-summarycontent-страница без summary:{type, where, page_type}
domain-orderLLM-issue, см. Layer 2{type, where, current, expected, reasoning}
tag-casingLLM-issue, см. Layer 2{type, where, current, expected, reasoning}

Ask user (Step 5)

Требует решения пользователя.

typeУсловиеСтруктура
dead-linkwikilink на несуществующую страницу{type, where, what, context}
orphanстраница без входящих wikilinks{type, where}
missing-conceptконцепция в ≥3 страницах без своей page{type, term, mentioned_in}
contradictionпротиворечие двух страниц{type, page_a, page_b, claim}
outdated-claimутверждение опровергнуто более новой{type, where, claim, conflicts_with}
dangling-domain-refdomain: на несуществующую domain-страницу{type, where, missing_domain}
asymmetric-relatedA.related → B без B.related → A{type, page_a, page_b}
similar-but-unlinkedдве страницы близки, wikilink отсутствует (если эмбеддинги доступны){type, page_a, page_b, similarity, threshold}
synthesis-driftстраница ушла далеко от центроида источников (если эмбеддинги доступны){type, where, drift, threshold}

Skip

Информационные флаги, не спрашиваем:

typeУсловие
style-nitстилистические замечания (не декларативное настоящее, отсутствие линка на не-ключевую сущность)

Команда и флаги

КомандаПоведение
/lint--quick (default): skip-check по wiki_hash; новые issues эмитятся только для touched pages (контент-хеш изменился с прошлого lint); старые issues для не-touched сохраняются. Embedding checks (similar-but-unlinked, synthesis-drift) запускаются всегда если есть wiki/meta/embeddings.json.
/lint --fullПолный audit. Skip-check игнорируется, scope не ограничен. Используется periodically для глубокой проверки (раз в неделю, или после массового рефактора).

Touched detection: wiki_hash сохраняется как aggregate, page_hashes — per-page sha256. На первом запуске после миграции state'а bootstrap трактует все страницы как touched (де-факто = --full).


Конвенции wiki

См. CLAUDE.md раздел Frontmatter — схема, типы, поля. Здесь не дублируем.


Что lint не делает

  • Не лезет в raw/. raw-источники иммутабельны (кроме transcript-конвертации через transcribe).
  • Не правит content-файлы по ask-issues самостоятельно. Только после явного решения пользователя.
  • Не запускает синтез. Это работа ingest. lint только чинит.
  • Не удаляет файлы без явного «удалить» от пользователя (на orphan).

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.