| name | audit-project-research |
| description | Use when you need to audit a research project against the init-project-research template. |
| allowed-tools | Bash(ls*), Bash(readlink*), Bash(git*), Bash(diff*), Bash(jq*), Read, Glob, Grep |
| argument-hint | [project-path or no arguments for CWD] |
Audit Project Research
Compare a research project's directory structure against the current /init-project-research template and report gaps. Report-only.
When to Use
- After revisiting a project set up a while ago
- When the template has been updated and you want to check older projects
- Before submission — verify nothing is missing
- When a project "feels messy" and you want a structured audit
When NOT to Use
- Setting up a new project — use
/init-project-research
- Fixing issues — this skill only reports; user decides what to action
- Auditing all projects at once — use
/atlas-audit (this skill is per-project)
Modes
| Invocation | Behaviour |
|---|
/audit-project-research (no args) | Audits CWD. Aborts if CWD is not a project directory. |
/audit-project-research <project-path> | Audits the given path. Resolves to absolute first. |
Critical Rules
- Read-only by default, narrow scaffold exception. Phases are read-only with one exception: Phase 2.11 auto-creates empty
.gitkeep-stubbed mandatory template dirs (reviews/, correspondence/editorial/, correspondence/referee-reviews/, knowledge/, to-sort/), seeds reviews/INDEX.md and knowledge/_index.md with placeholders, and drops the canonical .latexmkrc into every directory containing *.tex that lacks one. These are decision-free safe defaults—no content choices are made, no existing files are touched. Every other "fix" action remains flag-only. Per rules/review-artefact-routing.md: never auto-create correspondence/internal-reviews/ (legacy dir, superseded; existing instances handled by /tidy-project-reviews).
- Detect project type before checking. Don't flag missing
code/ in theoretical projects.
- Distinguish "missing" from "intentionally absent." Flag but don't alarm.
- Check content quality, not just existence. Empty CLAUDE.md is worth flagging.
- Mirror
/init-project-research. Phases 2–8 below correspond 1:1 to init's Phases 3–9. When init adds a directory or convention, add the matching audit check here AND update /atlas-audit SA1.
Architecture
Ten phases, in order:
- Identify Project — resolve path, detect type, read CLAUDE.md metadata
- Scaffold — common core dirs/files, conditional structure, settings, hooks, rules, LaTeX, GitHub repo, growth patterns (mirrors init Phase 3)
- Seed Files — content quality of CLAUDE.md, README.md, MEMORY.md, current-focus.md (mirrors init Phase 4)
- Overleaf — paper symlinks, Overleaf separation, sibling paper dirs, backup dirs, LaTeX build config, review correspondence (mirrors init Phase 5)
- Git — repo health, branch, untracked files, nested repos, submodules (mirrors init Phase 6)
- Atlas — atlas topic cross-reference, outputs drift (mirrors init Phase 7)
- Task Management Integration —
_index.md, papers/<short>.md, current-focus.md entries (mirrors init Phase 8)
- Literature & Discovery — knowledge wiki, literature-review/, review agent outputs (mirrors init Phase 9)
- Report — three-severity findings table
- Audit Log — timestamped record to
.claude/audits/
Phase 1: Identify Project
-
Resolve to absolute path (argument or CWD).
-
Determine project name from basename. Convention is kebab-case (matches the atlas slug, e.g. article40-access-as-mechanism). Title Case basenames (e.g. Article 40 Access As Mechanism) appear in older projects and are also valid — flag neither as a finding. Flag only basenames with non-conforming characters (spaces in kebab-case slugs, mixed-case-with-spaces, punctuation other than hyphens) as Info.
-
Check if git repo: git -C "<path>" rev-parse --is-inside-work-tree 2>/dev/null.
-
Detect project type:
| Indicator | Implies |
|---|
code/ or data/ | Experimental |
src/ or tests/ | Computational |
Only paper/, docs/, log/ | Theoretical |
| Mix of above | Mixed |
-
Read CLAUDE.md if it exists — extract declared metadata (type, venue, authors, slug).
-
Try to find an Atlas topic file matching the project: find ~/vault/atlas/ -name "<slug>.md". If found, note path for Phase 6.
Phase 2: Scaffold
Audits init's Phase 3 outputs. Sub-steps run in order; results aggregate into the Phase 9 report.
2.1 Pre-template detection
If no .context/ AND no .claude/, flag as pre-template project with consolidated remediation commands. Skip the rest of Phase 2 — this is a structural prerequisite. See references/pre-template-detection.md.
2.2 Common core directories
Record present / missing / degraded. Check: .context/, .claude/, docs/, docs/literature-review/, docs/readings/, docs/venues/, log/, paper*/, knowledge/ (required), reviews/ (required, per rules/review-artefact-routing.md), correspondence/referee-reviews/ (required), correspondence/editorial/ (required), to-sort/ (required).
Legacy flag: correspondence/internal-reviews/ — if present, flag as LEGACY and recommend running /tidy-project-reviews to migrate content to reviews/<source>/ (AI provenance) or correspondence/internal/ (human provenance) per the routing rule.
2.3 Common core files
Check: CLAUDE.md (project root, non-empty), README.md, MEMORY.md, reviews/INDEX.md (required, per rules/review-artefact-routing.md), .gitignore (must include paper-*/backup/ and reviews/**/archived/), .context/current-focus.md, .context/project-recap.md, .claude/settings.local.json.
Legacy flag: REVIEW-STATE.md at project root — if present, flag as LEGACY and recommend running /tidy-project-reviews to move it to reviews/INDEX.md.
Dual-file flag (Gap A): if BOTH <project>/reviews/INDEX.md AND <project>/REVIEW-STATE.md exist, flag as DEGRADED — divergent state. This can happen if the post-Bug-1-fix review-state-log.sh (commit dcbcd9fb) hit a project where the rename Batch A missed (or where a fresh REVIEW-STATE.md was hand-created after retrofit). Recommend running /tidy-project-reviews to merge contents (its Phase 5.2 dedup-merges rows by (Check, Last Run) key) and remove REVIEW-STATE.md.
2.4 Reviews directory canonicalisation
See references/review-consistency.md for canonical registry and legacy-location detection.
2.5 Conditional structure (by project type)
Experimental: code/, code/python/ or code/R/, data/, data/raw/, data/processed/, output/, output/figures/.
Computational: src/, tests/, experiments/, results/, pyproject.toml.
Python tooling: flag requirements.txt as Degraded.
Theoretical: no additional checks.
2.6 Permissions audit (read-only)
Compare .claude/settings.local.json allow against global ~/.claude/settings.json. Flag missing as Degraded. See references/permissions-sync.md.
2.7 Hooks schema validation (read-only)
Every hook entry must use object format {"type": "command", "command": "..."}, not bare strings. See references/hooks-schema.md.
2.8 Rules hygiene (read-only)
Compare project's .claude/rules/ against global rules. Flag byte-identical duplicates as Redundant. See references/rules-sync.md.
2.9 GitHub release repo
Validate structure and hygiene. See references/github-release-repo.md.
Submission-ready projects without an artifact: flag when atlas outputs[] entry is Drafting/Submission-ready/Submitted/R&R and github-repo/ is absent or vault/atlas lack artifact_repo: fields. Recommend /anonymous-artifact. Do not auto-fix.
Skip for theoretical/qualitative projects: Skip artifact-missing check when (a) Project type detected as Theoretical in Phase 1, (b) No .py/.R/.jl/.do/.ipynb/.m files outside excluded dirs, AND (c) Atlas methods: contains only non-computational entries.
2.10 Post-init growth patterns
Classify items beyond scaffold as recognised growth or unrecognised (Info). See references/growth-patterns.md.
2.11 Auto-scaffold mandatory template dirs and files
Create if absent: reviews/ with INDEX.md seeded from the routing-rule template (manifest only — per-source subdirs created lazily), correspondence/editorial/, correspondence/referee-reviews/, knowledge/ (with seed _index.md), to-sort/ (with .gitkeep), .latexmkrc in every dir with *.tex (detect via find -L). Record in audit log. Never overwrite existing files; flag drift as Degraded.
Per rules/review-artefact-routing.md: do NOT auto-create correspondence/internal-reviews/ — that legacy dir is superseded by the human-vs-AI provenance split (correspondence/internal/ for human collaborator feedback, reviews/<source>/ for AI output). If it exists in the project, flag as LEGACY rather than re-create it.
If .gitignore exists and lacks paper-*/backup/ or reviews/**/archived/, flag as DEGRADED and suggest adding (don't auto-edit).
Phase 3: Seed Files
Audits init's Phase 4 outputs. Beyond existence — verify meaningful content.
3.1 CLAUDE.md content
Must have: Project Overview (title, authors, venue, type), Research Questions (≥1), Setup/Overleaf, Folder Structure, Conventions. Flag placeholder text (<title>, TODO, TBD) and excessive length (>200 lines). Vault sync requires Project Overview fields for metadata extraction.
3.2 README.md content
Title, authors, abstract/description, status checklist.
3.3 reviews/INDEX.md content
Per rules/review-artefact-routing.md, the manifest must have:
- Frontmatter or header naming the project
## Latest per source section (table or list of latest report per source slug)## Open issues section (aggregated from per-report headers)## Stale sources section (producers with no report in last 60 days)
If the project still has a legacy REVIEW-STATE.md at root instead of reviews/INDEX.md, flag as LEGACY and direct to /tidy-project-reviews.
Legacy 10-column schema (Gap C). If reviews/INDEX.md exists but its content starts with the legacy 10-column REVIEW-STATE.md table header (| Paper | Check | Last Run | Verdict | Score | Open Issues | Source | Trigger | Report | Notes |), flag as DEGRADED — legacy schema. This is the Batch A (2026-05-17) retrofit pattern: 278 projects had their REVIEW-STATE.md renamed to reviews/INDEX.md verbatim without translating the content into the "Latest per source" manifest. The legacy schema is functional (rows continue to append correctly via the helper) but doesn't render the way /review-recap expects post-2026-05-17. Recommend running /review-recap to migrate content; do NOT auto-rewrite (audit is read-only here).
3.4 .gitignore content
Must include: .DS_Store, __pycache__/, out/, paper/ (if Overleaf-managed), paper-*/backup/ (Overleaf snapshots, per routing rule), reviews/**/archived/ (archived reports, per routing rule).
3.5 .context/current-focus.md content
Should be updated beyond "Project just initialised" if commits exist beyond the initial one.
Phase 4: Overleaf
Audits init's Phase 5 outputs. The nested-pattern paper directory is the cross-cutting concern.
4.1 Paper directory convention (nested pattern)
Each paper*/ must contain a paper/ symlink → Overleaf with relative path (absolute paths break across machines). See references/paper-dir-conventions.md.
4.2 Overleaf separation
Scan all paper*/ directories for forbidden file types (code, data, package files). Hard rule — violations are Missing. See references/overleaf-separation.md.
4.3 Sibling paper directory check
Detect near-duplicate paper-*/ dirs and overlapping symlink targets. See references/paper-dir-conventions.md.
4.4 Backup directory
Each paper-{venue}/ should contain backup/ subdirectory. Flag root-level backup/ as wrong-convention. See references/paper-dir-conventions.md.
4.5 LaTeX build config
Every dir with .tex must have .latexmkrc with $out_dir = 'out'. Critical: use find -L to traverse Overleaf symlinks. Auto-scaffolded by Phase 2.11. See references/latex-build-config.md.
4.6 Review correspondence consistency
Verify paper-{venue}/correspondence/referee-reviews/ structure. See references/review-consistency.md.
4.7 Talk directory convention
If the project has a talk/deck (a paper-{venue}/talk/ dir, or a presentations/ dir, or any *-talk.tex/landing page), verify it follows the convention: the talk/ layout ({venue}-talk.tex, speaker-script.md, references.bib, .latexmkrc, figures/ incl. qr-{slug}.png, out/), a project-local links/{slug}/index.html as source of truth, and the correct folder pattern (archival → paper-{venue}/talk/; non-archival/seminar → presentations/). Flag deploy-only landing pages (no project copy), a missing speaker-script.md, a QR subtitle that over-promises resources the landing page lacks, and a local paper.pdf card that should be a DOI link. Report-only (these are talk artefacts, not init-scaffolded). See references/talk-dir-conventions.md.
Phase 5: Git
Audits init's Phase 6 outputs. If not a git repo: flag as Missing (default since Feb 2026). If git repo, check: branch name (main or master), untracked files, remote status, nested repos (.git/ subdir → Missing; note: submodules have .git as file, use find -mindepth 2 -name .git), submodule tracking (if .gitmodules exists, verify checked out).
Phase 6: Atlas
Audits init's Phase 7 outputs. Skip if no Atlas topic file found in Phase 1. Check drift on slug / status / venue / paper-dir / co-authors fields. See references/atlas-checks.md.
Phase 7: Task Management Integration
Audits init's Phase 8 outputs. Verify context library entries: 7.1 index row in .context/projects/_index.md; 7.2 paper file at .context/projects/papers/<short>.md with valid frontmatter; 7.3 mention in .context/current-focus.md. See references/task-management-integration.md.
Phase 8: Literature & Discovery
Audits init's Phase 9 outputs.
8.1 Knowledge wiki
knowledge/_index.md should exist if non-empty. If last updated > 90 days with recent activity, flag Degraded.
8.2 Literature review presence
If project status > Idea: expect *-initial-review.md or literature_summary.md. If any paper-*/ has \cite{}, expect references.bib.
8.3 Review agent outputs
If reviews/ exists, verify structure follows the routing rule (rules/review-artefact-routing.md):
- Per-source subdirs match the canonical R1 source slug table (
paper-critic/, domain-reviewer/, referee2-reviewer/, etc. — NOT variants like referee2/, peer-review/, fix/)
- Files inside each source folder follow
YYYY-MM-DD.md, YYYY-MM-DD-HHMM.md (the timestamp-precision form review agents now write after the 5-agent patch commit 23ebcfff), OR YYYY-MM-DD-<descriptor>.md (manual descriptor form for same-day reruns)
reviews/INDEX.md exists at the reviews/ root- No review reports at the project root (
./CRITIC-REPORT.md and similar are rule violations)
- No content files under
correspondence/internal-reviews/ (legacy)
If any of these checks fail, flag as DEGRADED and recommend /tidy-project-reviews to retrofit. See references/review-agent-outputs.md for the legacy reference (now superseded by the routing rule).
Phase 9: Report
Three severity levels:
| Level | Meaning |
|---|
| Missing | Expected by template, not present |
| Degraded | Present but incomplete or has issues |
| Info | May be intentional — no action needed unless it bothers you |
Full report format with severity markers and remediation lines: references/report-format.md.
Phase 10: Audit Log
After presenting the report, save a timestamped log to .claude/audits/ in the project:
- Create
.claude/audits/ if it doesn't exist (this is the only directory the skill creates — it's a self-contained audit trail, not a project-state mutation).
- Write
YYYY-MM-DD-structure-audit.md with:
- Date, project name, detected type
- Summary table (Missing / Degraded / Info counts with items)
- Remaining items (not addressable by user via standard skill commands)
- If an audit log already exists for today, append a suffix:
-2, -3, etc.
Persistent audit trail so future sessions can see what was checked and when.
What This Skill Does NOT Do
- Does not create or fix anything in the project (except writing the audit log to
.claude/audits/ in Phase 10)
- Does not check file content beyond seed files
- Does not compare against other projects (use
/atlas-audit for that)
- Does not enforce uniformity — identifies unintentional gaps
Cross-References
/init-project-research — the template this skill audits against. Structural checks here mirror init's scaffold. When init adds a new directory or convention (e.g., github-repo/), add a matching audit check here AND update /atlas-audit SA1./atlas-audit — batch-audits all projects via SA1. SA1's structure checks must stay consistent with this skill's phases./sync-permissions — fixes Phase 2.5 permissions findings./project-safety — safety rules and folder guardrails./update-project-doc — fixes stale documentation (run after this audit)./compile-knowledge — fixes Phase 8.1 empty-knowledge-wiki findings.
Papers-layout checks (2026-07-03, FB directive)
Per rules/submission-file-archive.md § Topic-folder layout, audit:
- No stray submission artifacts outside
paper-<venue>/ — flag any docs/submission-history/, docs/venues/*/submission/, or root-level as-submitted PDFs.
- Archive dirs resolve — every
files:/submitted_files: pointer in the project's vault submissions + atlas outputs exists on disk under paper-<venue>/submission/archive/ (or published/, correspondence/, talk/, presentations/).
PAPER-HISTORY.md freshness — run uv run "$(head -1 ~/.config/task-mgmt/path)/scripts/generate-paper-history.py" --project . --check; report stale/missing (fix = regenerate, one command).- Filename taxonomy — archived files follow
{surface}-{stage}[-{role}] (no exemptions).
