audit

What this skill does

# Audit: Project Quality Scorecard

**EXECUTE this skill now.** Follow the workflow steps below using the provided $ARGUMENTS. Do NOT describe, summarize, or explain this skill — run it.

## Constants

- `PRINCIPLES_DIR`: `C:/Users/gurusharan.gupta/Agents/Claude Code/principles`
- `PRINCIPLES_INDEX`: `C:/Users/gurusharan.gupta/Agents/Claude Code/principles/_index.json`
- `MANIFEST_PATH`: `C:/Users/gurusharan.gupta/Agents/Claude Code/manifest.json`

## Commands

Parse $ARGUMENTS to determine action:
- `/audit` — Audit the current project
- `/audit <project-id>` — Audit a specific registered project by ID
- `/audit all` — Audit all active projects in the manifest
- `/audit principles` — List all golden principles with descriptions

## Workflow: Audit a Project

### Step 1: Identify Target

If no argument, use the current working directory.
If a project-id is given, look it up in the manifest to get the path.
If `all`, iterate over all active projects.

### Step 2: Read Principles

Read `PRINCIPLES_INDEX` to get the list of all principles with severity and enforcement method.

### Step 3: Check Each Principle

For each principle, run the appropriate check against the project directory:

**claude-md-required** (critical):
- Check: `CLAUDE.md` or `.claude/CLAUDE.md` exists
- Check: File is under 150 lines
- Check: Contains "## Commands" and "## Architecture" sections

**formatting-configured** (critical):
- Check for JS/TS: `.prettierrc`, `.prettierrc.json`, `prettier` in package.json, `.eslintrc*`, `eslint.config.*`
- Check for Python: `pyproject.toml` with `[tool.black]` or `[tool.ruff]`, `.flake8`, `setup.cfg` with flake8
- Check for Rust: `rustfmt.toml` or `.rustfmt.toml`
- Check for Go: always passes (gofmt built-in)
- If no recognized tech stack: SKIP (not applicable)

**tests-required** (critical):
- Check for JS/TS: `jest.config.*`, `vitest.config.*`, `*.test.*` or `*.spec.*` files exist, `"test"` script in package.json
- Check for Python: `pytest.ini`, `pyproject.toml` with `[tool.pytest]`, `tests/` directory, `test_*.py` files
- Check for Rust: `#[test]` in source files or `tests/` directory
- If no recognized tech stack: check for any `test` directory

**parse-at-boundaries** (critical):
- Cannot be mechanically checked fully. Check proxy indicators:
- For JS/TS: Zod, joi, yup, or io-ts in dependencies
- For Python: Pydantic in requirements
- Otherwise: MANUAL (flag for human review)

**semantic-file-naming** (recommended):
- Check: No files named `helpers.*`, `utils.*`, `common.*`, `misc.*`, `shared.*` at any level
- Use glob to find violations

**no-utils-helpers-dirs** (recommended):
- Check: `find $PROJECT -type d -name "utils" -o -name "helpers" -o -name "misc" -o -name "common" -o -name "shared"`
- Exclude `node_modules/`, `venv/`, `.git/`

**structured-logging** (recommended):
- Check proxy: structured logging library in dependencies (winston, pino, bunyan for JS; structlog, python-json-logger for Python)
- If no dependencies found: MANUAL

### Step 4: Check Additional Quality Signals

Beyond principles, check:
- `docs/` directory exists with exec-plans/, design-docs/ subdirectories
- `.claude/` directory exists
- `.git/` initialized
- Active exec-plans present and not stale (>30 days since last progress update)

### Step 5: Calculate Quality Score

Scoring:
- Start at 100 points
- Each FAILED critical principle: -20 points
- Each FAILED recommended principle: -10 points
- Each FAILED suggested principle: -5 points
- Missing docs/ structure: -10
- Missing .git/: -10
- Stale exec-plans: -5

Grade:
- A: 90-100
- B: 75-89
- C: 60-74
- D: 40-59
- F: 0-39

### Step 6: Output Scorecard

```
╔══════════════════════════════════════════════════╗
║  Audit: {project_name}                           ║
║  Path:  {project_path}                           ║
╠══════════════════════════════════════════════════╣
║                                                  ║
║  Golden Principles:                              ║
║    ✓ parse-at-boundaries          PASS           ║
║    ✗ claude-md-required           FAIL (missing) ║
║    ✗ tests-required               FAIL (no config)║
║    ✗ formatting-configured        FAIL           ║
║    ✓ semantic-file-naming         PASS           ║
║    ✓ no-utils-helpers-dirs        PASS           ║
║    ~ structured-logging           MANUAL         ║
║                                                  ║
║  Infrastructure:                                 ║
║    docs/ structure                MISSING        ║
║    .claude/ config                PRESENT        ║
║    .git/ initialized              MISSING        ║
║    Active exec-plans              NONE           ║
║                                                  ║
║  Score: 40/100                                   ║
║  Grade: D                                        ║
║                                                  ║
║  Critical issues (fix first):                    ║
║    1. Run /init-project to create CLAUDE.md      ║
║    2. Add test framework for Python              ║
║    3. Add formatter (black/ruff) config          ║
║                                                  ║
╚══════════════════════════════════════════════════╝
```

### Step 7: Update Manifest (optional)

If the user wants to persist the score, update the project's entry in manifest.json with:
```json
"quality_score": {
  "grade": "D",
  "score": 40,
  "last_audit": "2026-03-26",
  "critical_failures": 3,
  "recommended_failures": 0
}
```

## Workflow: List Principles

When the user runs `/audit principles`:

Read all principle files and display:

```
Golden Principles (7):

  CRITICAL:
    parse-at-boundaries      All external data parsed at boundary into typed representations
    tests-required           All new code must have tests, target 100% coverage
    formatting-configured    Automated formatting/linting configured before agent work
    claude-md-required       CLAUDE.md must exist following table-of-contents pattern

  RECOMMENDED:
    semantic-file-naming     Files/dirs use domain-specific names, not generic labels
    no-utils-helpers-dirs    No utils/, helpers/, misc/ directories
    structured-logging       Structured logging (JSON/key-value) in production code
```

## Important

- Audit is read-only. Never modify project files during an audit.
- MANUAL checks should be flagged clearly — they require human judgment.
- Always suggest specific remediation actions for each failure.
- The /init-project skill can fix most infrastructure-level failures.
- Quality scores are informational. They help prioritize cleanup, not block work.