suede-code

Files (11)

• CARD.md
• SKILL.md
• openai.yaml · agents/
• maintainability-baseline.md · references/
• security-baselines.md · references/
• threat-verify.md · references/
• traps-swift-ios.md · references/
• traps-web.md · references/
• worked-example-grade-only.md · references/
• worked-example.md · references/
• commit-dirt-scan.sh · scripts/

SKILL.md (first lines)

# Suede AI Code Skills

One skill for judging code: what is wrong, and whether it ships. Every finding
has a file, evidence, and a fix path. Every grade has the evidence that earned
it. No finding without evidence; no volume without signal.

**Runs only when asked.** Never fire this as a side effect of a diff, a save,
or a commit.

## Compatibility

An agent with repository read access and Git; Bash is needed for local tests and the bundled commit-dirt scan. Fix mode additionally needs authorized file edits. Review can proceed with explicitly unverified runtime checks when execution is unavailable.

## Gate policy: advisory, not blocking

Every check, grade, and ship verdict here is a recommendation to the user, not
a control on the agent.

- Run every check and report results honestly. `ship`, `ship-with-caveats`,
  `hold`, letter grades, and BLOCKED items are advice attached to the work.
- Never block, delay, skip, or rewrite the action the user asked for because a
  gate said hold. A failed gate changes what you report, never what you do.
- Single exception: an extreme-risk finding (data loss, credential exposure,
  legal or rights violation, payment mistake, irreversible public damage).
  Pause, state the risk and the options, and let the user pick. Their choice
  is final.

## Pick the mode

| Request sounds like | Mode | Emits |
|---|---|---|
| "review and grade", "is this safe to ship", "check this PR" | **full** (default) | Findings, grade, deploy safety, commit dirt, ship gate |
| "findings only", "no grade", "line by line", "find the bugs" | **`--findings-only`** | Findings, deploy safety, commit dirt, ship gate. No letters. |
| "grade only", "give it a letter", "A-F verdict", "should this merge" | **`--grade-only`** | Lane grades, caps, required upgrades, ship gate. No findings list. |

Grade-only still runs Step 1 (Instant-F) and still reads the code. It skips
the itemized findings output, not the investigation.

Other modes that combine with any of the above:

- **Plan review:** nothing built yet; check scope, sequencing, acceptance
  criteria, test mapping, and missing decisions.
- **Fix verification:** after fixes, rescan only the changed files and confirm
  each original finding is gone.
- **Release review:** add build, secrets, env, public copy, screenshots,
  metadata, and live or API readback.
- **`--fix`:** apply fixes (see Fix Mode).
- **`--threat-verify`:** confirm declared threat-model mitigations exist.
  Procedure in `references/threat-verify.md`; read it only in this mode.

**Depth** (state it at the top of every output):

- `--quick` (about 2 min): pattern scan for obvious bugs, secrets, missing null
  checks, injection, broken error handling. No cross-file analysis.
- `--standard` (default, about 10 min): per-file correctness on changed paths,
  language traps, state handling, test coverage of changed behavior, call graph
  within changed files, maintainability baseline.
- `--deep` (about 25 min): full import graph, call-chain tracing, whole-repo and
  history pass, critic lanes. Use for auth, payments, migrations, public APIs.

Model: Sonnet by default. Recommend Opus for auth, payments, and public API
surfaces.

## Pre-flight

Name three things before analysis:

- **Target:** repo, branch, PR, commit range, diff, route, API, or release build.
- **Intent:** what the change claims to do. Find the spec in this order: issue
  references in commits and PR body (`#123`, `Closes #45`), a path the caller
  passed, a matching file under `docs/` or `specs/`. If none exists, write
  "no spec available" and judge intent from the PR description alone. Never
  invent requirements.
- **Risk lanes:** frontend, backend, data, auth, payments, contracts, iOS,
  release, public copy, analytics, secrets, deployment, docs.

Pin the comparison point and prove it is reviewable: `git rev-parse <base>`
resolves, diff with three dots (`git diff <base>...HEAD`) so the comparison
runs against the merge-base, and the diff is non-empty. A bad ref or empty
diff fails here in one line.

## Context graph

Build it before judging the diff:

1. Changed files and generated files.
2. Imports, callers, routes, handlers, jobs, hooks, models, schemas, and
   config or env dependencies the change touches.
3. Tests, fixtures, migrations, release scripts, docs, and screenshots that
   should move with the behavior.
4. Runtime surfaces: local route, live URL, API endpoint, simulator flow,
   dashboard, store metadata, deploy target.
5. Domain contracts: ownership, rights and provenance, payments and wallets,
   agent commerce, and published-statement accuracy.

Flag beyond-the-diff risk when related files, defaults, docs, env, or deploy
requirements no longer agree.

## Run the repo's own gates first

Do not hand-review what a tool already decides. Detect what the repo ships
(`package.json` scripts, config files, lockfiles) and run only that. Never add
a tool the repo does not use. Never report a result you did not run.

| Stack | Type check | Lint | Test | Other |
|---|---|---|---|---|
| Web / Node | `npx tsc --noEmit` | `npm run lint` (changed files) | `npm test` | `npm audit` when deps changed |
| MCP server (Node) | `node --check <server>.mjs` | configured linter | repo MCP tests | One stdio session: `initialize`, `notifications/initialized`, then list/call/read/get |
| iOS / Swift | the build is the check | SwiftLint if configured | XCTest target | `xcodebuild -scheme X -destination 'platform=iOS Simulator,name=<device>' build` |
| API / backend | compile step if any | configured linter | contract or schema tests | OpenAPI validation against the live route |

Severity mapping: a type error on a changed line is P2 (P1 on a critical
path); a failing test on changed behavior is P1; a test that silently stopped
running is P2; a reachable, exploitable dependency CVE is P0 or P1; a verified
live secret is P0; a broken production build in a release review is P0.

Cite command, exit status, and the file:line it implicates. A gate that cannot
run goes in Verification as "not run" with the reason.

From JasonColapietro/suede-creator-skills, MIT.

More from JasonColapietro/suede-creator-skills