Check Conventions

Purpose

Provide a deterministic, rule-driven compliance check that maps every ALWAYS/NEVER/MUST directive from the project's convention rules onto concrete lines in the target file. Complements /check-conventions command and the codebase-conventions-reviewer specialist.

When to Invoke

• Before pushing a file that touches API, frontend, Terraform, or Alembic.
• During PR self-review to pre-empt convention feedback.
• As a gate inside the Quality Gate Pipeline skill.

When NOT to Invoke

• On generated files (OpenAPI, migrations autogenerated via Alembic, .next/).
• For design-intent questions (use ADR flow instead).
• For files outside tracked rule scopes (vendored libs, fixtures).

Inputs

• target: active file or explicit path.
• scope (optional): file (default) or diff (added lines only).

Procedure

1. Resolve target. Determine its rule scope (api, frontend, infra, docs) by path.
2. Load applicable rules from documentation/rules/*.md and .cursor/rules/*.mdc.
3. Extract each ALWAYS / NEVER / MUST directive as a check.
4. For each check, search the target for the pattern (literal, regex, or structural).
5. Report matches as PASS, violations as FAIL with line number and the directive text.
6. If scope=diff, filter to lines added in the current git diff.
7. Emit the output format below. Do not modify files.

Outputs

Check Conventions — api/src/services/opportunity_service.py
Rule scope: api
Rules loaded: 14 (documentation/rules/api-*.md)

FAIL  L42  MUST: services return domain models, not ORM rows (api-services.md)
FAIL  L88  NEVER: raw SQL in service layer (api-data-access.md)
PASS  —   ALWAYS: service methods have type hints
PASS  —   ALWAYS: exceptions subclass ApiError

Summary: 2 failures, 12 passes. Block merge: yes.

Safety

• Read-only.
• Never invents rules; only reports what is in the loaded rule files.
• Cites the rule file name and directive verbatim so the author can verify.
• FedRAMP / PII rules are always loaded when the target lives under api/src/.

Examples

Example 1 — API service check. Flags a raw SQL string in a service; cites api-data-access.md.

Example 2 — Frontend component check. Flags a hard-coded color literal that violates USWDS-token directive.

Example 3 — Diff-only scope. In a large legacy file, checks only the added lines so pre-existing violations don't block the PR.

Related

• .cursor/commands/check-conventions.md — the original command.
• .cursor/skills/quality-gate/ — invokes this skill as one gate.