research-lint

namespace	aiwg
platforms	["all"]
name	research-lint
description	Run the research corpus lint ruleset to detect structural and referential integrity issues — orphan notes, missing frontmatter, broken references, missing GRADE assessments.
commandHint	{"argumentHint":"[target] [--fix] [--format full|summary|json] [--ci] [--fail-on error|warn|info]","allowedTools":"Read, Write, Bash, Glob, Grep","model":"sonnet","category":"research-validation","modelRole":"coding","modelTier":"standard"}

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:

1. <AIWG_CORPUS_ROOT>/documentation/references/ when AIWG_CORPUS_ROOT is set.
2. <research.corpusRoot>/documentation/references/ when .aiwg/aiwg.config configures a corpus root.
3. documentation/references/ when the canonical warehouse layout exists in the project.
4. .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:

1. Missing frontmatter fields — Add fields with sensible defaults:
   • status: pending
   • documented_date: <today>
   • tags: []
2. Date format — Convert dates to ISO 8601
3. Missing GRADE — Add grade_rating: null placeholder

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