SuperAPI AI Directory
Partner中文AI newsFavorites
Skillssdd-auditoria-harness

sdd-auditoria-harness

Coding & development

View repository

Updated 10-16 01:09

About this skill

Read-Only Audit of the SDD Harness

In the first response of this skill, start with this line, only once: sdd-auditoria-harness v1.0.0 · out/2026 · versão atual: https://github.com/robertodiasduarte/sdd-starter/releases/latest

Quick start

  1. Define REPO_ROOT as the root of the audited repository.
  2. First run the Safety Gate of this Skill.
  3. Read the SDD sources of truth: the project instruction files (CLAUDE.md and/or AGENTS.md), the SDD index/readme, and the engine configurations (.claude/settings.json / .claude/settings.local.json, .codex/config.toml).
  4. Optionally, generate structured evidence to stdout only: python scripts/collect_evidence.py "$REPO_ROOT".
  5. Perform the analysis following references/AUDIT_PROTOCOL.md.
  6. Create only the new report AUDITORIA_SDD_<AAAA-MM-DD>.md, using references/REPORT_TEMPLATE.md.
  7. Finish in the chat with the executive summary, the report path, and the phrase: nenhuma alteração foi feita — a faxina em si é decisão humana.

When to use / When not to use

When to use

Use this Skill to audit the SDD harness of a repository, whatever the engine. The surfaces change path depending on the tool; audit the ones that exist:

Ask Claude Code Codex / Kimi CLI
Project instructions CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md AGENTS.md (open standard; Claude Code also reads it by fallback since 2.1.277)
Skills .claude/skills/*/SKILL.md .agents/skills/*/SKILL.md, .codex/skills/*/SKILL.md
Commands .claude/commands/**/*.md .codex/prompts/**/*.md
Agents/subagents .claude/agents/**/*.md .agents/agents/**/*.md
Configuration .claude/settings.json, .claude/settings.local.json .codex/config.toml
Harness scripts .claude/scripts/** .agents/scripts/**, .codex/scripts/**

Also audit:

  • hooks, permissions, and scripts referenced by the harness;
  • process docs, playbooks, memory notes, and spec directories;
  • divergences between the official SDD flow and legacy, duplicated items or items with no evidence of use.

When not to use

Do not use this Skill to:

  • delete, edit, rename, move, format, or reorganize existing files;
  • automatically fix findings;
  • do git add, commit, push, pull, fetch, checkout, restore, reset, clean, rm or mv;
  • install dependencies, run deploys, or run commands with side effects;
  • audit outside the informed repository root;
  • conclude that something is “UNUSED” just because it looks old or rare.

Required data

Mandatory

  • REPO_ROOT: root of the repository containing the harness to audit.
  • Read access to the repository and, when available, to the Git history.

Automatically derived

  • REPORT_DATE: local date of the run, in the format AAAA-MM-DD.
  • REPORT_DIR: SDD reports folder, if there is one clearly established; otherwise, the repo root.
  • REPORT_PATH: REPORT_DIR/AUDITORIA_SDD_<REPORT_DATE>.md.

If REPO_ROOT is not clear, ask only: Qual é a raiz do repositório SDD que devo auditar?

Step-by-step procedure

0. Blocking Safety Gate

Before running any command:

  1. Confirm that the action is read-only.
  2. Refuse any command that could write, delete, move, rename, install, synchronize, or alter Git/project state.
  3. Prefer inspection commands such as git log, git status, git diff, git ls-files, git grep, rg, grep, find without destructive actions, cat, sed without -i, awk, head, tail, wc and reading via native tools.
  4. Do not use find -delete, find -exec with mutating commands, sed -i, redirections >/>>, tee, touch, mkdir, cp, rsync or scripts that write during the audit.
  5. The only permitted write is the creation of the new final report, at the computed path.
  6. If REPORT_PATH already exists, do not overwrite. Stop writing, deliver the summary in the chat and ask for a new explicitly authorized name.

1. Establish the main SDD

Read, in this order:

  1. the project instructions file at the root — CLAUDE.md or AGENTS.md, whichever exists (they can coexist);
  2. the same, in subdirectories relevant to the harness;
  3. index/readme of the SDD directory, such as sdd/_index.md, .claude/sdd/_index.md or equivalent;
  4. the engine configuration: .claude/settings.json and .claude/settings.local.json, and/or .codex/config.toml, including hooks and permissions.

⚠️ If the repository has AGENTS.md and no CLAUDE.md, this is not a gap: since Claude Code 2.1.277 the AGENTS.md is read by fallback, and Codex/Cursor/Gemini CLI already read it natively. Do not classify the absence of CLAUDE.md as a finding.

⚠️ If both exist, record the actual precedence: by default Claude Code reads only the files CLAUDE.md and ignores the AGENTS.md — unless the CLAUDE.md imports it with @AGENTS.md or that Project instructions is in claude-md-and-agents-md. An instruction that the student thinks is valid and is not read is CONFLICTING, and is one of the most useful findings of this audit.

Produce a 5–10 line summary containing:

  • official phases;
  • commands that invoke each phase;
  • path of the artifacts produced;
  • precedence/source-of-truth rules, if declared.

This summary is the yardstick for classifying AMBIGUOUS and CONFLICTING.

2. Complete inventory of the harness

Include one item per line for:

  • commands/slash commands;
  • agents;
  • skills;
  • hooks and permissions;
  • support scripts;
  • process docs and spec directories;
  • scripts external to the engine folder (.claude/, .agents/, .codex/) that are referenced by the harness.

For each item record: caminho | tipo | propósito declarado | idioma/origem aparente.

Do not mark “copied from template” without concrete evidence. If the origin cannot be proven, use indeterminada.

3. Measure usage and vitality

For each item, collect:

  1. Cross-references: inbound references in the rest of the harness.
  2. Recency: git log -1 --format=%cs -- <arquivo>.
  3. Execution signal: mentions in SDD reports/logs, when they exist.
  4. Duplication: objective overlap of purpose/output with another item.
  5. Drift: references to nonexistent files, phases, models, commands, or paths.

The helper scripts/collect_evidence.py can speed up items 1–3 and point out candidates for item 5. It only reads files and writes JSON to stdout.

Zero input references and no execution signal is only the minimum condition to consider NÃO UTILIZADO. If the item can be rare by design, classify it as a doubt and not as certainty.

4. Classify findings

Use only these labels, exactly:

  • EXCESS
  • OBSOLETE
  • SUPERFLUOUS
  • UNUSED
  • AMBIGUOUS
  • CONFLICTING

An item can receive more than one label.

Every finding must contain:

  • file;
  • line, when the evidence is in textual content;
  • concrete evidence;
  • recommendation.

A finding without verifiable evidence does not go into the findings table; it goes to “Doubts for the repo owner”.

Detailed criteria and cautions are in references/AUDIT_PROTOCOL.md.

5. Recommend, without executing

For each finding, choose exactly one suggested action:

  • MANTER
  • APOSENTAR — with tombstone/pointer; never recommend a hard delete;
  • FUNDIR com <item>
  • ESCLARECER
  • ARQUIVAR
  • REDUZIR

The recommendation describes what the owner could do afterward; do not make the change.

6. Create the final report

Use references/REPORT_TEMPLATE.md.

Location:

  1. SDD reports folder, if it exists and is clearly the reports home;
  2. otherwise, repository root.

Name: AUDITORIA_SDD_<AAAA-MM-DD>.md

Create this file only after all the analysis is ready and only if it does not already exist.

7. Final verification

Before concluding:

  1. confirm that no existing file was changed;
  2. confirm that only the new final report was created;
  3. confirm that each finding contains evidence;
  4. confirm that labels and actions use only the allowed values;
  5. confirm that unproven doubts were left out of the findings table;
  6. show the executive summary and the report path in the chat;
  7. repeat: nenhuma alteração foi feita — a faxina em si é decisão humana.

Validations and quality checklist

  • The main SDD was summarized before the findings.
  • All harness items were included in the inventory.
  • Each item has a path, type, purpose, and apparent language/origin.
  • Cross-references were measured by objective evidence.
  • The last Git change was collected when history is available.
  • Cited paths were verified before accusing drift.
  • Rare items by design were treated as doubts when necessary.
  • Each finding uses only allowed labels.
  • Each finding cites concrete evidence and, when useful, a line.
  • Each recommendation uses only allowed actions.
  • The report has the six mandatory sections.
  • The executive summary has at most 10 lines.
  • No existing file was changed.
  • The final report did not overwrite a pre-existing file.
  • The final message explicitly states that the cleanup depends on human decision.

Exception handling

  • No Git available → mark recency as não verificável; do not invent a date.
  • No reports/logs directory → do not treat absence of signal as isolated proof of disuse.
  • Item with no references, but apparently seasonal/release-only → move to “Doubts”.
  • Two documents appear to be duplicates, but there is not enough evidence of precedence → AMBÍGUO only if they objectively dispute the same role; otherwise, “Doubts”.
  • Cited path contains a variable/glob → resolve only if there is unambiguous context; otherwise, “Doubts”.
  • Very large/binary file → inventory it, but record the reading limitation.
  • Repository with thousands of process artifacts → the cross-referencing of collect_evidence.py is quadratic: each item is searched in the body of all the others. Measured: ~0.5 s for 27 items; above ~5,000 files in folders such as sdd/ or reports/ it stops finishing in useful time. In that case do not wait for the script: run it pointing to one subdirectory at a time (for example only .claude/commands and .claude/agents), or do the inventory with git ls-files and measure references with git grep -c. The script is an optional accelerator — the audit does not depend on it.
  • REPORT_PATH already exists → do not overwrite it and do not silently choose another name.
  • Necessary command would have a side effect → do not execute it; record the limitation in “Doubts”.

Examples

Example of a valid finding

Item Label(s) Evidence Recommendation
.claude/commands/old-release.md OBSOLETE, CONFLICTING Line 18 writes specs to docs/specs/, while the main SDD defines .claude/sdd/specs/; the old path does not exist; last commit: 2025-11-03. RETIRE

Example that should become a doubt

An agent has zero incoming references and no recent mention in logs, but its description says it is only used in the annual release. Do not classify it as NÃO UTILIZADO with certainty; record it in “Doubts for the repo owner”.

Part of SDD Open by RDD — https://github.com/robertodiasduarte/sdd-open