From sdd
Audits alignment between ADRs, specs, and code across project or module/scope, covering six drift categories with structured prioritized reports.
npx claudepluginhub joestump/claude-plugin-sdd --plugin sddThis skill uses the workspace's default tool permissions.
You are performing a deep, comprehensive audit of design artifact alignment across the project or a specified scope. This skill covers all six drift categories and produces a structured report with prioritized findings.
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Guides code writing, review, and refactoring with Karpathy-inspired rules to avoid overcomplication, ensure simplicity, surgical changes, and verifiable success criteria.
Provides UI/UX resources: 50+ styles, color palettes, font pairings, guidelines, charts for web/mobile across React, Next.js, Vue, Svelte, Tailwind, React Native, Flutter. Aids planning, building, reviewing interfaces.
Share bugs, ideas, or general feedback.
You are performing a deep, comprehensive audit of design artifact alignment across the project or a specified scope. This skill covers all six drift categories and produces a structured report with prioritized findings.
Resolve artifact paths: Follow the Artifact Path Resolution pattern from references/shared-patterns.md to determine the ADR and spec directories. If $ARGUMENTS contains --module <name>, resolve paths relative to that module; otherwise, in a workspace, aggregate across all modules. The resolved ADR directory is {adr-dir} and spec directory is {spec-dir}.
Cross-module aggregation: When in aggregate mode (no --module, workspace detected), iterate over all discovered modules and run the full audit analysis (steps 4–6) per module. Label every finding with its source module in the output tables (add a Module column). After per-module analysis, include a Cross-Module Summary section that aggregates finding counts per module and highlights any cross-module inconsistencies (e.g., one module's ADR contradicting another module's spec). When --module is provided, scope to that single module — no module labels needed. When in single-module mode (no workspace), operate normally.
Parse arguments: Extract the scope and flags from $ARGUMENTS.
security, api, database), a directory path (src/), or omitted for a full project audit.--review: Enable team review mode. Default: off. Mutually exclusive with: --scrum.--scrum: Enable scrum triage ceremony. Default: off. Mutually exclusive with: --review.--module <name>: Resolve artifact paths relative to the named module. Default: none./sdd:audit without a scope for a full project audit."Locate design artifacts:
{adr-dir} for ADR files. If the directory does not exist, report: "The {adr-dir} directory does not exist. Run /sdd:adr [description] to create your first ADR."{spec-dir} for spec files. If the directory does not exist, report: "The {spec-dir} directory does not exist. Run /sdd:spec [capability] to create your first spec."/sdd:adr or a spec with /sdd:spec first."Choose execution mode: Check if $ARGUMENTS contains --scrum or --review. --scrum takes precedence over --review if both are present.
Default (no --review, no --scrum): Single-agent mode.
With --review (and no --scrum): Team review mode.
TeamCreate:
general-purpose) to perform the full analysis and write the audit reportgeneral-purpose) to validate the auditor's findings for accuracy, completeness, and correct severity assignmentsTeamCreate fails, fall back to single-agent mode and tell the user: "Team creation failed. Proceeding with single-agent audit and self-review."With --scrum: Scrum triage mode — see the Scrum Triage Ceremony section below. When --scrum is set, complete the standard audit analysis (steps 4–6) first, then enter the ceremony. Do NOT run --review mode when --scrum is set.
3a. Tier 3 staleness check (v5.0.0+):
On entry, check the qmd index's last-modified timestamp for this repo's collections (use the exact-prefix match algorithm from references/qmd-helpers.md § "This-Repo Collection Identification"). If older than the configured staleness threshold (default 120m, configurable in CLAUDE.md ### SDD Configuration #### Index Freshness **Staleness Threshold** per the Config Resolution pattern), trigger a silent qmd update first. Emit a one-line note in the report header: Index was {age} stale — refreshed before running. On fresh, proceed silently. On qmd update failure, surface the error per qmd-helpers.md § "Error Handling" and continue best-effort.
3b. qmd-aware artifact retrieval per target file (v5.0.0+):
Audit operates at scale across many target files. For each target file in scope, use qmd hybrid retrieval (per references/qmd-helpers.md § "Hybrid Retrieval") to identify the top-K candidate ADRs and specs governing that specific file, then deep-read only those candidates. The pre-v5 "read all ADRs and specs once, then semantically match against every target" path is removed in v5 — per-target qmd retrieval is the canonical mechanism.
Per-file query construction follows the same pattern as /sdd:check:
lex: file path basename + exported symbols + governing comment block contentvec: one-sentence summary of what the file doesintent: "/sdd:audit {scope} — find ADRs and specs governing {file}"collections: ["{repo}-adrs", "{repo}-specs"] (or per-module variants)limit: 8, minScore: 0.3Per-target retrieval is more expensive than the pre-v5 single-pass scan, but produces dramatically tighter, file-relevant context for the drift analysis in Step 5. On large audit scopes (entire repo), this is what /sdd:audit was designed to scale to — the per-target retrieval is small per-call and runs in qmd's sub-second hybrid path.
On qmd unreachable / timeout per qmd-helpers.md § "Error Handling", surface the error and stop. Per ADR-0024 / SPEC-0019 REQ "qmd Assumption in Consumer Skills", fallback paths were eliminated in v5; the failure mode is "fix qmd, retry."
Validate spec artifact pairing: For each spec directory found under {spec-dir}, check that both spec.md and design.md exist. If a spec.md exists without a corresponding design.md (or vice versa), report as [WARNING] under "Stale Artifacts" with finding: "Unpaired spec artifact: {path} exists but {missing-file} is missing. Per ADR-0003, spec.md and design.md are a paired unit." (Governing: ADR-0003, SPEC-0003)
Analyze across all six categories:
Code vs. Specification Drift: Does the implementation match spec requirements and scenarios?
[CRITICAL][WARNING][WARNING]Code vs. ADR Drift: Does the implementation follow accepted ADR decisions?
[CRITICAL][WARNING]ADR vs. Spec Inconsistencies: Are ADR decisions consistent with spec requirements?
[CRITICAL][WARNING]Coverage Gaps: What code areas have no governing ADR or spec?
[INFO]Stale Artifacts: Do artifact statuses match implementation reality?
proposed that have existing implementations -- [WARNING]draft that have deployed implementations -- [WARNING]accepted ADRs whose decisions have been overridden in code -- [WARNING]Policy Violations: Are specs internally consistent in their use of RFC 2119 keywords?
[INFO][CRITICAL][INFO]Produce the audit report using the standard format:
## Design Audit Report
Scope: {scope or "Full project"}
Analyzed: {N} ADRs, {M} specs, {P} source files
Total findings: {X} ({C} critical, {W} warning, {I} info)
---
### Code vs. Specification Drift
| Severity | Finding | Spec | Location |
|----------|---------|------|----------|
| [CRITICAL] | {description} | SPEC-XXXX | src/path/file.ts:NN |
### Code vs. ADR Drift
| Severity | Finding | ADR | Location |
|----------|---------|-----|----------|
| [WARNING] | {description} | ADR-XXXX | src/path/file.ts:NN |
### ADR vs. Spec Inconsistencies
| Severity | Finding | ADR | Spec |
|----------|---------|-----|------|
| [CRITICAL] | {description} | ADR-XXXX | SPEC-XXXX |
### Coverage Gaps
| Severity | Area | Description |
|----------|------|-------------|
| [INFO] | src/path/ | {description} |
### Stale Artifacts
| Severity | Artifact | Issue |
|----------|----------|-------|
| [WARNING] | ADR-XXXX | {description} |
### Policy Violations
| Severity | Finding | Source | Location |
|----------|---------|--------|----------|
| [INFO] | {description} | SPEC-XXXX | {spec-dir}/path/spec.md |
---
### Summary
| Category | Critical | Warning | Info | Total |
|----------|----------|---------|------|-------|
| Code vs. Spec | N | N | N | N |
| Code vs. ADR | N | N | N | N |
| ADR vs. Spec | N | N | N | N |
| Coverage Gaps | N | N | N | N |
| Stale Artifacts | N | N | N | N |
| Policy Violations | N | N | N | N |
| **Total** | **N** | **N** | **N** | **N** |
### Recommended Actions
1. [CRITICAL] {action}
2. [WARNING] {action}
3. [INFO] {action}
Workspace aggregate mode adds these sections to the report:
Module column in every findings table (e.g., | [api] | [CRITICAL] | ... |)### Cross-Module Summary
| Module | Critical | Warning | Info | Total |
|--------|----------|---------|------|-------|
| [api] | N | N | N | N |
| [worker] | N | N | N | N |
| **Total** | **N** | **N** | **N** | **N** |
### Cross-Module Inconsistencies
| Severity | Finding | Module A | Module B |
|----------|---------|----------|----------|
| [CRITICAL] | {description of cross-module contradiction} | [api] ADR-XXXX | [worker] SPEC-XXXX |
If no cross-module inconsistencies are found, omit the "Cross-Module Inconsistencies" table and note: "No cross-module inconsistencies detected."
Add recommended actions at the end, ordered by severity:
/sdd:status to update/sdd:adr/sdd:spec/sdd:check (audit is a superset of check)Handle clean results: If no drift is found across any category:
## Design Audit Report
Scope: {scope or "Full project"}
Analyzed: {N} ADRs, {M} specs, {P} source files
No drift detected. All implementation aligns with governing ADRs and specs.
--scrum)When --scrum is set, run the standard audit analysis (steps 4-8 above) first, then follow the Triage Ceremony in references/triage-ceremony.md. The triage ceremony groups audit findings into functional themes, runs a 5-agent triage team to prioritize and dispute findings, and produces a triage report with remediation priorities and optional issue creation. Governing: SPEC-0013, ADR-0014.
--review mode)TeamDelete when done.See the plugin's references/shared-patterns.md § "Severity Assignment Rules" for the full mapping. Key: MUST/SHALL violations → CRITICAL, SHOULD violations → WARNING, coverage gaps → INFO.
--review mode, follow the team handoff protocol exactly. Do not present the report until the reviewer sends "APPROVED".ADR-0001, SPEC-0002, Req 3. Do not abbreviate.src/auth/login.ts:45).## for the top-level heading (report title) and ### for sections within the report.--scrum is set, MUST run the full standard audit analysis first, then the triage ceremony — never skip the standard analysis (Governing: SPEC-0013 REQ "Scrum Flag and Mode Activation")--scrum and --review are mutually exclusive; --scrum takes precedence if both are providedaccepted) and specs (approved/implemented) are the source of truth — code deviation is presumed wrong unless the Architect explicitly reclassifies a finding as an artifact update (Governing: SPEC-0013 REQ "Source of Truth Principle")qmd update and emit a one-line note (Governing: ADR-0026, SPEC-0019 REQ "Tier 3 Staleness Threshold for Consumer Skills")