--- namespace: aiwg name: verify-citations platforms: [all] description: Verify all citations in a document against the research corpus commandHint: category: research-quality --- # Verify Citations Command Validate that all citations, references, and factual claims are backed by actual sources in the research corpus. ## Instructions When invoked, perform systematic citation verification: 1. **Parse Target File** - Load the specified file (or all markdown files if no path given) - Extract all citation patterns: - `@.aiwg/research/sources/*` references - `@.aiwg/research/findings/*` references - `REF-XXX` inline references - DOI patterns (`10.XXXX/...`) - Author-year patterns (`Author et al., YYYY`) - **RLM citation patterns** (#1225): `[@, L-]` and path-only fallback `[, L-]` 2. **Verify Each Citation** - Check file existence for @-mention references - Validate REF-XXX against frontmatter in corpus - Verify DOI format validity - Check page number ranges - Validate quoted text against source - **For RLM citations**: verify cited file exists; if `content_hash` present, recompute current hash and compare (see [RLM Citation Verification](#rlm-citation-verification) below) 3. **Detect Hallucinations** - Flag citations to non-existent files - Flag fabricated DOIs - Flag statistics without sources - Flag author names not in corpus 4. **Check GRADE Compliance** - Load quality assessment for each cited source - Compare hedging language to evidence quality - Flag overclaiming (HIGH-confidence language for LOW evidence) 5. **Generate Report** - Display summary table (total, valid, issues) - List each issue with severity and fix suggestion - Include RLM Citations section when present (Fresh / Stale / Un-versioned counts) - Provide overall PASS/FAIL verdict 6. **Auto-Fix Mode (--fix)** - Downgrade hedging language for GRADE violations - Remove citations to non-existent sources (with comment) - Add TODO markers for sources needing verification - For STALE RLM citations: leave them in place but annotate with `[STALE: hash mismatch]`; do not auto-rewrite (the agent that emitted them must decide whether the new content still supports the claim) ## RLM Citation Verification When the target file contains RLM-format citations (#1205, #1223), `verify-citations` validates them against the current state of the cited artifacts. ### Citation patterns The skill recognizes two inline forms (matching the schema at `agentic/code/addons/rlm/schemas/citation-tuple.json`): - **Versioned**: `[@, ]` — full provenance with content hash - Example: `[src/auth/login.ts@a8f9c2d4e5f60718, L42-58]` - **Path-only fallback**: `[, ]` — citation without content hash (artifact wasn't in the index when emitted) - Example: `[src/legacy/auth.py, L88]` The `lines` field is optional in both forms. ### Verdict logic For **versioned** RLM citations: 1. Resolve `` to a project-relative file path 2. If file does not exist → verdict: **MISSING** (error) 3. If file exists, compute its current content hash using the same routine as the artifact index: sha256, truncated to first 16 hex chars (matches `src/artifacts/index-builder.ts:243`) 4. Compare to the citation's `content_hash`: - **Match** → verdict: **FRESH** (pass) - **Mismatch** → verdict: **STALE** (warning by default; error in `--strict`) For **path-only fallback** RLM citations: 1. Resolve `` to a project-relative file path 2. If file does not exist → verdict: **MISSING** (error) 3. If file exists → verdict: **UN-VERSIONED** (warning by default; error in `--strict`) Stale verdict means the file content has changed since the citation was emitted — the claim may no longer be supported by the cited region. The simple hash-mismatch heuristic doesn't distinguish whitespace edits from semantic changes; richer semantic-drift detection is the responsibility of `aiwg index doctor --rlm-audit` (#1208). ### Hash computation The hash routine MUST match the index implementation exactly so citations emitted by `rlm-batch` round-trip cleanly: ``` sha256(file_contents).hexdigest()[0:16] ``` See `src/artifacts/index-builder.ts:243` for the canonical implementation. Any verification logic that diverges from this convention will produce false stale verdicts. ### Report format When RLM citations are present, the report adds a new section: ``` RLM Citations: 12 total ✓ Fresh: 9 ⚠ Stale: 2 ⚠ Un-versioned: 1 ✗ Missing: 0 STALE citations: - [src/auth/login.ts@a8f9c2d4e5f60718, L42-58] Current hash: f3b2c1d4e5a60718 File modified since citation emitted UN-VERSIONED citations: - [src/legacy/auth.py, L88] File exists but no content hash; consider running through aiwg index ``` ### Mode flags - **Default mode**: auto-detects both research-corpus citations (existing behavior) and RLM citations (new). No flag required. - **`--rlm`**: opt-in to RLM-only mode — skip @-mention research-corpus checks. Useful when verifying RLM-aggregated outputs in CI without research-corpus context. - **`--strict`**: existing flag — STALE and UN-VERSIONED RLM citations escalate from warnings to errors and produce non-zero exit. ## Arguments - `[file-path]` - File to verify (default: all `.md` files in current directory) - `--strict` - Treat warnings as errors (including STALE and UN-VERSIONED RLM citations) - `--fix` - Automatically fix GRADE violations and remove hallucinated citations (does not rewrite RLM citations — see #6 above) - `--report` - Save report to `.aiwg/reports/citation-verification.md` - `--corpus-only` - Only check @-mention references, skip author-year patterns - `--rlm` (#1225) - Verify RLM citations only; skip research-corpus checks ## References - @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/rules/citation-policy.md - Citation enforcement rules - @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/agents/citation-verifier.md - Citation Verifier agent - @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/schemas/research/citation-audit.yaml - Audit schema - @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/schemas/research/hallucination-detection.yaml - Detection patterns - @$AIWG_ROOT/agentic/code/addons/rlm/schemas/citation-tuple.json - RLM citation tuple schema (#1223) - @$AIWG_ROOT/agentic/code/addons/rlm/skills/rlm-batch/SKILL.md - RLM citation emission contract --- Source attribution: jmagly Original project: https://github.com/jmagly/aiwg/blob/bc0cd4d707708593ef15781cb9d38364ea29bdd5/agentic/code/frameworks/sdlc-complete/skills/verify-citations/SKILL.md License: MIT License information: https://opensource.org/license/mit Original upstream instructions; downloaded from Mega AI Hub. ## Upstream license notice MIT License Copyright (c) 2024 Joe Magly Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # Mega AI Hub resource metadata Creator / publisher: jmagly Original project: https://github.com/jmagly/aiwg/blob/bc0cd4d707708593ef15781cb9d38364ea29bdd5/agentic/code/frameworks/sdlc-complete/skills/verify-citations/SKILL.md Attribution basis: Source repository record Fields of work: Content & Media, Education & Research, Marketing Roles: Content Marketer, Copywriter, Researcher Specialties: API, Cross Platform Tools: Tool not specified Country applicability: Country not specified Classification basis: Source catalog labels Instruction SHA-256: 27eafba0c55b9bc2f17761e3f8cd04b92663c192857661768dd9cc1802bc6b63