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 analyzes your code against the project’s conventions and classifies violations as Critical (blocks PR), Important (technical debt), or Minor (stylistic). It reads rules from openspec/steering/conventions.md and openspec/steering/project-rules.md — the same files that /sdd-apply consults during implementation. Running the audit before opening a PR catches architectural and semantic violations that no linter detects.

​
Running an audit

/sdd-audit                  # Check files modified in current branch
/sdd-audit src/components/  # Check a specific path
Prerequisite: openspec/steering/conventions.md must exist. If it doesn’t, run /sdd-init (new project) or /sdd-steer (existing project) first. Before analyzing, the skill prints its scope so you know exactly what it’s checking: 
Analyzing: 4 modified files since main
  src/api/handler.py
  src/api/router.py
  tests/test_handler.py
  ...
Ruleset: conventions.md (12 rules) + project-rules.md (8 rules) = 20 rules
If the scope exceeds 20 files, the skill asks whether you want to limit the analysis to a subdirectory.

​
Understanding the audit report

The report uses a compact, terse format — one line per violation with an ID, file, approximate line, description, the rule that was violated, and a concrete fix suggestion. 
## Audit Report — api-demo — 2026-04-15
Scope: 3 files analyzed | Rules checked: 10 (conventions: 10 + project-rules: 0)

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

### Critical (blocks PR review)

- [C01] `src/api/handler.py:15` — Repository injected directly into handler
  - Rule: Architecture — MUST NOT inject Repository directly into handlers [conventions.md]
  - Fix: Introduce a use case interface; inject the use case, not the repository

- [C02] `src/api/handler.py:42` — Function parameter missing type hint
  - Rule: Code style — MUST use type hints for all parameters [conventions.md]
  - Fix: Add type annotation to `user_id` parameter

### Important (technical debt)

- [I01] `src/api/handler.py:28` — Method is 67 lines
  - Rule: Architecture — SHOULD keep handlers under 50 lines [conventions.md]
  - Fix: Extract validation logic into a separate helper function

### Minor

(none)

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

## Summary

| Level    | Count |
|----------|-------|
| Critical | 2     |
| Important | 1    |
| Minor    | 0     |
| Total    | 3     |

## SDD Actions

To fix critical violations:
/sdd-new "fix audit violations in api handler"

​
Violation severity levels

SeverityRule levelImpactAction
CriticalMUST / MUST NOTBlocks PR reviewFix before creating PR
ImportantSHOULDAccumulating technical debtCan be deferred; document in tasks.md
MinorMAYStylistic or preferenceFix opportunistically
The audit is semantic, not syntactic — it complements your linter (ruff, eslint, PHPStan), not replace it. Rules that are already enforced by a linter should not appear in conventions.md; the audit catches architectural and domain-level violations that static analysis cannot detect.

​
Writing effective conventions

conventions.md uses RFC 2119 keyword levels for precision. Every rule is one of MUST, MUST NOT, SHOULD, SHOULD NOT, or MAY. The keyword determines the violation severity and directly controls whether the audit flags something as Critical, Important, or Minor. 
# Conventions: api-demo

> Rules that cause PR review failures. RFC 2119 levels: MUST / MUST NOT / SHOULD / MAY.

## Bootstrap decisions
- Architecture: simple layered — single-purpose demo, no ceremony needed
- Testing: tests-after — small scope, fast iteration
- Commit format: `[change-name] Description` — SDD default

## HTTP responses
- **MUST** return JSON with `Content-Type: application/json`
- **MUST** use standard HTTP status codes (200, 404, 500)
- **MUST NOT** return HTML from API endpoints

## Code style
- **MUST** use ES module imports (`import`, not `require`)
- **SHOULD** keep route handlers in separate files under `src/routes/`

## Testing
- **MUST** test happy path and error cases for each endpoint
- **SHOULD** use `node --test` (built-in, no dependencies)
This is the complete conventions.md from the api-demo example. A few principles to follow when writing your own:
  • One rule per bullet. Each bullet should express a single, testable condition.
  • Be concrete about the violation. “MUST NOT inject Repository directly into handlers — use via use case interfaces” gives the audit model enough context to recognize the pattern.
  • Reserve MUST for things you’d actually reject a PR over. If you’d let it through with a comment, use SHOULD.
  • Group by area. Section headers (Architecture, Testing, HTTP responses, etc.) help the audit organize its report and help the AI determine which rules apply to which files.

​
Updating conventions

Conventions are not static — they evolve as your codebase grows, your team adopts new patterns, and the AI learns from your corrections.

​
Detect drift with /sdd-steer sync

After a major refactor or when you suspect conventions no longer reflect how the code is actually written: 
/sdd-steer sync
This compares the current conventions.md against actual code patterns, active skills, and MEMORY.md, then presents a diff of proposed additions, updates, and removals for your confirmation. It never auto-applies changes — you review and approve each proposal.

​
Automatic growth via project-rules.md

During /sdd-apply, when you correct the AI’s behavior, the correction gets recorded in project-rules.md:
  • Explicit correction ("always use X", "remember this") — saved immediately as a rule
  • Implicit correction (you override the AI’s choice) — the AI asks “save as rule?” before recording
  • Second correction of the same pattern — saved automatically without asking
Rules in project-rules.md use the same RFC 2119 format as conventions.md and are checked by /sdd-audit with equal weight: 
**MUST** pass `startTime` as a parameter to route handlers — never read from global state

​
Manual edits

Both conventions.md and project-rules.md are plain Markdown. Edit them directly at any time. There is no schema to follow beyond the RFC 2119 keyword format — the files are read by the AI, not parsed by a tool.
Make /sdd-audit part of your pre-PR routine. Run it on your current branch before pushing — critical violations caught here cost seconds to fix, versus minutes of back-and-forth in code review.
/sdd-audit        # scope: files modified since main
For teams that want automated enforcement, add it as a pre-push hook or a CI step. Any output containing Critical exits non-zero, which is enough to gate a pipeline.

Build docs developers (and LLMs) love

Get started for freeTalk to us