jmagly Research Lint
Run the research corpus lint ruleset against the configured corpus to detect structural and referential integrity issues.
Triggers
- "lint the research corpus"
- "check research integrity"
- "validate research notes"
- "sweep the corpus for issues"
- "research lint"
/research-lint
Parameters
[target] (optional)
Path to lint. When omitted, resolve the target in this order:
<AIWG_CORPUS_ROOT>/documentation/references/whenAIWG_CORPUS_ROOTis set.<research.corpusRoot>/documentation/references/when.aiwg/aiwg.configconfigures a corpus root.documentation/references/when the canonical warehouse layout exists in the project..aiwg/research/for legacy project-local corpora.
--fix (optional)
Attempt auto-fixes for fixable issues (add missing frontmatter defaults, correct formatting).
--format (optional)
Output format: full (default), summary, or json.
--ci (optional)
CI mode — exit code reflects pass/fail.
--fail-on (optional)
Severity threshold for failure: error (default), warn, or info.
Execution Flow
Phase 1: Run Lint
Resolve the default target as described above, then execute the lint runner against the research corpus:
aiwg lint <resolved-target> --ruleset research --format full
This checks all 11 rules in the research ruleset:
| Rule | Severity | What it checks |
|---|---|---|
ref-frontmatter |
error | Required frontmatter fields present |
ref-id-unique |
error | No duplicate REF-XXX identifiers |
ref-id-format |
warn | REF identifiers follow REF-NNN naming |
citation-resolves |
error | Whole REF IDs point to exact or slugged notes anywhere in the lint target |
grade-present |
warn | GRADE quality assessment in frontmatter |
provenance-present |
warn | Provenance metadata present |
cross-ref-bidirectional |
info | Related refs linked both ways |
orphan-detection |
info | Notes with no inbound references |
frontmatter-date-format |
warn | Dates follow ISO 8601 |
source-file-exists |
error | Referenced source files exist |
Phase 2: Report Results
Display the results grouped by file with severity indicators:
- Errors: must be fixed for corpus integrity
- Warnings: should be addressed for corpus quality
- Info: suggestions for improvement
Phase 3: Auto-Fix (if --fix)
When --fix is specified, attempt automatic corrections:
- Missing frontmatter fields — Add fields with sensible defaults:
status: pendingdocumented_date: <today>tags: []
- Date format — Convert dates to ISO 8601
- Missing GRADE — Add
grade_rating: nullplaceholder
Write corrections in place and re-run lint to verify fixes.
Integration Points
| Component | Relationship |
|---|---|
aiwg lint |
Underlying CLI command this skill wraps |
corpus-health |
Lint results feed into health scoring |
induct-research |
Post-induction hook can trigger lint on new notes |
ralph loops |
Lint pass as completion gate |
| CI/CD | aiwg lint --ci --ruleset research --fail-on error |
Examples
# Full corpus lint
/research-lint
# Quick summary
/research-lint --format summary
# CI mode (exit code)
/research-lint --ci --fail-on warn
# Lint specific directory
/research-lint .aiwg/research/findings/
# Auto-fix what's fixable
/research-lint --fix
# JSON output for programmatic use
/research-lint --format json
Sidecar-level integrity (use sidecar-lint)
This skill runs the note/corpus-wide ruleset. It does not inspect citation
sidecar internals (Outgoing/Incoming sections, edge tables, doubled-append
duplicate headers, (see REF doc) authors, affiliation-primary
canonicalization, zero-edge sidecar orphans). For those, use the companion
sidecar-lint skill (aiwg corpus sidecar-lint / sidecar-repair). The two
compose — research-lint for note-level referential integrity, sidecar-lint
for citation-sidecar structure — neither duplicates the other.
References
- @$AIWG_ROOT/agentic/code/frameworks/research-complete/lint/ruleset.yaml
- @$AIWG_ROOT/src/lint/cli.ts
- @$AIWG_ROOT/src/lint/runner.ts
- @$AIWG_ROOT/agentic/code/frameworks/research-complete/skills/sidecar-lint/SKILL.md — sidecar-structural lint + repair