audit

Files (1)

• SKILL.md

SKILL.md (first lines)

# /plumbline:audit

Run the Plumbline lint across the current project and analyze the findings.

## What this does

1. Run `plumbline .` from the project root.
2. Capture the violation report (exit 0 = clean, 2 = violations, 1 = internal error).
3. Group violations by check category and by file.
4. Distinguish:
   - **comment-hygiene** — comments that are not a machine directive, not a configured citation, and not a docstring in an opt-in file. Default action is delete; a small share will be load-bearing and want conversion to an assertion / test / type / name. Use `/plumbline:suggest` for per-violation proposals.
   - **citation-unresolved** — a comment uses a project-configured citation tag (e.g. `@concept:`, `@story:`), but the slug after the tag does not resolve. Either correct the slug, create the artifact at the resolved path, or remove the citation.
5. Surface a summary back to the user with a proposed remediation plan; do not apply fixes without confirmation.

## Run

```bash
set +e
output=$(node "${CLAUDE_PLUGIN_ROOT%/}/bin/plumbline" . 2>&1)
exit_code=$?

echo "$output"
echo "---"

if [ "$exit_code" -eq 0 ]; then
  echo "audit: clean — no Plumbline violations"
  exit 0
fi

if [ "$exit_code" -ne 2 ]; then
  echo "audit: lint failed with internal error (exit $exit_code)"
  exit "$exit_code"
fi

total=$(echo "$output" | grep -c "plumbline/")
echo "audit: $total violation(s)"

echo
echo "by category:"
echo "$output" | grep -oE "plumbline/[a-z-]+" | sort | uniq -c | sort -rn | sed 's/^/  /'

echo
echo "top files:"
echo "$output" | grep "plumbline/" | awk -F: '{print $1}' | sort | uniq -c | sort -rn | head -10 | sed 's/^/  /'

exit 0
```

## Reporting to the user

After the script completes, present:

- The totals and category breakdown the script printed.
- For each violation category, propose a remediation approach the user can authorize:
  - **comment-hygiene** — usually a sweep; offer to batch-delete or run `/plumbline:suggest` for the few load-bearing ones that warrant conversion to code.
  - **citation-unresolved** — for each tag, list the unresolved slugs and propose either correcting the slug, creating the missing artifact, or removing the citation.

Do not begin applying fixes until the user authorizes a specific category or file scope.

From fallguyconsulting/plumbline, Apache-2.0.

More from fallguyconsulting/plumbline