audit

Audit

Lens-based auditing. Pick the lens matching the concern:

========================================

Security lens — security audit

Scan the codebase for security vulnerabilities, present findings by severity, and generate phased remediation plans with branch/build/PR workflow.

Persona: Application security engineer — thorough, methodical, and pragmatic. Prioritize exploitable vulnerabilities over theoretical risks. Never print secret values.

Arguments

Parse $ARGUMENTS at invocation:

• --auto: Fully non-interactive. Implies --output github. Scans, creates issues, returns summary. See orchestration guide Section 10.
• --output github: Write findings and remediation plans as GitHub Issues. See output guide (~/.claude/skills/_shared/output-guide.md).
• --output session: Present findings in chat only, no persistence.
• Remaining text is the focus area (e.g., auth, api/, dependencies). If provided, scope the scan to that area.

When NOT to use

• For general code quality/tech debt → use /tech-debt
• For frontend performance → use /frontend-performance-audit
• For production outages → use /investigate-app

Procedure

Follow these steps exactly in order.

Enter Plan Mode. Call EnterPlanMode to enter deliberation mode. All discovery, analysis, and proposal steps are read-only — plan mode enforces this by disabling write tools. If the user declines plan mode, proceed normally — the deliberation steps are still read-only by convention.

---

Phase 1: Scan

Scan the codebase across 8 categories (A-H). Follow scan-categories.md for the full checklist of each category's checks, tools, and grep patterns.

Present findings using the severity system and table format defined in severity-definitions.md.

---

User Gate

Present the findings table and ask:

"Here are the security findings. Would you like me to generate remediation plans? I'll group related fixes into PRs."

Do NOT proceed to Phase 2 without explicit confirmation.

Exit Plan Mode. Call ExitPlanMode to transition to execution mode. The deliberation phase is complete — doc generation requires the Write tool.

---

Phase 2: Remediation Plans

Output location:

documentation/planning/security/<session_name>_<YYYY-MM-DD>/
├── 00_SECURITY_AUDIT.md
├── 01_<remediation-slug>.md
├── 02_<remediation-slug>.md
└── ...

Archive convention: See orchestration guide, Section 8.

Ask the user for a short session name, or derive one (e.g., api-security, full-audit).

00_SECURITY_AUDIT.md

Master audit document containing:

• Audit date and scope
• Full findings table with severity, category, location
• Remediation priority order (CRITICAL first, then HIGH, etc.)
• Grouping rationale (which findings are addressed together)
• Dependency matrix (which remediations must complete before others)

Remediation Docs (01_, 02_, etc.)

Group related findings into single PRs where sensible. For example:

• All hardcoded secrets → one "secrets rotation" PR
• All SQL injection fixes → one "parameterized queries" PR
• All dependency updates → one "dependency update" PR

Each doc represents exactly 1 PR and must include:

1. Header — PR title, severity of findings addressed, effort, files modified
2. Findings Addressed — list of finding numbers from the audit table
3. Dependencies — which phases must complete first
4. Detailed Implementation Plan
   • Explicit code references: file paths, line numbers, function names
   • Before/after code examples showing exact changes
   • Step-by-step instructions leaving zero ambiguity
5. Verification Checklist
   • How to verify each finding is actually fixed
   • Tests to run
   • Manual checks
6. "What NOT To Do" Section — common mistakes when fixing this class of vulnerability

Subagent Workflow

Follow Section 9 of the orchestration guide (~/.claude/skills/_shared/orchestration-guide.md). Scratch directory: /tmp/security-audit-<YYYY-MM-DD_HHMMSS>/research/. Plan agents read research from this directory.

Security-specific rule: All subagents MUST mask secret values in research files and docs. Show API_KEY=sk-**** — never the full value.

---

Phase 3: Summary & Handoff

After generating all remediation docs, present a final summary:

Security Audit Summary
═══════════════════════════════════════════════════════════════════════════
  Session:          [name]
  Date:             [date]
  Scope:            [what was audited]

  Findings:         [total] ([critical] critical, [high] high, [medium] medium, [low] low)

  Remediation Plans:
    01  [title]    [CRITICAL]   [effort]
    02  [title]    [HIGH]       [effort]
    03  [title]    [MEDIUM]     [effort]

  Ongoing Recommendations:
    - Add `npm audit` to CI pipeline
    - Set up Dependabot / Renovate for automated dependency updates
    - Add pre-commit hook for secret scanning (e.g., gitleaks, detect-secrets)
    - Schedule quarterly security audits
    - Consider SAST tooling (Semgrep, CodeQL) for continuous scanning

  Audit docs: documentation/planning/security/<session>/
═══════════════════════════════════════════════════════════════════════════

Then tell the user:

"Plans are ready. Run /implement-plan documentation/planning/security/<session>/ to start building — it will handle challenge review, branching, implementation, and PRs for each phase doc."

This skill produces plans, not code. Implementation is always handled by /implement-plan, which provides its own challenge round, verification, and PR workflow. Do NOT build, branch, or create PRs from this skill.

---

Notes

• Never print secret values. Show file:line and the variable name, but mask the actual value.
• Severity is explicit. Use the definitions in severity-definitions.md — don't inflate or deflate.
• Group related fixes. One finding per PR creates review fatigue. Group logically.
• Skip missing tools gracefully. If pip-audit isn't installed, note it and move on. Don't block the audit.
• User gates at every phase transition. Scan → confirm → plan.
• Subagent strategy. Phase 1 can use Explore agents for deep code analysis (disk-write pattern). Phase 2 uses Plan agents for remediation docs (disk-write pattern). Both patterns defined in ~/.claude/skills/_shared/orchestration-guide.md. Context never flows through the orchestrator.
• See orchestration guide, Section 10 for shared reminders (one PR per doc, testing, plans-not-code).

---

Output Targets

This skill supports --output github and --output session in addition to the default docs target.

Follow the output guide at ~/.claude/skills/_shared/output-guide.md:

• For github: use the structured issue body format (Section 4), check for duplicates (Section 4.5), apply labels (Section 4.3). Map scan severities: CRITICAL → priority:critical, HIGH → priority:high, MEDIUM → priority:medium, LOW → priority:low.
• For session: present findings in chat, stay in Plan Mode (Section 5)
• For docs (default): follow the subagent workflow in the orchestration guide

After creating issues, present the batch summary and return issue URLs for audit tracking.

---

Autonomous Mode (--auto)

When --auto is set (see orchestration guide Section 10):

1. Skip Plan Mode — go straight to Phase 1 scan
2. Skip the user confirmation gate between Phase 1 and Phase 2
3. Use focus area from $ARGUMENTS as scope. If none provided, scan full codebase.
4. Create GitHub Issues for all findings (CRITICAL and HIGH immediately, MEDIUM batched)
5. Skip LOW/INFO findings unless particularly noteworthy
6. Return structured summary for audit tracking
7. Security-specific: Never include actual secret values in issue bodies. Mask as sk-****.

========================================

Tech debt lens — find and plan remediation

Find, report, and plan remediation of technical debt in the current codebase.

Arguments

Parse $ARGUMENTS at invocation:

• --auto: Fully non-interactive. Implies --output github. Scans, creates issues, returns summary. See orchestration guide Section 10.
• --output github: Write findings and plans as GitHub Issues. See output guide (~/.claude/skills/_shared/output-guide.md).
• --output session: Present findings in chat only, no persistence.
• Remaining text is the focus area (e.g., src/api/ or auth module). If provided, scope the scan to that area instead of the full codebase.

When NOT to use

• For security-specific vulnerabilities → use /security-audit
• For frontend performance issues → use /frontend-performance-audit
• For product feature gaps → use /product-enhance

Enter Plan Mode. Call EnterPlanMode to enter deliberation mode. All discovery, analysis, and proposal steps are read-only — plan mode enforces this by disabling write tools. If the user declines plan mode, proceed normally — the deliberation steps are still read-only by convention.

Phase 1: Scan & Report

Scan the codebase for common technical debt patterns:

Do NOT read CLAUDE.md or MEMORY.md directly — Claude already has both in its system prompt. Use the system prompt context for project understanding; focus scan effort on code patterns and structure.

1. Duplicated Code

Detect the project language from the codebase (look at file extensions, package.json, requirements.txt, Cargo.toml, go.mod, etc.). Use the Glob tool with appropriate patterns (e.g., **/*.py, **/*.ts, **/*.go).

Look for:

• Copy-pasted functions
• Similar logic in multiple places
• Repeated patterns that could be abstracted

2. TODO/FIXME Comments

Use the Grep tool with pattern TODO|FIXME|HACK|XXX, glob *.{py,js,ts}, output_mode: content, and head_limit: 30.

3. Large Files

Use the Glob tool with the detected language patterns to find source files, then run wc -l on the results to identify large files.

Files over 300 lines may need splitting.

4. Complex Functions

Look for functions with:

• Deep nesting (>3 levels)
• Many parameters (>5)
• Multiple responsibilities

5. Missing Tests

Compare source files to test files - flag untested modules.

6. Outdated Dependencies

Detect the package manager and run the appropriate command:

• Python: pip list --outdated
• Node: npm outdated or check package.json
• Rust: cargo outdated (if installed)
• Go: check go.mod for old versions

Skip gracefully if the tool isn't installed.

7. Dead Code

• Unused imports
• Unreachable code paths
• Commented-out code blocks

Scan Output

Provide a prioritized list:

1. High Priority - Bugs waiting to happen, security issues
2. Medium Priority - Maintainability concerns, duplication
3. Low Priority - Style issues, minor improvements

For each item, suggest a specific fix.

---

Phase 2: Generate Remediation Plans

After presenting the scan results, ask the user to confirm whether they want to generate the full tech debt documentation and phased remediation plans. Do NOT proceed without explicit confirmation.

Ask: "Would you like me to generate detailed tech debt documentation and phased remediation plans?"

Exit Plan Mode. Call ExitPlanMode to transition to execution mode. The deliberation phase is complete — doc generation requires the Write tool.

If yes, ask the user for a short session name (e.g., api-cleanup, db-layer) or derive one from the focus area. All output goes into:

documentation/planning/tech_debt/<session_name>_<YYYY-MM-DD>/
├── 00_TECH_DEBT.md
├── 01_<remediation-slug>.md
├── 02_<remediation-slug>.md
└── ...

Archive convention: See orchestration guide, Section 8.

If the user confirms, generate the following:

A. Master Tech Debt Document

Create 00_TECH_DEBT.md in the session directory containing:

• Complete inventory of all findings from Phase 1
• Severity scoring (blast radius, complexity, risk)
• Prioritized remediation order
• Dependency matrix showing which work blocks other work

B. Phased Enhancement Plans

Create individual plan documents prefixed by execution order: 01-*.md, 02-*.md, etc.

Each plan document represents exactly 1 PR and must include:

1. PR title, risk level, estimated effort, files modified
2. Dependencies (which phases must be completed first) and blocks (which phases this unlocks)
3. Explicit code references - file paths, line numbers, function names, class names
4. Before/after code examples showing exact changes to make
5. Step-by-step implementation instructions leaving zero ambiguity
6. Verification checklist (tests to run, commands to execute, things to manually check)
7. "What NOT To Do" section - common pitfalls and anti-patterns to avoid

C. Subagent Workflow

Follow Section 9 of the orchestration guide (~/.claude/skills/_shared/orchestration-guide.md). Scratch directory: /tmp/tech-debt-<YYYY-MM-DD_HHMMSS>/research/. Plan agents read research from this directory.

---

Output Targets

This skill supports --output github and --output session in addition to the default docs target.

Follow the output guide at ~/.claude/skills/_shared/output-guide.md:

• For github: use the structured issue body format (Section 4), check for duplicates (Section 4.5), apply labels (Section 4.3). Map scan priorities: High → priority:high, Medium → priority:medium, Low → priority:low.
• For session: present findings in chat, stay in Plan Mode (Section 5)
• For docs (default): follow the subagent workflow in the orchestration guide

After creating issues, present the batch summary and return issue URLs for audit tracking.

---

Autonomous Mode (--auto)

When --auto is set (see orchestration guide Section 10):

1. Skip Plan Mode — go straight to Phase 1 scan
2. Skip the user confirmation gate between Phase 1 and Phase 2
3. Implies --output github
4. Use focus area from $ARGUMENTS as scope. If none provided, scan full codebase but limit to top 10 findings.
5. Create GitHub Issues per the output guide (--output github) for all findings above LOW severity
6. Return structured summary for audit tracking

========================================

Repo health lens — overall codebase health view

Birds-eye view across multiple repositories. Scan for open PRs, CI status, stale branches, pending plan docs, and uncommitted work — then present a single dashboard.

Reference: health-checks.md — detailed check definitions, commands, and example output formats.

Procedure

Follow these steps exactly in order.

---

Step 1: Discover Repos

Ask the user how to find repos:

1. "Scan a parent directory?" — provide a path (e.g., ~/Projects). Use Glob with */.git to find repos one level deep.
2. "Specific repos?" — provide a list of paths.
3. "Use saved list?" — check ~/.claude/notes/repo-health-repos.txt for a previously saved list.

Present discovered repos and ask the user to confirm. Offer to save the list for next time.

If using a saved list, validate each path exists and contains .git/. Report dead entries and ask: "Remove the dead entries from your saved list?"

---

Step 2: Scan Each Repo

Launch one Explore subagent per repo for parallel scanning. Gather per-repo data points (see health-checks.md for commands):

Current branch, working tree status, open PRs (mine), PRs to review, CI status, stale branches (14+ days), in-progress plans, pending plans, last commit, stash count.

---

Step 3: Present the Dashboard

Show a compact summary table — one line per repo with branch, tree status, PR count, review count, CI status. Include a totals row. Then expand with a Needs Attention section for repos with issues. See health-checks.md for detail format and examples.

---

Step 4: Recommend Priorities

Suggest a priority order: CI failures > PRs needing your review > PRs with changes requested > uncommitted changes > in-progress plans > stale branches.

Present as a short numbered list with specific actions. Ask: "Which repo do you want to start with?"

---

Step 5: Hygiene Check

After the main dashboard, run a quick hygiene scan. Skip entirely if everything is clean. Check three areas (see health-checks.md for criteria and output formats):

• Stale planning sessions — abandoned or never-started sessions in documentation/planning/. Offer to archive, delete, or skip each.
• Backup retention — old claudefather backups in ~/.local/share/claudefather/backups/. Offer to prune backups older than 30 days.
• Orphaned context-resume files — dirs in ~/.claude/notes/projects/ whose repos no longer exist. Offer to remove.

---

Step 6: Handoff

Once the user picks a repo, suggest the relevant skill (/context-resume, /review-pr, /implement-plan). If it's a different directory, tell the user to switch there first.

---

Notes

• Speed matters. Triage tool, not a deep audit. Scan fast, present concisely.
• Subagent parallelism. Launch one Explore subagent per repo for speed.
• Saved repo list. ~/.claude/notes/repo-health-repos.txt — one path per line, never synced.
• CI is best-effort. Skip gracefully if gh is unavailable; note "no CI data."
• Mostly read-only. Steps 1–4 and 6 don't modify anything. Step 5 modifies only with explicit user confirmation.
• Stale branch threshold. 14 days, configurable if the user asks.
• GitHub CLI dependency. PR/CI data requires gh and an authenticated session.

========================================

Docs lens — doc staleness audit

Rigorously audit project documentation against the actual codebase. Update inaccuracies, mark development plan statuses, archive stale docs, and identify gaps — ensuring full handoff-readiness.

Framing principle: This project is being handed off to another engineering team. There must be zero gaps. Any engineer who picks up the codebase should be able to fully understand it, have complete context, and confidently edit and enhance the codebase without asking the original team a single question.

Arguments

Parse $ARGUMENTS at invocation:

• --auto: Fully non-interactive. Auto-fixes stale docs, creates GitHub Issues for gaps (implies --output github). See orchestration guide Section 10.
• --output github: Create GitHub Issues for documentation gaps. See output guide (~/.claude/skills/_shared/output-guide.md).
• --output session: Present findings in chat only, no persistence.
• Remaining text is the scope path (e.g., docs/, documentation/). If provided, skip asking in Step 1.

When NOT to use

• For code quality/tech debt → use /tech-debt
• For security vulnerabilities → use /security-audit
• For writing new docs from scratch → just ask Claude directly

Procedure

Follow these steps exactly in order.

Step 1: Scope Selection

Ask the user:

1. "Review a specific folder?" → user provides a path (e.g., ./documentation, ./docs)
2. "Global review?" → scan the entire project for documentation files

If the user chooses a global review, search for:

• All *.md files in the repo
• Common doc directories: docs/, documentation/, doc/

Automatically detect and exclude archive/legacy folders from the active review set:

• archive/, legacy/, .archive/, old/, deprecated/
• Note their existence to the user but do not include them in the active audit

Step 2: Discovery & Inventory

Find all documentation files within scope. Categorize each doc:

Category	Description
Coding overview	Describes architecture, systems, code structure, APIs
Development plan	Describes phases of work, roadmaps, feature plans
Guide/runbook	How-to, setup, operational procedures
Reference	API docs, config references, schemas, changelogs
Other	Anything that doesn't fit above

Present the inventory as a table:

Documentation Inventory
═══════════════════════════════════════════════════════
  File                        Category           Modified
  docs/architecture.md        Coding overview    2025-01-15
  docs/roadmap.md             Development plan   2025-02-01
  README.md                   Guide/runbook      2025-02-10
  CHANGELOG.md                Reference          2025-02-10
═══════════════════════════════════════════════════════
  4 files found (1 overview, 1 plan, 1 guide, 1 reference)

Ask the user to confirm the inventory and categories before proceeding. The user may exclude files or recategorize.

Step 3: Coding Overview Audit

For each document categorized as Coding overview:

1. Read the document thoroughly
2. Use subagents (Task tool with Explore type) to trace every claim back to real code:
   • File path references → verify files exist at stated paths
   • Function/class mentions → verify they exist and match descriptions
   • Architecture claims → verify the described patterns in the actual code
   • Integration descriptions → verify connections between systems
   • Config references → verify config files and their current values
3. Update statements to be true — fix inaccuracies, wrong file paths, renamed functions, changed APIs
4. Remove things no longer valid — deleted features, removed integrations, dead code references
5. Add detail where missing — new modules not yet documented, undocumented config, implicit patterns. Think: "What would confuse a senior engineer on day 1?"
6. After edits, show a summary of what changed and why

Important: Only modify documentation files. Never touch code files.

Step 4: Development Plan Audit

For each document categorized as Development plan:

1. Read the plan and its phases/sections
2. Use subagents to cross-reference each item against the codebase
3. Mark each section/phase with a status:

Status	Meaning
✅ COMPLETED	Code exists, feature is implemented
🔧 IN PROGRESS	Partial implementation exists
📋 PENDING	No implementation found

4. Update the doc in place with status markers
5. If the entire document is fully completed or no longer valid (superseded, abandoned):
   • Ask the user for confirmation
   • Move it using git mv so the rename is tracked in history (ask user for preferred location, default to archive/ in the doc's parent directory)
   • Create the archive directory first with mkdir -p if it doesn't exist
   • Note the move in the summary

Step 5: Gap Analysis

After reviewing all docs, identify:

• Undocumented systems — code modules, services, or significant logic with no corresponding documentation
• Missing setup/onboarding steps — things a new engineer would need to know to get started
• Stale cross-references — docs linking to other docs that have moved, been archived, or deleted
• Missing context — decisions, trade-offs, or "why" explanations that aren't captured anywhere

Present findings as a list and ask the user which gaps to address:

• Create new documentation
• Extend existing documentation
• Skip (note for later)

Execute the user's choices — create or update docs as requested.

Step 6: Summary Report

Print a final report:

Documentation Review Complete
═══════════════════════════════════════════════════════
Files reviewed:    N total
  Coding overview: N (N updated)
  Development plan: N (N updated, N archived)
  Guide/runbook:   N (N updated)
  Reference:       N
  Other:           N

Changes made:
  - docs/architecture.md: Fixed 3 file paths, added new API section
  - docs/roadmap.md: Marked Phase 1 ✅, Phase 2 🔧, Phase 3 📋
  - docs/old-plan.md: Archived → archive/old-plan.md (fully completed)

Gaps identified:
  - No documentation for the auth middleware module
  - Missing onboarding guide for local development setup
  - 2 broken cross-references fixed

Handoff readiness: [assessment]
Could a new engineer onboard from these docs alone?
═══════════════════════════════════════════════════════

Notes

• Uses subagents heavily for codebase exploration — keeps main context clean while doing deep code tracing.
• Always asks before archiving or creating new files.
• Every edit decision is filtered through: "Would a new engineer understand this?"
• Does NOT touch code files — only documentation.
• Archive folder detection is flexible — looks for existing archive/, legacy/, .archive/, or asks the user.
• If the project has no documentation at all, suggest a minimal doc set: README, architecture overview, and development plan.

---

Output Targets

This skill supports --output github and --output session in addition to the default inline-fix behavior.

Follow the output guide at ~/.claude/skills/_shared/output-guide.md:

• For github: use the structured issue body format (Section 4), check for duplicates (Section 4.5), apply labels (Section 4.3). Apply docs label. Auto-fix verifiable inaccuracies first, then create issues for gaps requiring human judgment.
• For session: present findings in chat, stay in Plan Mode (Section 5)
• Default: fix docs inline and ask about gaps (current behavior)

After creating issues, present the batch summary and return issue URLs for audit tracking.

---

Autonomous Mode (--auto)

When --auto is set (see orchestration guide Section 10):

1. Use scope from $ARGUMENTS or default to global review
2. Skip user confirmation of inventory (Step 2) — proceed with auto-categorization
3. Auto-fix verifiable inaccuracies in coding overviews (wrong file paths, renamed functions) — commit fixes directly
4. Auto-mark development plan statuses
5. Auto-archive fully completed plans
6. Create GitHub Issues for gaps that require human judgment (new docs to write, structural decisions)
7. Return structured summary for audit tracking

========================================

Design lens — visual / UX design audit

Design-literate PM bridging visual polish and engineering. Audit a deployed app, find design/UX gaps, produce phased PR-ready design docs.

Arguments

Parse $ARGUMENTS at invocation:

• If it contains --output github: activate GitHub Issues output mode. See output guide (~/.claude/skills/_shared/output-guide.md).
• If it contains --output session: present findings in chat only, no persistence.
• Remaining text is the deployed URL or focus area. If provided, skip asking in Step 1.

When NOT to use

• For frontend performance (flickering, slow loads, re-renders) → use /frontend-performance-audit
• For code quality/tech debt → use /tech-debt
• For product feature gaps → use /product-enhance

Procedure

Enter Plan Mode (EnterPlanMode). Steps 1-5 are read-only. If declined, proceed by convention.

---

Step 1: Scope & Context Gathering

Ask: (1) deployed URL, (2) focus area, (3) anything to skip, (4) front-end stack. Scratch dir: /tmp/design-review-<YYYY-MM-DD_HHMMSS>/research/.

Parallel: A. Explore subagents (disk-write pattern, orchestration guide Section 2) for front-end structure, styling, state, APIs, tokens, components. B. Begin Step 2.

Present codebase context summary. Confirm with user.

---

Step 2: Visual Audit — Screenshot Capture

Detect Chrome (which google-chrome, which chromium, test -x "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" in parallel). Prefer local dev server -- check package.json for port, lsof if running, curl to verify; fall back to deployed URL.

Capture each page at 1440,900 / 768,1024 / 375,812. One screenshot per Bash call. No shell operators.

Classify pages: MARKETING (hero-driven), APP UI (data-dense), HYBRID (per-section rules). See design-hard-rules.md.

DOM Extraction (optional, claude-in-chrome MCP -- skip if unavailable):

Fonts: JSON.stringify([...new Set([...document.querySelectorAll('*')].slice(0,500).map(e => getComputedStyle(e).fontFamily))])

Colors: JSON.stringify([...new Set([...document.querySelectorAll('*')].slice(0,500).flatMap(e => [getComputedStyle(e).color, getComputedStyle(e).backgroundColor]).filter(c => c !== 'rgba(0, 0, 0, 0)'))])

Headings: JSON.stringify([...document.querySelectorAll('h1,h2,h3,h4,h5,h6')].map(h => ({tag:h.tagName, text:h.textContent.trim().slice(0,50), size:getComputedStyle(h).fontSize, weight:getComputedStyle(h).fontWeight})))

Touch targets: JSON.stringify([...document.querySelectorAll('a,button,input,[role=button]')].filter(e => {const r=e.getBoundingClientRect(); return r.width>0 && (r.width<44||r.height<44)}).map(e => ({tag:e.tagName, text:(e.textContent||'').trim().slice(0,30), w:Math.round(e.getBoundingClientRect().width), h:Math.round(e.getBoundingClientRect().height)})).slice(0,20))

Ask: "Here's what I see. Anything I should look at more closely?"

---

Step 3: Design Intent Interview

Ask these one group at a time, waiting for answers:

• Brand & Identity — desired feeling, brand guides/Figma, target users
• Pain Points — visual annoyances, user complaints, pages that feel "off"
• Aspirations — admired apps, snap-fix wish, desired patterns

---

Step 4: Design Gap Analysis

Compare intent (Step 3) vs. observations (Step 2) vs. code (Step 1). Explore subagents for targeted digs.

Subagents read from this directory: audit-checklist.md, ai-slop-blacklist.md, font-knowledge.md, design-hard-rules.md. Calibrate by page-type. Present gap analysis with dual scores (Design + AI Slop), referencing screenshots and code.

Ask: "Does this match your experience? Anything I missed or got wrong?"

---

Step 5: Enhancement Proposals

Propose enhancements scored on Impact, Effort, Risk. Classify as SAFE (baseline fix users expect) or RISK (differentiation -- explain upside and downside). SAFE first, ranked by impact-to-effort. Reference screenshots, Step 3 intent, code.

Ask: "Which would you like me to design? Pick by number or adjust." Wait for selection. Call ExitPlanMode.

---

Step 6: Generate Phased Design Docs

Output to documentation/planning/phases/<session_name>_<YYYY-MM-DD>/. Overview + numbered docs (1 PR each). Orchestration guide Section 9.

Phase docs include: header, context + screenshots, visual spec (exact before/after), dependencies, implementation plan, responsive behavior, accessibility checklist, test plan, verification, "What NOT To Do."

Tell user: "Run /implement-plan on the phase directory to start building." This skill produces plans, not code.

---

Notes

• User gates at every step -- never auto-proceed.
• Screenshots are evidence -- every observation references one.
• Subagents: Steps 1/4 Explore, Step 6 Plan. Disk-write pattern per orchestration guide.
• Critique format: "I notice..." / "I wonder..." / "What if..." / "I think... because..."
• Respect existing design system. Accessibility non-negotiable. Orchestration guide Section 10.

---

Output Targets

This skill supports --output github and --output session in addition to the default docs target.

Follow the output guide at ~/.claude/skills/_shared/output-guide.md:

• For github: use the structured issue body format (Section 4), check for duplicates (Section 4.5), apply labels (Section 4.3). Apply design label. Include SAFE vs RISK classification in issue body.
• For session: present findings in chat, stay in Plan Mode (Section 5)
• For docs (default): follow the subagent workflow in the orchestration guide

After creating issues, present the batch summary and return issue URLs for audit tracking.

========================================

Access path lens — API/CLI/SDK/Slack interface consistency

Audit whether a system's access paths consistently enforce cross-cutting concerns — and whether those concerns are placed at the correct architectural layer (transport vs. domain core).

Persona: Senior platform architect who evaluates systems holistically. Evidence-driven — every finding cites specific code paths. Distinguishes between genuine inconsistencies and appropriate per-transport differences.

Arguments

Parse $ARGUMENTS at invocation:

• --auto: Fully non-interactive. Implies --output github. Scans, creates issues, returns summary. See orchestration guide Section 10.
• --output github: Write findings and remediation plans as GitHub Issues. See output guide (~/.claude/skills/_shared/output-guide.md).
• --output session: Present findings in chat only, no persistence.
• Remaining text is the focus area (e.g., auth, validation, api/). If provided, scope the audit to that area.

When NOT to use

• For security vulnerabilities (injection, secrets, OWASP) → use /security-audit
• For general code quality / tech debt → use /tech-debt
• For production outages or broken behavior → use /investigate-app
• For frontend performance → use /frontend-performance-audit

The Key Insight

Not every difference across access paths is a bug. A CLI having no auth is correct — it's a local operator tool. The real questions are:

1. Shared invariants: Which concerns MUST hold regardless of access path? (e.g., input validation, SQL injection prevention)
2. Concern placement: Is each concern enforced at the right layer? Transport-specific concerns (auth, rate limiting) belong at the edge. Universal concerns (validation, error sanitization) belong in the domain core.
3. Genuine gaps: Where does one path enforce something that another path should but doesn't?

Quick Reference

Phase	Steps	What happens	User gate?
1: Scan	Steps 1–5	Detect paths, parallel discovery, convergence analysis, classify findings, present summary	No
Gate	—	User confirms whether to generate remediation plans	Yes
2: Remediation	—	Generate per-PR planning docs grouped by related findings	No
3: Summary	—	Present final summary, hand off to /implement-plan	No

Procedure

Follow these steps exactly in order.

Enter Plan Mode. Call EnterPlanMode to enter deliberation mode. All discovery, analysis, and proposal steps are read-only — plan mode enforces this by disabling write tools. If the user declines plan mode, proceed normally — the deliberation steps are still read-only by convention.

Do NOT read CLAUDE.md or MEMORY.md — already in system prompt.

---

Phase 1: Scan

Step 1: Scope & Stack Detection

If no focus area was provided in $ARGUMENTS, ask: "Any specific concern or access path to focus on?" Default to full system scan if no scope given.

Detect the system's framework and access patterns. Run in parallel:

• Glob **/routes/**/*.py, **/api/**/*.py, **/controllers/**/*.{ts,js,py,rb,go} (HTTP frameworks)
• Grep @app\.(get|post|put|delete|patch)|@router\.|@Controller|@RequestMapping|app\.(get|post|use)\( in source files
• Grep click\.command|typer\.command|argparse|Commander|cobra\.Command (CLI frameworks)
• Grep slack_bolt|slack_sdk|SlackBot|Bolt\( (Slack integrations)
• Grep FastMCP|McpServer|mcp\.tool|@mcp_tool (MCP servers)
• Grep celery|dramatiq|huey|rq\.job|@task|BackgroundTasks (background workers)
• Grep WebSocket|socket\.io|ws\.on (WebSocket handlers)
• Grep GraphQL|@Query|@Mutation|type Query (GraphQL endpoints)

If fewer than 2 access paths found, tell the user: "This system appears to have a single access path — this audit is most valuable for systems with 2+ interfaces to the same core logic."

Step 2: Parallel Discovery

Scratch directory: /tmp/access-path-audit-<YYYY-MM-DD_HHMMSS>/research/

Launch two general-purpose subagents in parallel (Agent tool, subagent_type: "general-purpose"). Each writes findings to scratch dir, returns 2-4 line summary. Orchestrator does NOT read full research files.

• Subagent A: Access Path Inventory — every access path, transport, entry point, auth, domain services called. Writes to research/path-inventory.md.
• Subagent B: Cross-Cutting Concern Mapping — for each concern in scan-categories.md, maps enforcement across every access path. Writes to research/concern-mapping.md.

Full subagent prompts and research file formats: See subagent-prompts.md in this skill directory.

Step 3: Convergence — Concern Placement Analysis

Launch a third general-purpose subagent that reads both research files and builds the concern placement map. This is the core analytical step.

The convergence subagent must:

1. Classify each concern as transport-appropriate or domain-core:

   • Transport-layer concerns (correctly vary per path): authentication, rate limiting, request/response serialization, protocol-specific headers, connection management
   • Domain-core concerns (must be consistent): input validation, business rule enforcement, error sanitization, audit logging of domain events, authorization (beyond "is authenticated")
   • Hybrid concerns (enforced at both layers): some validation at transport for fast-fail, authoritative validation in domain

2. Trace a representative operation (e.g., "search", "query") through each access path, noting exactly where each concern is applied

3. Build the consistency matrix: for each domain-core concern, is it enforced in the domain layer (shared) or only in some transport adapters (inconsistent)?

4. Identify shared code vs. duplicated logic: which cross-cutting implementations are shared (good) vs. copy-pasted across paths (maintenance risk)?

Writes to research/convergence.md. Returns 2-4 line summary.

Full convergence subagent prompt: See subagent-prompts.md.

Step 4: Findings Classification

Using the convergence summary, classify findings into four categories:

Category A: Genuine Gaps — domain concern missing from a path. Fix: push concern into domain core.

Category B: Misplaced Concerns — right concern, wrong layer. Fix: move to correct layer.

Category C: Appropriate Differences — paths correctly differ (transport-specific). Not a bug — list to show thoroughness.

Category D: Duplication Risk — shared logic copy-pasted. Fix: extract to shared module.

Severity for categories A and B:

Severity	Definition
CRITICAL	Exploitable security gap or data integrity risk across paths
HIGH	Inconsistency that causes incorrect behavior under normal use
MEDIUM	Inconsistency that causes issues under edge cases or load
LOW	Maintenance risk or minor inconsistency with no immediate impact

Category C findings are not bugs — list them to show the audit was thorough. Category D findings are always MEDIUM or LOW.

Step 5: Present Findings Summary

Present to the user:

1. Architecture summary — how many paths, what pattern, overall health
2. Concern placement map — table showing where each concern is enforced per path (use the legend: MW = middleware, Route! = route-only should be domain, None! = missing gap, None* = correctly absent, Leaks! = present but broken)
3. Ranked findings table — all findings sorted by severity with category, concern, and one-line summary
4. Architectural recommendation — one paragraph on highest-leverage structural change

---

User Gate

Present the findings and ask:

"Here are the access path audit findings. Would you like me to generate remediation plans? I'll group related fixes into PRs."

Do NOT proceed to Phase 2 without explicit confirmation.

Exit Plan Mode. Call ExitPlanMode to transition to execution mode. The deliberation phase is complete — doc generation requires the Write tool.

---

Phase 2: Remediation Plans

Output location:

documentation/planning/access-paths/<session_name>_<YYYY-MM-DD>/
├── 00_ACCESS_PATH_AUDIT.md
├── 01_<remediation-slug>.md
├── 02_<remediation-slug>.md
└── ...

Archive convention: See orchestration guide, Section 8.

Ask the user for a short session name, or derive one (e.g., domain-boundary, full-audit).

00_ACCESS_PATH_AUDIT.md

Master audit document containing:

• Audit date and scope
• System architecture summary (paths, pattern, domain core)
• Concern placement map (the full table)
• Full findings table with severity, category, concern, location
• Remediation priority order (CRITICAL first, then HIGH, etc.)
• Grouping rationale (which findings are addressed together)
• Operation traces (the traced operations showing where concerns apply per path)
• Category C listing (appropriate differences — proves audit thoroughness)

Remediation Docs (01_, 02_, etc.)

Group related findings into single PRs where sensible. For example:

• All validation extraction → one "domain validation" PR
• All search deduplication → one "search service extraction" PR
• All error sanitization → one "error handling" PR

Each doc represents exactly 1 PR and must include:

1. Header — PR title, severity of findings addressed, effort, files modified
2. Findings Addressed — list of finding numbers from the audit table
3. Dependencies — which phases must complete first
4. Detailed Implementation Plan
   • Explicit code references: file paths, line numbers, function names
   • Before/after code examples showing exact changes
   • Step-by-step instructions leaving zero ambiguity
5. Verification Checklist
   • How to verify each finding is actually fixed
   • Tests to run
   • Manual checks
6. "What NOT To Do" Section — common mistakes when fixing this class of issue

Subagent Workflow

Follow Section 9 of the orchestration guide (~/.claude/skills/_shared/orchestration-guide.md). Scratch directory: /tmp/access-path-audit-<YYYY-MM-DD_HHMMSS>/research/. Plan agents read research from this directory.

---

Output Targets

This skill supports --output github and --output session in addition to the default docs target.

Follow the output guide at ~/.claude/skills/_shared/output-guide.md:

• For github: use the structured issue body format (Section 4), check for duplicates (Section 4.5), apply labels (Section 4.3). Map Category A/B → priority:critical/priority:high, Category C → priority:medium, Category D → priority:low.
• For session: present findings in chat, stay in Plan Mode (Section 5)
• For docs (default): follow the subagent workflow in the orchestration guide

After creating issues, present the batch summary and return issue URLs for audit tracking.

---

Phase 3: Summary & Handoff

After generating all remediation docs, present a final summary:

Access Path Audit Summary
═══════════════════════════════════════════════════════════════════════════
  Session:          [name]
  Date:             [date]
  Scope:            [what was audited]

  Architecture:     [pattern] with [N] access paths
  Domain Core:      [key shared modules]

  Findings:         [total] ([critical] critical, [high] high, [medium] medium, [low] low)
  Appropriate Diffs: [count] (not bugs — transport-specific)

  Remediation Plans:
    01  [title]    [CRITICAL]   [effort]
    02  [title]    [HIGH]       [effort]
    03  [title]    [MEDIUM]     [effort]

  Ongoing Recommendations:
    - Schedule periodic re-audit when new access paths are added
    - New access paths should go through domain core, not duplicate transport logic
    - Domain-core concerns should raise domain exceptions, not HTTP exceptions

  Audit docs: documentation/planning/access-paths/<session>/
═══════════════════════════════════════════════════════════════════════════

Then tell the user:

"Plans are ready. Run /implement-plan documentation/planning/access-paths/<session>/ to start building — it will handle challenge review, branching, implementation, and PRs for each phase doc."

This skill produces plans, not code. Implementation is always handled by /implement-plan, which provides its own challenge round, verification, and PR workflow. Do NOT build, branch, or create PRs from this skill.

---

Common Mistakes

Mistake	Fix
Treating every cross-path difference as a bug	Use Category C — transport-specific differences (CLI has no auth, HTTP has CORS) are correct. List them to prove thoroughness.
Tracing only middleware stacks	Trace at function-call depth — entry point → middleware → domain service → data layer. Middleware-only traces miss gaps in business logic.
Missing mounted sub-apps in dual mode	Sub-apps (e.g., MCP on FastAPI) inherit parent middleware in HTTP mode but NOT in stdio/standalone. Always check both deployment modes.
Missing LLM-mediated paths	Slack → ChatService → LLM → ToolExecutor is an indirect access path. Trace concerns through the full chain including the dispatch layer, not just the outer entry point.
Shallow "access path" definition	Any code path that can invoke domain logic with different cross-cutting behavior counts. Internal dispatch layers (tool executors, job runners) count if they have their own validation/error handling distinct from their caller.
Claiming definitive findings for graceful degradation	Scan category I is best audited through code review of error handling and timeout configs. Flag areas of concern for follow-up runtime testing rather than making definitive claims from static analysis alone.
Including secrets in findings	Never include connection strings or credentials verbatim — file:line references only.

Notes

• Subagent pattern. Disk-write pattern per ~/.claude/skills/_shared/orchestration-guide.md Sections 2 & 6. Three subagents in Phase 1 (two parallel, one sequential). Phase 2 uses Plan agents per Section 9. Orchestrator coordinates only.
• Pass focus area from Step 1 into both Step 2 subagent prompts.
• Technology-agnostic. The scan categories cover common patterns across Python, Node.js, Go, Ruby, and Java. The subagent prompts adapt to whatever stack is detected.
• User gates at every phase transition. Scan → confirm → plan. Do not generate remediation docs without user confirmation.
• See orchestration guide, Section 11 for shared reminders (one PR per doc, testing, plans-not-code).

---

Autonomous Mode (--auto)

When --auto is set (see orchestration guide Section 10):

1. Skip Plan Mode — go straight to Phase 1 scan
2. Skip the user confirmation gate between Phase 1 and Phase 2
3. Use focus area from $ARGUMENTS as scope. If none provided, scan full system.
4. Create GitHub Issues for all Category A and B findings (CRITICAL and HIGH immediately, MEDIUM batched)
5. Skip Category C (appropriate differences) and Category D at LOW severity
6. Return structured summary for audit tracking

========================================

Data model lens — how well schema serves the app

Audit how well a Python/Postgres application's data model serves its codebase — traces code paths to DB interactions, maps intent to schema, finds where the model fights the application.

Persona: Senior data architect who reads code. Evidence-driven — every finding cites specific code paths and schema elements.

Procedure

Follow steps in order. Call EnterPlanMode first — the entire skill is diagnostic (no write phase). If user declines, proceed read-only by convention. Never exit plan mode.

Do NOT read CLAUDE.md or MEMORY.md — already in system prompt.

---

Step 1: Scope & Context

Ask: (1) "What's the pain point?" and (2) "Any specific area to focus on?" Default to full codebase scan if no scope given.

Target System Detection

Verify Python/Postgres/SQLAlchemy codebase. Run in parallel:

• Grep declarative_base|DeclarativeBase|mapped_column in *.py
• Glob **/alembic/versions/*.py
• Grep psycopg|asyncpg|postgresql|postgres in *.{py,toml,cfg,txt,yml,yaml,env*}

If none match, warn the user this skill targets Python/Postgres/SQLAlchemy and offer best-effort or alternative. Proceed on confirmation.

---

Step 2: Parallel Discovery

Scratch directory: /tmp/data-model-audit-<YYYY-MM-DD_HHMMSS>/research/

Launch two general-purpose subagents in parallel (Agent tool, subagent_type: "general-purpose"). Each writes findings to scratch dir, returns 2-4 line summary. Orchestrator does NOT read full research files. (General-purpose because Explore lacks Write tool.)

Subagent A: Schema Discovery

Discovers the complete data model — SQLAlchemy models, Alembic migrations, raw SQL, and discrepancies between them. Writes findings to research/schema-discovery.md.

Subagent B: Code Path Tracing

Traces every code path from entry points (routes, CLI, tasks) through business logic to database interactions. Catalogs data access patterns, query patterns, and N+1 candidates. Writes findings to research/code-path-tracing.md.

Full subagent prompts, instructions, and research file formats: See subagent-prompts.md in this skill directory.

---

Step 3: Convergence — Map Code to Schema

Launch a third general-purpose subagent that reads both research files, verifies against the codebase, and builds a code-to-schema convergence map (unused schema, write-only columns, read-hot tables, god-tables, structural workarounds, missing constraints, N+1 patterns). Writes to research/convergence.md.

Full convergence subagent prompt and checklist: See subagent-prompts.md in this skill directory.

The orchestrator receives the convergence summary (2-4 lines) and presents the code-to-schema map overview to the user for confirmation before proceeding to fit analysis.

---

Step 4: Fit Analysis

Classify and rank findings into six categories: Schema Gaps, Schema Bloat, Structural Friction, Missing Constraints, Performance Anti-patterns, Model Drift. Use convergence summary + any user corrections from Step 3 gate.

Category definitions, severity guidance, examples: See gap-analysis-categories.md.

If convergence summary is insufficient, read specific sections of the research file — never the full file.

---

Step 5: Ranked Findings Report

Print structured report: scope summary, code-to-schema map, ranked findings table, detailed findings with evidence/recommendations, total summary with top recommendation.

Report structure and finding template: See gap-analysis-categories.md.

---

Notes

• Subagent pattern. Disk-write pattern per ~/.claude/skills/_shared/orchestration-guide.md Sections 2 & 6. Three subagents: two parallel (Step 2), one sequential (Step 3). Orchestrator coordinates only.
• Pass focus area from Step 1 into both Step 2 subagent prompts.
• Secrets masking. Never include connection strings verbatim — file:line only.
• User gates. Confirmation required after Step 3 before fit analysis.
• Terminal at report. Diagnostic only — no artifacts. User acts via /implement-plan if desired.
• Orchestration guide: Section 9 N/A (no Plan subagents). Section 10: "Respect existing architecture" applies; doc/testing rules do not.

========================================

Frontend performance lens — symptoms like jank, flicker, load times

Audit frontend rendering performance by tracing render cycles, diagnosing fetch patterns, and producing phased remediation plans for /implement-plan.

Persona: Senior frontend performance engineer — traces render cascades methodically, maps symptoms to root causes before proposing fixes. Pragmatic: fix the bottleneck, not everything.

Arguments

Parse $ARGUMENTS at invocation:

• --auto: Fully non-interactive. Implies --output github. Requires page/flow in arguments. See orchestration guide Section 10.
• --output github: Write findings and remediation plans as GitHub Issues. See output guide (~/.claude/skills/_shared/output-guide.md).
• --output session: Present findings in chat only, no persistence.
• Remaining text is the page or flow to audit. If provided, use it as the scope in Phase 1 instead of asking.

When NOT to use

• For visual/UX design issues → use /design-review
• For backend/API latency → use /investigate-app
• For general code quality → use /tech-debt

Procedure

Follow these steps in order. Enter Plan Mode (EnterPlanMode) before starting — all discovery and analysis is read-only. If the user declines, proceed read-only by convention.

---

Phase 1: Scope & Symptom

Ask the user: (1) what's the symptom, (2) which page or flow, (3) how to reproduce. If vague, ask them to narrow to a specific page. Performance audits need a concrete entry point.

---

Phase 2: Codebase Reconnaissance

Scratch directory: /tmp/frontend-performance-audit-<YYYY-MM-DD_HHMMSS>/research/. All Explore agents write here and return 2-4 line summaries. Follow Explore Agent → Disk Pattern (orchestration guide, Section 2). Do NOT read CLAUDE.md/MEMORY.md in the orchestrator.

Map three areas via parallel Explore agents:

• A. Framework & rendering setup — framework/version, React version, strict mode, providers, middleware
• B. Component tree for the affected route — server/client boundaries, data-fetching hooks, prop sources
• C. Data layer — fetch utilities, caching strategy, SSR vs client-side

Present a brief architecture summary (framework, React version, affected route, component chain, data fetching, Suspense).

---

Phase 3: Scan

Scan the affected components across 8 categories using Explore subagents (one per category). Each agent reads scan-categories.md for detailed checklists, writes findings to the scratch directory, and returns a summary. Focus on the Phase 2 component tree only.

Categories: A. Render Cascades, B. Fetch Patterns, C. Observer & Listener Overhead, D. State Management, E. Memoization Gaps, F. Layout Stability, G. Framework-Specific Issues, H. Bundle & Loading

---

Findings Output

After all scans complete, present a consolidated findings table and render cascade diagram. Templates and severity definitions are in cascade-diagram-template.md (same directory).

---

User Gate

Present findings and cascade diagram. Ask: "Would you like me to generate remediation plans? I'll group related fixes into PRs ordered by impact." Do NOT proceed without confirmation. Exit Plan Mode (ExitPlanMode) after confirmation — doc generation requires the Write tool.

---

Phase 4: Remediation Plans

Ask the user for a short session name (e.g., explain-page-flicker). Output to documentation/planning/performance/<session_name>_<YYYY-MM-DD>/. Archive convention: orchestration guide, Section 8.

00_PERF_AUDIT.md — Master audit: date, scope, symptom, architecture summary, findings table, cascade diagram, priority order, grouping rationale, dependency matrix.

Remediation Docs (01_, 02_, etc.) — Group related findings into single PRs. Each doc = exactly 1 PR containing: header (title, severity, effort, files), findings addressed, dependencies, root cause explanation with cascade chain, detailed implementation plan (file paths, line numbers, before/after code), verification checklist (DevTools + manual repro + build/test), and "What NOT To Do" section.

Subagent workflow: Follow orchestration guide Section 9. Plan agents read research from scratch directory. Quality requirements (beyond Section 4): explain render lifecycle per fix, draw before/after cascades, include DevTools verification.

After generating docs: "Plans are ready for review. Run /implement-plan on the session directory to execute them."

---

Notes

• Symptom first, then trace. Start from the symptom, trace backwards. Focused beats broad.
• The cascade diagram is the deliverable. If you can draw the re-render chain, you've found the bug.
• Severity tracks user impact, not code smell.
• Group fixes by PR, not by category. One PR for the full cascade is better than three PRs touching the same file.
• Don't prescribe caching libraries. Prefer minimal fixes over architectural changes.
• User gates at every phase transition.
• Subagent strategy. Phase 2: Explore (architecture). Phase 3: Explore (per category). Phase 4: Plan (remediation docs). All use disk-write pattern.
• See orchestration guide, Section 10 for shared reminders.

---

Output Targets

This skill supports --output github and --output session in addition to the default docs target.

Follow the output guide at ~/.claude/skills/_shared/output-guide.md:

• For github: use the structured issue body format (Section 4), check for duplicates (Section 4.5), apply labels (Section 4.3). Apply performance label. Map severity levels to priority labels. Group issues by cascade chain where applicable.
• For session: present findings in chat, stay in Plan Mode (Section 5)
• For docs (default): follow the subagent workflow in the orchestration guide

After creating issues, present the batch summary and return issue URLs for audit tracking.

---

Autonomous Mode (--auto)

When --auto is set (see orchestration guide Section 10):

1. Skip Plan Mode — go straight to reconnaissance and scan
2. Page/flow must be provided in $ARGUMENTS (bail if missing — this skill can't auto-detect what to audit)
3. Skip the user confirmation gate between scan and remediation
4. Create GitHub Issues for all findings, grouped by cascade chain
5. Return structured summary for audit tracking

========================================

Cache lens — CLAUDE.md / config cache efficiency

Diagnostic scan of a project's Claude Code configuration for patterns that hurt prompt cache efficiency. Run this occasionally — like /tech-debt or /security-audit — to check your project's cache hygiene.

This is a read-only skill. It reads files and presents findings. It does not modify anything.

Background

Claude Code's prompt caching works by prefix matching: static content at the start of the system prompt is cached and reused across turns. Anything that changes between turns or sessions invalidates the cache from that point forward. The main user-controlled factors are:

1. CLAUDE.md section ordering — static content first, dynamic content last
2. CLAUDE.md size — larger files mean more tokens in every API call
3. Lessons file loading — auto-loading .claude/lessons.md adds variable content to every request
4. Tool set stability — adding/removing tools mid-session invalidates the entire cache
5. Model stability — switching models mid-session rebuilds the cache from scratch
6. Mid-session CLAUDE.md edits — editing CLAUDE.md during a session invalidates the cached prefix

Procedure

Run all six checks, then present the combined findings table. Do not ask questions or pause between checks — run them all and present results.

Checks (see cache-checks.md for detailed guidance and scoring):

1. Section ordering — static sections before dynamic sections in CLAUDE.md
2. CLAUDE.md size — line count thresholds (200 / 350)
3. Lessons isolation — .claude/lessons.md on-demand only, not auto-loaded
4. Tool & model stability — no mid-session tool/model switching patterns
5. Mid-session edits — no instructions to edit CLAUDE.md during a session
6. Rules file configuration — .claude/rules/ files have correct paths: frontmatter

Each check scores PASS / WARN / FAIL per the criteria in cache-checks.md.

Presenting Results

After running all checks, present a single findings table:

Cache Audit Results
═══════════════════════════════════════════════════════════════════════════

  Check                        Status    Notes
  ─────────────────────────    ──────    ─────────────────────────────
  Section ordering             PASS      Static-first layout detected
  CLAUDE.md size               WARN      247 lines (threshold: 200)
  Lessons isolation            PASS      On-demand only
  Tool & model stability       PASS      No mid-session changes
  Mid-session edits            WARN      "Update continuously" language
  Rules file config            PASS      All rules have paths: frontmatter

═══════════════════════════════════════════════════════════════════════════
  6 checks: 4 passed, 2 warnings, 0 failures

Then, for each WARN or FAIL item, provide a brief recommendation explaining the caching impact and a concrete suggestion.

Tone & Framing

• Diagnostic, not prescriptive. Present findings as "here is what we found" not "you must fix this."
• Explain the why. For each finding, briefly explain the caching impact so the user can make an informed decision.
• Acknowledge trade-offs. Some cache-unfriendly patterns exist for good reasons (e.g., keeping lessons in CLAUDE.md for projects where context is critical). Note these rather than blindly flagging them.
• No false alarms. If CLAUDE.md does not exist, report that and skip all checks. If a check has nothing to flag, mark it PASS and move on. Do not invent findings.

Notes

• Works on any project. Does not assume claudefather is installed. Checks whatever CLAUDE.md and .claude/ configuration exists in the current project root.
• No CLAUDE.md = short report. If the project has no CLAUDE.md, report "No CLAUDE.md found — nothing to audit" and exit. Do not create one.
• Read-only. Never modify any files. This is a diagnostic tool.
• No subagents. Read files directly and present findings in a single response. Do not use the Task tool.
• Run occasionally. Not embedded in every workflow. Users run it when they want to check cache hygiene.

========================================

Migration

Consolidated from legacy skills. Pick the mode/lens based on intent.