home / skills / madebyaris / spec-kit-command-cursor / sdd-audit

sdd-audit skill

safe

This skill analyzes code against specifications, identifies gaps, and generates structured audit reports to improve quality and compliance.

npx playbooks add skill madebyaris/spec-kit-command-cursor --skill sdd-audit

Review the files below or copy the command above to add this skill to your agents.

Files (3)

SKILL.md

2.1 KB

---
name: sdd-audit
description: Compare implementation against specifications, identify gaps and issues. Use for code review, quality assurance, and verifying spec compliance.
---

# SDD Audit Skill

Compare implementations against specifications and generate structured review reports.

## When to Use

- Code review before marking tasks complete
- Quality assurance checks
- Verifying implementation matches spec
- Identifying technical debt and issues

## Workflow

1. **Load specs**: Read `spec.md` → `plan.md` → `tasks.md`
2. **Identify scope**: Check `todo-list.md` for completed work
3. **Inspect code**: Review implementation for each task
4. **Gap analysis**: Compare spec requirements vs actual code
5. **Generate report**: Structured findings with severity levels

## Audit Checklist

Reference `references/checklist.md` for the complete audit checklist covering:
- Functional requirements compliance
- Non-functional requirements (performance, security)
- Code quality standards
- Edge case handling

## Severity Levels

- **CRITICAL**: Broken functionality, security risk, release blocker
- **MAJOR**: Logic error, missing feature, significant bug
- **MINOR**: Style issue, optimization opportunity, cleanup
- **OUTDATED**: Code correct but spec needs updating

## Report Format

```markdown
## Audit Report: [Feature]

**Status:** Pass | Fail | Warnings
**Date:** [timestamp]
**Spec Version:** [version]

### Quick Stats
- CRITICAL: [N]
- MAJOR: [N]  
- MINOR: [N]

### Review Comments
| ID | Severity | Location | Issue | Recommendation |
|:--:|:--------:|:---------|:------|:---------------|
| #1 | CRITICAL | `file:line` | Description | Fix suggestion |

### Spec Compliance
| Requirement | Status | Evidence |
|-------------|--------|----------|
| Req 1 | MET | [file:line] |
| Req 2 | NOT MET | [gap description] |

### Recommended Actions
1. [Priority action]
2. [Secondary action]
```

## Integration

- Works with `sdd-verifier` subagent for automated validation
- Can trigger `scripts/validate.sh` for automated checks
- Best used with Cursor's Debug Mode for runtime evidence
- Use the ask question tool if audit criteria are unclear

Overview

This skill compares an implementation against its specifications and produces a structured audit report highlighting gaps, issues, and compliance status. It is designed for spec-driven development workflows to support code review, QA, and release readiness. Use it to surface functional, non-functional, and documentation mismatches with clear severity levels and recommended actions.

How this skill works

The audit loads spec artifacts (spec.md, plan.md, tasks.md) and examines the todo-list to determine implemented scope. It inspects code and runtime evidence where available, runs checklist-driven checks, and performs a gap analysis between requirements and the actual implementation. Results are emitted in a standardized report with severity levels, evidence links, and prioritized remediation steps.

When to use it

Before marking tasks or features as complete to verify spec compliance
During code review or QA cycles to catch regressions and missing requirements
Prior to releases to identify release-blocking issues and security risks
When integrating third-party changes or refactors to ensure behavior parity
To convert informal feedback into structured action items for engineers

Best practices

Keep spec.md, plan.md, and tasks.md up to date; audits rely on accurate source documents
Run automated validation (scripts/validate.sh) before manual inspection to reduce noise
Attach runtime evidence (logs, traces) when possible to prove compliance or failures
Classify findings with CRITICAL/MAJOR/MINOR/OUTDATED to prioritize work
Integrate with sdd-verifier for automated checks and Cursor Debug Mode for live validation

Example use cases

Perform a pre-release audit to catch critical functionality and security gaps
Review a completed task list to verify every spec requirement is implemented
Assess technical debt introduced during a fast refactor and document remediation
Validate non-functional requirements such as performance and edge-case handling
Generate concise reports for project managers and maintainers with actionable fixes

FAQ

What files does the audit read?

It reads spec.md, plan.md, tasks.md and todo-list.md plus referenced checklist and code files for evidence.

How are severities determined?

Severities map to impact: CRITICAL blocks release or causes security risk; MAJOR breaks functionality; MINOR is cosmetic or optimization; OUTDATED means spec needs updating.

Can audits be automated?

Yes—use the sdd-verifier integration and scripts/validate.sh for automated checks, then run a manual pass for subjective or runtime issues.