kmshihab7878/claude-code-setup/audit

/audit — Four-Cs Score

Read-only weekly audit. Adapted from AIS-OS. Pairs with /level-up (the action loop).

When to use

• The user runs /audit
• Weekly Friday cadence (see docs/CADENCE.md)
• Before planning a quarter — establish a baseline
• After a major change to the OS — measure drift

When NOT to use

• Daily — too noisy, the trend disappears
• Mid-task — audit is reflective, not action-driving
• For deep code review — that's /audit-deep. This is OS-level audit, not codebase audit.

Inputs

• Current state of context/, connections.md, skills/, commands/, agents/, recipes/, decisions/log.md, ~/.claude/usage.jsonl (if exists)
• Optional flag --no-save: print the report without writing to docs/audits/

Outputs

• A score 0-100 broken down by Four Cs
• Top 3 leverage gaps (highest impact × lowest cost)
• One recommended next action
• File: docs/audits/YYYY-MM-DD.md (full report)
• One-line entry in decisions/log.md

Hard rules

• MUST be read-only by default. No edits to anything except docs/audits/ and decisions/log.md.
• MUST NOT modify settings.json, core/*, domains/*, CLAUDE.md, or any skill/agent definition.
• MUST surface the top 3 gaps, not 10. If you can't pick 3, pick 1 and state confidence.
• MUST cite the file paths that informed each score, so the audit is reproducible.

Steps

1. Pre-flight

• git status --short — note dirty state, but don't fail
• ls context/ — verify expected files exist
• claude mcp list 2>/dev/null — capture live MCP state (don't fail if it times out)
• Compute date: YYYY-MM-DD for the report filename

2. Score the Four Cs

Context (out of 25)

Inputs:

• Are context/About Me.md, About Business.md, Priorities.md, Voice Sample.md, Operating Preferences.md non-placeholder?
• Has decisions/log.md had an entry in the last 30 days?
• Do active projects have their own MEMORY.md?
• Last /onboard run — within 90 days?

Banding:

Connections (out of 25)

Inputs:

• Does connections.md exist with all 7 domains represented (even as Tier-4 "manual")?
• Does every active connection have a documented kill switch?
• Does every high sensitivity tool have a dedicated service account noted?
• Are credentials referenced via .env.example placeholders (no real secrets in repo)?
• claude mcp list — count of live servers vs. count documented in connections.md

Banding:

Capabilities (out of 25)

Inputs:

• Count workflows mentioned in decisions/log.md from last 90 days that lack a corresponding skill/script
• Count of skills with no improvement loop documented
• Count of skills > 500 lines without references/ extraction
• docs/CAPABILITIES.md last updated date

Banding:

Cadence (out of 25)

Inputs:

• Last /audit run — within 14 days = healthy, 14-30 = stale, >30 = dormant
• Last /level-up run
• Daily/weekly skills used in last 7 days (check ~/.claude/usage.jsonl if available)
• Any /schedule-d job running > 30 days without review

Banding:

3. Identify top 3 leverage gaps

For each pillar with a score below the next band threshold, list:

• The exact missing artifact (e.g. "no connections.md rows for Tasks domain")
• The cost to fix (low / medium / high — in operator hours)
• The impact (low / medium / high — on Four-Cs trend)

Pick the 3 with highest impact ÷ lowest cost. Order by impact descending.

4. Recommend ONE next action

The single thing to do next week. Not a list. The one action that, if done, moves the lowest-scoring pillar by 5+ points.

Frame as: "Run /level-up Friday with constraint = <gap>. Build <artifact> first."

5. Write the report

Path: docs/audits/YYYY-MM-DD.md

Format:

# Audit — YYYY-MM-DD
 
**Total: <score>/100**
 
| Pillar | Score | Trend |
|--------|-------|-------|
| Context | X/25 | ↑/→/↓ vs last audit |
| Connections | X/25 | |
| Capabilities | X/25 | |
| Cadence | X/25 | |
 
## Top 3 leverage gaps
1.<gap> (impact: ?, cost: ?, fix: <pointer>)
2.<gap>
3.<gap>
 
## Next action
<one sentence>
 
## Evidence
-<path>: <what it told us>
-<path>: <what it told us>

6. Log to decisions/log.md

## YYYY-MM-DD — Audit: <total>/100
 
**Decision:** Audit captured. Top gap: <one-line>.
**Status:** Read-only audit; no changes applied.
**Follow-up:** Run /level-up Friday targeting: <gap>.

7. Output to user

Print the report (not the full file — just the summary table + top 3 gaps + next action).

Failure modes

Reference files

• references/four-cs-framework.md — the rubric
• references/3ms-framework.md — what "leverage gap" means
• docs/CADENCE.md — when to run this
• docs/audits/README.md — where reports live

Improvement loop

After every run:

1. Was the score the operator expected? If wildly off → rubric needs adjustment
2. Did the recommended action match what the operator actually did? If no → recommendation logic is wrong
3. Did the next audit show movement? If no → either the action was wrong or it wasn't done