Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/jorgeferrando/sdd-skills/llms.txt

Use this file to discover all available pages before exploring further.

/sdd-audit is a semantic code-review tool that checks your changes against the conventions and project rules captured in openspec/steering/. Run it before opening a pull request to catch architecture violations early, after a refactor to confirm nothing has drifted, or periodically to track accumulated technical debt. Unlike a linter — which enforces syntax and style — audit is semantic: it checks whether the code follows the architectural patterns, naming conventions, and structural rules your team has documented. It complements your linter rather than replacing it.

​
Usage

/sdd-audit                      # Analyze files modified in the current branch
/sdd-audit src/components/      # Analyze a specific directory or file

​
Prerequisites

openspec/steering/conventions.md must exist. This file is generated by /sdd-init (new project) or /sdd-steer (existing project).
Without conventions.md, /sdd-audit has no reference to check against and will not run. If the file is missing, run /sdd-init or /sdd-steer first to establish your project’s conventions baseline.

​
What It Does

1
Verify prerequisites
2
Checks that openspec/steering/conventions.md exists. If it is missing, the skill stops and tells you which command to run to create it.
3
Load the ruleset
4
Reads the steering files as a unified ruleset:
5
  • openspec/steering/conventions.md (required)
  • openspec/steering/project-rules.md (if it exists)
  • Specialist files (conventions-*.md) loaded selectively based on the files in scope — for example, conventions-testing.md is loaded only when the scope includes test files, and conventions-security.md only when scope includes auth or input-handling files. Irrelevant specialists are skipped to keep context focused.
    • 6
    Rules in project-rules.md that duplicate existing linter coverage (quote style, import order, etc.) are excluded — audit is semantic, not syntactic.
    7
    Determine analysis scope
    8
    No argument: detects files modified since the branch diverged from main:
    9
    git diff --name-only $(git merge-base HEAD main 2>/dev/null || echo "HEAD~10") HEAD
    10
    With path argument: uses the files at the provided path.
    11
    The scope and rule count are shown before analysis begins:
    12
    Analyzing: 4 modified files since main
  src/components/UserCard.tsx
  src/services/user.service.ts
  tests/user.service.spec.ts
  ...
Ruleset: conventions.md (12 rules) + project-rules.md (8 rules) = 20 rules
    13
    If the scope exceeds 20 files, the skill asks whether you want to narrow the analysis.
    14
    Analyze each file
    15
    For each file in scope, every applicable MUST / MUST NOT / SHOULD / MAY rule is checked. Violations are noted with approximate line numbers and concrete descriptions. The source file (conventions.md vs project-rules.md) is recorded for each violation.
    16
    Generate the report
    17
    Violations are classified into three severity levels:
    18
    SeverityRule keywordMeaningCriticalMUST / MUST NOTViolates a hard architectural rule — typically flagged in PR reviewImportantSHOULDAccumulating technical debt — deferrable but trackedMinorMAYStylistic or preference — low urgency
    19
    The report uses terse, one-line formatting per violation:
    20
    ## Audit Report — {project} — {date}
Scope: {N files analyzed} | Rules checked: {N}

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

### Critical (blocks PR review)

- [C01] `src/api/handler.py:15` — MUST NOT inject Repository directly
  - Rule: architecture — MUST NOT bypass the service layer [conventions.md]
  - Fix: inject UserService instead

- [C02] `src/api/handler.py:42` — MUST use type hints for all parameters
  - Rule: code-style — MUST annotate function parameters [conventions.md]
  - Fix: add type annotations to all parameters

### Important (technical debt)

- [I01] `src/api/handler.py:28` — SHOULD keep methods under 50 lines (current: 67)
  - Rule: structure — SHOULD limit method length [conventions.md]
  - Fix: extract the validation block into a separate method

### Minor

- [M01] `src/services/user.service.ts:8` — MAY use readonly for injected dependencies
  - Rule: style — MAY declare injected fields as readonly [conventions.md]
  - Fix: add readonly modifier

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

## Summary

| Level    | Count |
|----------|-------|
| Critical | 2     |
| Important| 1     |
| Minor    | 1     |
| Total    | 4     |
    21
    If critical or important violations exist, the report ends with grouped /sdd-new prompts to track the fixes as SDD changes:
    22
    To fix critical violations:
/sdd-new "fix: bypass-service-layer violations in api handler"
    23
    If no violations are found:
    24
    ✓ No violations found — conventions upheld.
  4 files analyzed, 20 rules checked
    25
    Final recommendation
    26
    If criticals are present, the skill recommends fixing before creating a PR. If only important or minor issues exist, they can be deferred by documenting them in tasks.md.

    ​
    Output

    /sdd-audit does not modify any code. It produces a report only. Fix recommendations suggest the exact change needed; /sdd-new prompts let you track groups of violations as first-class SDD changes rather than ad-hoc edits.

    ​
    Skill Metadata

    FieldValue
    model_hintsonnet
    requiresopenspec/steering/conventions.md
    producesAudit report (no files written)
    /sdd-audit also runs automatically as part of /sdd-verify — when conventions.md exists, verify runs an audit on the changed files as an additional quality gate before the PR is created.

    ​
    When to Use

    The primary use case. Run /sdd-audit to catch convention violations before reviewers do — critical violations are exactly the kind of feedback that shows up in PR comments.
    Refactors touch many files and can introduce drift. Run /sdd-audit src/ on the affected directory to confirm the refactored code still follows the established patterns.
    Use audit on a new team member’s first PR as an educational tool — it explains which rule was violated and why, not just that something is wrong.
    Run audit periodically on the whole codebase (or a specific domain) to track how technical debt is evolving over time.

    ​
    Next Steps

    • Fix critical violations before creating a PR. Use the suggested /sdd-new prompts to track them as proper SDD changes.
    • Defer important violations by adding them to tasks.md so they are tracked but not blocking.
    • After implementing fixes, run /sdd-audit again to confirm the violations are resolved.

    Build docs developers (and LLMs) love

    Get started for freeTalk to us