validate-techniques

name	validate-techniques
description	Technique module maintenance — validates conventions, checks paper pulls, detects duplicates, verifies registration, and auto-fixes import issues.

Validate Technique Modules

Mental Model

Technique modules in resources/techniques/ implement research paper algorithms as self-contained Python files. Each module is one paper's technique, imported independently by notebooks and other code. This skill validates both the code (import health, conventions) and the library (registration, paper pulls, duplicates).

What This Skill Checks

1. Import Health

Every technique module must import cleanly without errors. Failures indicate broken dependencies or syntax problems.

Verification (per module):

python -c "from resources.techniques.{slug} import *; print('OK')"

Automated batch check:

for f in resources/techniques/*.py; do
  slug=$(basename "$f" .py)
  [ "$slug" = "__init__" ] && continue
  result=$(python -c "from resources.techniques.$slug import *; print('OK')" 2>&1)
  if [ "$result" != "OK" ]; then
    echo "FAIL: $slug — $result"
  fi
done

2. Convention Compliance

Verified conventions (these are consistently followed across the codebase):

Convention	Check	Auto-fix?
from __future__ import annotations	First line after docstring	Yes — insert if missing
Exported: section	Module docstring lists all public symbols	No — requires understanding module purpose
No cross-imports	No from resources.techniques.{sibling} imports	No — requires design decision

Not universal conventions (present in most but not all modules — do not enforce):

• Shape comments (# [B, S, D] style) — used in complex modules, not in simple utility functions
• Typed constructor args — present in newer modules, not in all older ones

3. Registration Integrity

Every technique with a .py file should have a corresponding entry in references/papers.md.

Cross-reference checks:

• Slug in papers.md matches filename (strip .py)
• Technique module path is correct in the table's Technique module column
• Paper summary exists in docs/upstream/papers/{slug}.md

Known unregistered modules (files exist but no papers.md entry): Check by comparing ls resources/techniques/*.py against grep '' references/papers.md`:

sahoo2024mdlm, lou2024sedd, ding2026deletion, yang2026dare,
arriola2025blockdiff, zhang2026expertchoice, yu2026introspective,
nie2025llada, rafailov2023dpo, jang2017gumbel, deepseek2025grpo,
lee2025lookum, peng2025papl, cao2026soar

Auto-fix: Add missing entries to references/papers.md in the appropriate section. For each:

1. Read the module's docstring for title, authors, arXiv ID
2. Add a table row with slug, title, arXiv link, and technique module path
3. Verify the paper summary exists in docs/upstream/papers/

4. Paper Pull Status

Every registered paper should have its PDF downloaded to docs/upstream/pdfs/.

PDF naming convention: {arxiv_id}-{slug}.pdf Example: 2010.01412-foret2021sam.pdf

Check:

python tools/pull_pdfs.py --list

This lists all papers and whether their PDF exists. Papers without PDFs show ·.

Auto-fix — pull missing PDFs:

python tools/pull_pdfs.py --all

Or for specific slugs:

python tools/pull_pdfs.py {slug1} {slug2}

Papers without arXiv IDs (e.g., wales1997basinhopping — a 1997 chemistry paper) cannot be pulled. Report but skip.

Rate limit: pull_pdfs.py enforces 2 seconds between downloads.

5. Duplicate Detection

Some techniques have multiple implementations. Known duplicates:

Canonical file	Alternate file(s)	Status
chen2026attnres.py	attn_res.py	Both exist; __init__.py documents attn_res as "alternate implementation"
jaegle2021perceiver.py	perceiver.py	Both exist; __init__.py documents perceiver as "alternate implementation"
dohare2023plasticity.py	dohare2024plasticity.py	Same arXiv ID (2306.13812) but different implementations — 2023 is per-weight utility, 2024 is per-unit utility tracking (Nature published)

Detection approach:

1. Read __init__.py — it explicitly lists alternate implementations
2. Compare class/function names across modules using AST parsing or grep
3. Check for same arXiv IDs across different slugs

Action: Report duplicates but do NOT auto-fix. Resolving requires deciding:

• Which is the canonical implementation?
• Should the alternate be deleted, deprecated, or moved?
• For dohare2023 vs dohare2024: the 2024 version is the published Nature paper — consider whether the 2023 preprint implementation adds value.

6. Superseded Paper Detection

A technique may be superseded by a newer paper. This requires manual judgment — no auto-fix.

Detection approach:

1. Read each paper summary in docs/upstream/papers/{slug}.md
2. Search for language like "extends", "improves upon", "replaces", "builds on", "supersedes"
3. Check if the same arXiv ID appears under multiple slugs (see dohare pair above)
4. For papers with many citations, check if a follow-up paper by the same authors exists in the library

Known supersession patterns to watch:

• Same author, sequential years (e.g., dohare2023 → dohare2024)
• Paper explicitly references and improves a prior technique
• arXiv v2/v3 updates that supersede the original

Action: Add a note to the paper summary's metadata if supersession is detected. Do not delete or deprecate without explicit decision.

---

Anti-Patterns to Fix

Pattern	Where to Look	Fix	Auto-fix?
Missing from __future__ import annotations	Top of file, after docstring	Add the import	Yes
Technique not registered	references/papers.md	Add table row	Yes
Missing paper summary	docs/upstream/papers/{slug}.md	Create from module docstring	No — requires research
Missing PDF	docs/upstream/pdfs/	Run python tools/pull_pdfs.py {slug}	Yes
Import failure	python -c "from resources.techniques.X import *"	Debug and fix the import error	Case-by-case
Duplicate module	__init__.py alternate list	Report; requires design decision	No

---

Execution Workflow

Full validation run:

# 1. Check imports for all technique modules
for f in resources/techniques/*.py; do
  slug=$(basename "$f" .py)
  [ "$slug" = "__init__" ] && continue
  python -c "from resources.techniques.$slug import *; print('OK: $slug')" 2>&1 || echo "FAIL: $slug"
done

# 2. Find unregistered techniques
comm -23 \
  <(ls resources/techniques/*.py | xargs -I{} basename {} .py | grep -v __init__ | sort) \
  <(grep '`' references/papers.md | sed 's/.*`\([^`]*\)`.*/\1/' | sort)

# 3. Check paper pull status
python tools/pull_pdfs.py --list

# 4. Pull any missing PDFs
python tools/pull_pdfs.py --all

Single module validation:

# For a specific slug (e.g., foret2021sam):
python -c "from resources.techniques.foret2021sam import *; print('OK')"
grep 'foret2021sam' references/papers.md
ls docs/upstream/papers/foret2021sam.md
ls docs/upstream/pdfs/*foret2021sam* 2>/dev/null || echo "PDF missing"

---

Auto-Fix Capabilities

Fix	How	Safe?
Add from __future__ import annotations	Insert after docstring, before first import	Yes — no runtime effect in Python 3.12+
Add registration to papers.md	Append row to appropriate section	Yes — additive only
Pull missing PDF	python tools/pull_pdfs.py {slug}	Yes — downloads to expected path

Not auto-fixed (requires human judgment):

• Resolving duplicate modules
• Deciding supersession handling
• Creating paper summaries (requires reading the paper)
• Fixing import errors (requires understanding the failure)

---

Report Format

STATUS: [no_work | fixed | issues_found]

CHANGES:
- resources/techniques/{slug}.py: Added `from __future__ import annotations`
- references/papers.md: Added registration for {slug}
- docs/upstream/pdfs/{arxiv_id}-{slug}.pdf: Pulled from arXiv

WARNINGS:
- Duplicate: {slug1}.py ↔ {slug2}.py (same classes, different implementations)
- Superseded: {old_slug} may be superseded by {new_slug}
- Import failed: {slug} — {error message}

UNREGISTERED:
- {slug} — file exists but no papers.md entry