til-lint

Files (1)

• SKILL.md

SKILL.md (first lines)

> **TIL_PATH**: All `${TIL_PATH}/...` references below resolve to the vault's configured TIL path (injected at SessionStart). Bash expands `${TIL_PATH}` automatically. For `Read`/`Edit`/`Glob`/`Write` tools, substitute the resolved value before passing it as an argument (e.g. `${TIL_PATH}/SCHEMA.md` → `40-Resources/til/SCHEMA.md`). Default `til` when not injected; call MCP `til_get_path` if you need the current value.

# TIL Lint Skill

Scan the TIL collection for structural issues and suggest fixes. Diagnose, don't auto-fix.

## Modes

- **Default (full)**: All 7 checks; vault-wide scan; diagnose-only (read-only).
- **Fast** (`--fast` flag, used by `/save` auto-lint loop): low-latency subset for a single file or category.
  - **Included**: Check 1 (Frontmatter Validation), Check 2 (Orphan TILs and MOC Coverage), and `${TIL_PATH}/SCHEMA.md` rule violations
  - **Excluded**: Check 3 (Broken/Unresolved Links — heavy `til_get_context` traversal), Check 4 (Backlog Consistency — vault-wide compare), Check 5 (SRS Coverage), Check 6 (Stale Content), Check 7 (Raw Source Coverage)
  - **Scope**: limited to the file or category argument; no full vault scan
  - **Output**: structured `## Violations` block (see Step 3) for downstream parsing

## MCP Tools

- `til_list`: Full TIL inventory (category grouping, search)
- `til_get_context`: Link relationships, unresolved mentions for a topic
- `til_backlog_status`: Backlog progress per category (with sections when filtered)
- `til_recent_context`: Recent activity (mtime-based)
- `til_review_list`: SRS review stats (total tracked, due today)
- `til_backlog_check`: Mark backlog item as completed (used in fix actions)
- `til_review_update`: Record review result or register for SRS (used in fix actions)

## Step 1: Collect Inventory

1. **Read `${TIL_PATH}/SCHEMA.md`** for current conventions. If missing, use built-in defaults and emit a warning in the report ("`${TIL_PATH}/SCHEMA.md` not found — using built-in defaults. Run `/omt-setup` to seed.").
2. Call `til_list` (no filters) to get all TILs and categories
3. Call `til_backlog_status` to get all backlog progress
4. Call `til_review_list` (`include_content: false`) to get SRS stats
5. Use `Glob` with pattern `raw/**/*.md` to list all raw source files
6. Use `Glob` with pattern `${TIL_PATH}/**/MOC.md` to list category MOC files
7. If category argument provided, repeat above calls with category filter

## Step 2: Run Checks

Perform all checks below. For each issue found, record category, file path, and issue type.

### Check 1: Frontmatter Validation

Validate each TIL file against `${TIL_PATH}/SCHEMA.md` rules (with built-in fallback when SCHEMA.md is missing):
- Required fields present: `title`, `date`, `category`, `tags`, `aliases`
- `tags` array includes `"til"`
- `date` is valid ISO format (YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS)
- Optional `related` field, if present, must be a string array of `${TIL_PATH}/{category}/{slug}.md` paths

### Check 2: Orphan TILs and MOC Coverage

For each TIL, call `til_get_context` with the filename slug as topic.
A TIL is **orphan** when: `matchedFiles` backlinks count = 0 AND the TIL is not listed in any MOC (root or category).

**Root MOC** (`${TIL_PATH}/TIL MOC.md`):
- TILs not listed in MOC (warning)
- MOC entries pointing to non-existent files (error)

**Category MOC** (`${TIL_PATH}/{category}/MOC.md`, only checked when present):
- TILs in that category not listed in the category MOC (warning)
- Category MOC entries pointing to non-existent files (error)
- Both root and category MOC count toward "is this TIL referenced by any MOC?" — orphan only when neither references it

### Check 3: Broken and Unresolved Links

From `til_get_context` results, collect:
- `unresolvedMentions`: links pointing to files that don't exist
- Group by source file for the report

### Check 4: Backlog Consistency

Compare `til_backlog_status` sections with `til_list`:
- Backlog item marked `[x]` but no corresponding TIL file exists
- TIL file exists but backlog item still marked `[ ]`

### Check 5: SRS Coverage

Compare total TIL count (`til_list`) with SRS tracked count (`til_review_list` stats).
- Flag TILs not registered for spaced repetition review
- Report coverage percentage

### Check 6: Stale Content

Call `til_recent_context` with `days: 180`.
- TILs NOT in the recent list = older than 6 months without modification
- Prioritize categories with fast-changing topics (framework, tool, library)

### Check 7: Raw Source Coverage

Scan all TIL files for `## References` sections containing `raw/` paths.
Compare with the full raw file inventory from Step 1.

- **Unprocessed raw**: Files in `raw/` not referenced by any TIL's References section
- **Broken raw reference**: TIL References contains a `raw/` path but the file doesn't exist

## Step 3: Generate Report

### Default (full) format

Present findings grouped by severity:

```
## TIL Lint Report

### Errors (must fix)
- Broken links (N)
- Missing required frontmatter (N)
- Backlog mismatches (N)
- Broken raw references (N)

### Warnings (should fix)
- Orphan TILs — no inbound links (N)
- Not in MOC (N)
- Not registered for SRS (N)

### Info
- Stale TILs — 6+ months without update (N)
- SRS coverage: X%
- Unprocessed raw sources (N)
- Raw sources total: N files
- Total: N TILs across M categories

From SongYunSeop/oh-my-til, MIT.

More from SongYunSeop/oh-my-til