Awesome-Agent-Skills-for-Empirical-Research deep-audit

install

source · Clone the upstream repo

git clone https://github.com/brycewang-stanford/Awesome-Agent-Skills-for-Empirical-Research

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/brycewang-stanford/Awesome-Agent-Skills-for-Empirical-Research "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/12-pedrohcgs-claude-code-my-workflow/dot-claude/skills/deep-audit" ~/.claude/skills/brycewang-stanford-awesome-agent-skills-for-empirical-research-deep-audit && rm -rf "$T"

manifest: skills/12-pedrohcgs-claude-code-my-workflow/dot-claude/skills/deep-audit/SKILL.md

source content

/deep-audit — Repository Infrastructure Audit

Run a comprehensive consistency audit across the entire repository, fix all issues found, and loop until clean.

When to Use

After broad changes (new skills, rules, hooks, guide edits)
Before releases or major commits
When the user asks to "find inconsistencies", "audit", or "check everything"

Workflow

PHASE 1: Launch 4 Parallel Audit Agents

Launch these 4 agents simultaneously using

Task

with

subagent_type=general-purpose

Agent 1: Guide Content Accuracy

Focus:

guide/workflow-guide.qmd

All numeric claims match reality (skill count, agent count, rule count, hook count)
All file paths mentioned actually exist on disk
All skill/agent/rule names match actual directory names
Code examples are syntactically correct
Cross-references and anchors resolve
No stale counts from previous versions

Agent 2: Hook Code Quality

Focus:

.claude/hooks/*.py

and

.claude/hooks/*.sh

No remaining
```
/tmp/
```
usage (should use
```
~/.claude/sessions/
```
)
Hash length consistency (
```
[:8]
```
across all hooks)
Proper error handling (fail-open pattern: top-level
```
try/except
```
with
```
sys.exit(0)
```
)
JSON input/output correctness (stdin for input, stdout/stderr for output)
Exit code correctness (0 for non-blocking, non-zero only when intentionally blocking)
```
from __future__ import annotations
```
for Python 3.8+ compatibility
Correct field names from hook input schema (
```
source
```
not
```
type
```
for SessionStart)
PreCompact hooks print to stderr (stdout is ignored)

Agent 3: Skills and Rules Consistency

Focus:

.claude/skills/*/SKILL.md

and

.claude/rules/*.md

Valid YAML frontmatter in all files
No stale
```
disable-model-invocation: true
```
```
allowed-tools
```
values are sensible
Rule
```
paths:
```
reference existing directories
No contradictions between rules
CLAUDE.md skills table matches actual skill directories 1:1
All templates referenced in rules/guide exist in
```
templates/
```

Agent 4: Cross-Document Consistency

Focus:

README.md

docs/index.html

docs/workflow-guide.html

All feature counts agree across all 3 documents
All links point to valid targets
License section matches LICENSE file
Directory tree matches actual structure
No stale counts from previous versions

PHASE 2: Triage Findings

Categorize each finding:

Genuine bug: Fix immediately
False alarm: Discard (document WHY it's false for future rounds)

Common false alarms to watch for:

Quarto callout
```
## Title
```
inside
```
:::
```
divs — this is standard syntax, NOT a heading bug
```
allowed-tools
```
linter warning — known linter bug (Claude Code issue #25380), field IS valid
Counts in old session logs — these are historical records, not user-facing docs

PHASE 3: Fix All Issues

Apply fixes in parallel where possible. For each fix:

Read the file first (required by Edit tool)
Apply the fix
Verify the fix (grep for stale values, check syntax)

PHASE 4: Re-render if Guide Changed

guide/workflow-guide.qmd

was modified:

quarto render guide/workflow-guide.qmd
cp guide/workflow-guide.html docs/workflow-guide.html

PHASE 5: Loop or Declare Clean

After fixing, launch a fresh set of 4 agents to verify.

If new issues found → fix and loop again
If zero genuine issues → declare clean and report summary

Max loops: 5 (to prevent infinite cycling)

Key Lessons from Past Audits

These are real bugs found across 7 rounds — check for these specifically:

Bug Pattern	Where to Check	What Went Wrong
Stale counts ("19 skills" → "21")	Guide, README, landing page	Added skills but didn't update all mentions
Hook exit codes	All Python hooks	Exit 2 in PreCompact silently discards stdout
Hook field names	post-compact-restore.py	SessionStart uses `source` , not `type`
State in /tmp/	All Python hooks	Should use `~/.claude/sessions/<hash>/`
Hash length mismatch	All Python hooks	Some used `[:12]` , others `[:8]`
Missing fail-open	Python hooks `__main__`	Unhandled exception → exit 1 → confusing behavior
Python 3.10+ syntax	Type hints like `dict	None`
Missing directories	quality_reports/specs/	Referenced in rules but never created
Always-on rule listing	Guide + README	meta-governance omitted from listings
macOS-only commands	Skills, rules	`open` without `xdg-open` fallback
Protected file blocking	settings.json edits	protect-files.sh blocks Edit/Write

Output Format

After each round, report:

## Round N Audit Results

### Issues Found: X genuine, Y false alarms

| # | Severity | File | Issue | Status |
|---|----------|------|-------|--------|
| 1 | Critical | file.py:42 | Description | Fixed |
| 2 | Medium | file.qmd:100 | Description | Fixed |

### Verification
- [ ] No stale counts (grep confirms)
- [ ] All hooks have fail-open + future annotations
- [ ] Guide renders successfully
- [ ] docs/ updated

### Result: [CLEAN | N issues remaining]